OpenKnowledge — 에이전트 가이드
OpenKnowledge (OK)는 MCP를 통해 제공되는 마크다운-CRDT 협업 플랫폼입니다. 이 스킬은 OK 에이전트 가이드의 단일 출처입니다. 아래의 모든 규칙은 별도로 표시되지 않는 한 MUST입니다. 상세 내용은 references/*.md에 있습니다 — 한 단계 깊이; 해당 작업이 필요할 때 참조 문서를 로드하세요.
스킬 버전은
@inkeep/open-knowledge-server를 추적합니다.cat ~/.ok/skill-state.yml은 설치된 내용을 보여줍니다.ok seed는@inkeep/open-knowledge>= 0.4.0이 필요합니다;unknown command오류가 발생하면npm install -g @inkeep/open-knowledge를 실행하세요.
설정 (아직 연결되지 않음?).
mcp__open-knowledge__*도구를 클라이언트에서 사용할 수 없다면, 이 프로젝트가 이 머신에 연결되지 않은 것입니다 —references/setup.md에서 단계별 가이드(.mcp.json승인 →ok startCLI → 선택적 데스크톱 앱)와 표준 빠른 시작을 확인하세요.
TL;DR — 90%의 경우
- 읽기: 단일 문서의 경우
exec("cat …"), 디렉토리의 경우exec("ls -A …")(폴더 기본값 + 템플릿 메뉴), 리터럴 검색의 경우exec("grep …"), 순위 기반 검색의 경우search를 사용합니다. 네이티브Read/Grep은 소스 코드(.ts/.py/ …)에만 사용하고, 인스코프.md/.mdx에는 절대 사용하지 않습니다. - 쓰기: 새 문서 또는 전체 교체의 경우
write({ document: { path, content } }); 본문 find/replace의 경우edit({ document: { path, find, replace } }); 프론트매터 병합-패치의 경우edit({ document: { path, frontmatter } })(null은 키를 삭제합니다).delete({ document })는 제거,move({ from, to })는 이동/이름 변경입니다. 본문 find/replace는 본문 전용입니다. 모든 콘텐츠 쓰기 작업 시 한 줄summary(≤80자, 사용자 대상 결과)를 전달하세요. - 미리보기: 모든 읽기/쓰기 응답에는 경로 전용
previewUrl(/#/<doc>, 호스트:포트 없음)이 포함됩니다. 세션 시작 시 브라우저를 한 번 여세요. 편집 확인을 위해preview_screenshot을 사용하지 마세요 — 도구 응답이 확인입니다. 전체 다중 호스트 계약:references/preview.md. - 워크플로우 가이드:
workflow({ kind: 'ingest' | 'research' | 'consolidate' | 'discover' })는 데이터가 아닌 절차적 가이드를 반환합니다. 작업이 해당 레이어에 적합할 때 사용하세요. - 직접 질문: 일반적인 비즈니스 질문("어떤 고객이…", "우리가 …에 대해 무엇을 결정했나요?")은
search/exec+ 인용된 채팅 답변으로 라우팅됩니다 — "research" 키워드가 필요하지 않습니다. 내구성이 있고, 여러 문서에 걸쳐 있으며, 이미 다루어지지 않은 경우에만 저장하고, 먼저 제안하세요.references/corpus-qa.md참조. - 스킬 작성 또는 개선 ("스킬을 작성/만들기", "이 스킬 개선", "이것을 스킬로 전환"): 중지하고
open-knowledge-write-skill스킬을 호출하세요 — 이 스킬이 범위 선택(프로젝트 대 글로벌), SKILL.md 계약, 평가 및 설치를 소유합니다; 이 스킬에서 즉흥적으로 하지 마세요.skill대상을 통해 작성하세요(write({ skill })), 절대 원시.ok/skills/…문서를 통하지 마세요..claude/skills/·.cursor/skills/·.codex/skills/·.opencode/skills/·.agents/skills/아래의 설치된 프로젝션을 절대 읽거나, 비교하거나, 편집하지 마세요 —install이 이를 생성하고 다음 동기화 시 덮어씁니다; 이는 진실의 출처가 아닙니다.
도구 색인 — 19개 도구 (라우터; MCP 도구 설명은 각 도구의 전체 계약을 전달합니다)
- 읽기 —
exec(기본; 읽기 전용cat/ls/grep/find/head/tail/wc/sort/uniq/cut+ 프론트매터/백링크/히스토리 강화; 하나의 명령어 또는 하나의 파이프, 셸 아님),search(순위 기반 BM25 + 최신성),history(문서 버전),links(kind: backlinks|forward|dead|orphans|hubs|suggest, 또는 한 번의 호출 감사를 위한 배열),skills(스킬 찾기 + 읽기:name을 생략하면 프로젝트 + 글로벌의 모든 스킬을 LIST,name을 전달하면 하나를 READ —name+scope로 주소 지정, 절대 경로로 하지 않음),config(해결된 설정),palette(마크다운 네이티브 작성 양식 +html preview시작점 + 테마 토큰; JSX 스키마의 경우palette({ components })),preview_url(요청 시 브라우저 미리보기 URL),share_link(GitHub 기반 공유 URL; 읽기 전용, GitHub 원격이 없으면 오류). - 쓰기 — 네 가지 네이티브 CRUD 동사,
document/folder/template/skill/asset에 대해 다형성 (정확히 하나의 대상을 전달, 주소 키 아래에 중첩):write(생성/덮어쓰기;write({ skill: { name, description, body, scope? } })는 스킬을 작성 →.ok/skills/<name>/SKILL.md,install까지 초안),edit(본문 find/replace 또는 프론트매터 병합-패치; 자산 없음),delete(제거),move(이동/이름 변경, 참조자 다시 쓰기; 스킬은 또한scope/toScope를 사용하여 Project↔Global 이동 — 히스토리 재설정, 다시install). 출력은 입력 대상 키를 미러링합니다; 미리보기 엔벨로프(previewUrl,warning)는 최상위에 유지됩니다. 추가로install(스킬에 대한 초안 → 설치 단계 — 편집기에 프로젝션;write({ skill })후 실행),checkpoint(명명된 버전),restore_version(롤백). 폴더의 프론트매터는 개방형이며 자체 전용입니다 (계단식으로 전파되지 않음); 템플릿은 새 문서가 시작하는 내용입니다. 스킬을 작성/개선?open-knowledge-write-skill호출 (TL;DR #6), 즉흥적으로 하지 마세요. - 충돌 —
conflicts(kind: list|content),resolve_conflict(해결 방안 작성 + 커밋; 파괴적).references/conflict-resolution.md참조. - 워크플로우 —
workflow(kind: ingest|research|consolidate|discover; 절차적 가이드, 데이터 아님).references/workflow-guides.md참조.
오용 시 자체 수정: JSON Schema가 표현할 수 없는 제약 조건("정확히 하나의 대상", "find에는 replace 필요", 본문-XOR-프론트매터)은 한 줄의 수정 형식과 함께 isError: true를 반환합니다. 그것을 읽고 해당 형식으로 재시도하세요; 추측하지 마세요.
OK MCP에 없는 도구 (호스트의 것): preview_start, preview_screenshot, WebFetch, WebSearch, 네이티브 Read / Grep / Glob / Edit. STOP 규칙은 인스코프 마크다운에 대해 어떤 것을 사용할 수 있는지 규율합니다.
중지 — 인스코프 .md / .mdx에 대한 네이티브 도구
인스코프 마크다운 읽기 및 쓰기 모든 것을 OK의 MCP 도구를 통해 라우팅하세요 — 호스트의 네이티브 파일 도구를 절대 사용하지 마세요. 인스코프 마크다운에 대한 네이티브 Edit / sed / 직접 Write는 CRDT를 우회하고 섀도 리포지토리에서 에이전트 속성을 잃습니다; 네이티브 읽기는 OK가 일치하는 모든 파일에 대해 반환하는 프론트매터, 백링크, 섀도 리포지토리 활동 및 프로젝트 git 히스토리를 건너뜁니다. 이 작업 공간에 OpenKnowledge MCP가 구성된 경우, 콘텐츠 디렉토리 내의 마크다운 경로에 대해 네이티브 파일 도구를 사용하지 마십시오. 이 금지는 모든 일반적인 합리화를 포함합니다:
- 인스코프
.md/.mdx에 대한 네이티브Read/Grep/Glob— 원래 경우. - 인스코프 마크다운을 포함하는 디렉토리에 대한
Bash ls/Bash find/Bash cat—exec("ls -A …")/exec("find … -name '*.md'")/exec("cat …")를 사용하세요. 네이티브는 이름만 반환합니다;exec는 프론트매터, 백링크 수 및 최근 활동을 반환합니다.-A는./..노이즈 없이 숨겨진 항목(.ok/,.okignore)을 보여줍니다. - 마크다운을 대상으로 하는 Glob 패턴 (
**/*.md,specs/**,reports/**,docs/**) —exec와find또는exec("ls -A <dir>")를 사용하세요. - 마크다운 중심 탐색을 위해 Explore / 일반 목적 하위 에이전트에 디스패치 — 하위 에이전트는 내부적으로 네이티브 도구를 사용하고 OK를 우회합니다.
exec/search를 통해 직접 마크다운 탐색을 수행하세요. 하위 에이전트는 소스 코드 탐색에 적합합니다. .ok/내의 인스코프 마크다운에 대한 네이티브Read/Grep—.ok/는 인스코프입니다; 다른 KB 파일처럼.md/.mdx를 처리하세요..ok/skills/에 대한ls/cat/find로 스킬 검색 또는 읽기 —.ok/skills/는 불투명한 내부 상태입니다; 스킬은name+scope로 주소 지정되며 경로가 아닙니다.skills도구를 사용하세요(name을 생략하여 프로젝트 + 글로벌 목록,name을 전달하여 하나 읽기); 절대.ok/skills/...경로를 탐색하지 마세요.
MCP 도구 가시성 — exec가 보이지 않는 것이 탈출구가 아닙니다. MCP 연결은 클라이언트(Claude Code, Cursor, Codex, Windsurf, VS Code)에 따라 다릅니다. 서버 레이블은 사용자 정의입니다; 도구가 exec라는 최상위 심볼로 나타나지 않을 수 있습니다. OpenKnowledge가 여기에 MCP 서버로 등록된 경우, 클라이언트의 문서화된 MCP 호출(일반적인 "MCP 도구 호출" 흐름 포함)을 통해 해당 exec / search로 마크다운 읽기를 라우팅하세요. 등록이 테스트이며, 최상위 심볼 가시성이 아닙니다.
초기 도구 목록은 완전하지 않습니다 — MCP가 누락되었다고 결론 내리기 전에 도구 검색을 실행하세요. 일부 클라이언트(특히 Codex)는 지연된 tool_search / 도구 검색 단계 뒤에 MCP 도구를 연기하므로, mcp__open-knowledge__*는 사전 도구 세트에 없으며 검색한 후에만 나타납니다. 표시 목록에 없음은 "아직 검색하지 않음"을 의미하며, "등록되지 않음"을 의미하지 않습니다. 도구가 보이지 않으면, 첫 번째 조치는 클라이언트의 도구 검색 / tool_search를 open-knowledge (또는 exec / search / write)에 대해 실행하는 것입니다 — 초기 목록에서 사용 불가능을 추론하지 마세요.
탈출구. .md / .mdx에 대한 네이티브 Read / Grep / Glob은 오직 도구 검색(위) 후 이 프로젝트에 OpenKnowledge MCP 서버가 등록되지 않은 경우, 또는 실제로 MCP 호출을 호출했고 실패한 직후에만 허용됩니다 — 그런 다음 사용자에게 보이는 문장을 OpenKnowledge MCP unavailable:로 시작하세요. "등록되지 않음"은 도구 검색이 빈 결과를 반환한 후에만 도달할 수 있는 결론입니다 — 초기 도구 목록만으로는 절대 안 됩니다. 클라이언트의 MCP 경로를 건너뛰었거나, exec를 최상위 도구로 보지 못했거나, 도구 검색을 실행하지 않았거나, 스킬이 필요하지 않다고 합리화했기 때문에 해치를 절대 사용하지 마세요.
소스 코드 및 비마크다운 파일 (.ts, .py, package.json, …): 네이티브 Read / Grep / Glob은 항상.
읽기 — 예시
- 파일 읽기:
exec("cat <path>.md")— 내용 + 전체 강화. - 디렉토리 목록:
exec("ls -A <dir>")— 하위 항목별 프론트매터, 재귀적 마크다운 수, 하위 디렉토리별 가장 최근 업데이트된 문서, 폴더 자체의title/description/tags+templates_available. 일반ls보다-A를 선호합니다. - 리터럴 검색:
exec("grep -rn <term> <dir> | head -5")— 일치 + 일치하는 파일에 대한 강화. - 순위 기반 검색:
search({ query })— 제목 부스트 + 본문 BM25 + 최신성; 모든 항목을 나열할 때가 아니라 가장 좋은 문서를 선택할 때 사용하세요.
쓰기
콘텐츠가 준비되는 즉시 write / edit을 호출하세요 (STOP 규칙에 따라 MCP를 통해 라우팅).
점진적으로 저장하세요 — 지식 베이스가 체크포인트입니다 (MUST). 다단계 또는 장기 실행 작업(연구 조사, 다중 소스 합성, 문서 배치)에서 각 단위(섹션별, 소스별, 문서별)를 완료할 때마다 완료된 작업을 KB에 쓰세요. 완료된 결과를 컨텍스트에만 보유하고 마지막에 한 번에 쓰지 마세요. 작업 중간에 속도 제한, 충돌 또는 컨텍스트 압축이 발생하면 아직 쓰지 않은 모든 것이 손실됩니다; 이미 저장된 작업은 유지되며, 문서를 다시 읽어서 재개합니다. 대상 문서를 조기에 생성(골격 + 프론트매터)한 다음, 각 섹션이 확정됨에 따라 edit하세요.
모든 콘텐츠 쓰기에 summary를 전달하세요 (SHOULD) — 타임라인 항목이 되는 한 줄(≤80자) 사용자 대상 변경 노트입니다. 프로스보다 요점을 더 잘 전달하는 곳에서는 시각적 구조 (Callout, mermaid, 테이블, html preview)를 사용하세요; 초안을 작성할 때 palette를 호출하세요. 권고적 쓰기 경고, MDX 작성, 삭제/이동 메커니즘 및 시각적 작성: references/writing.md + references/components-and-visuals.md + references/media-and-assets.md.
근거 — 모든 사실 주장에는 출처가 필요합니다 (MUST)
지식 베이스 문서는 사실적인 인공물입니다. 모든 주장은 추적 가능해야 하며, 출처는 지식 베이스 내에 있어야 하고 공개 웹에 떠 있어서는 안 됩니다.
- 지식 베이스는 진실의 출처입니다 — 폐쇄 루프. 외부 출처는 실시간 웹에 인용되지 않습니다;
ingest를 통해 가져온 다음 로컬에서 인용됩니다. KB 문서 내의 단순[source](https://...)URL은 완성된 인용이 아닙니다 — 이는 "이 출처를 아직 수집해야 함"을 의미하는 TODO입니다. 체인은 모든 잎이 로컬 문서인 경우에만 작동합니다. - 모든 사실 주장은 주장 시점에 출처를 인용해야 합니다. 출처 없는 추측은 없습니다.
- KB 문서의 웹 출처 → 페이지를 가져온 다음(호스트
WebFetch/WebSearch), 로컬 문서로ingest한 다음 로컬 경로를 인용하세요:[source name](./path/to/source.md)(로컬 문서는source_url:에 URL을 전달합니다). 인라인[source](URL)은 채팅 편의 기능이며 KB 편의 기능이 아닙니다. - 자체 가져온 횟수. KB에 들어갈 주장을 뒷받침하기 위해 URL을 가져온 경우, 해당 가져오기는 사용자 공유와 똑같이
ingest를 트리거합니다 — 에이전트가 시작했기 때문에 인라인 URL 인용으로 격하하지 마세요. - 내부 상호 참조 → 권위 있는 주장이 있는 OK 문서에 대한 표준 마크다운 링크; 해당 문서는 자체 출처를 인용해야 합니다 (체인은 보존된 로컬 문서에서 종료됩니다).
- 증거가 없는 경우: 웹 검색을 실행하고
ingest하거나, 인라인으로(TODO: needs source)를 표시하거나, 주장을 작성하지 마세요. 날조하지 마세요. 출처 없는 추측은 추적 불가능한 부족 지식으로 썩습니다.
링크 — 표준 마크다운 링크 (MUST)
다른 문서를 명명하는 모든 명사구를 링크하세요 — [text](./relative/path.md) — 그리고 자유롭게 링크하세요. 모든 링크는 작업이 완료될 때까지 존재하는 문서로 연결되어야 합니다 (동일 패스에서 나중에 생성하는 전방 참조는 괜찮습니다; 실제로 존재하지 않는 링크의 경우 언급을 일반 산문 + 추적된 작업으로 남겨두세요). 절대 링크를 백틱으로 감싸지 말고(`[text](./foo.md)`는 버그입니다) HTML <a>를 절대 사용하지 마세요. 모든 write/edit 응답에서 brokenLinks를 읽으세요: []는 모든 링크가 해결됨을 의미합니다; 채워진 목록은 각 끊어진 href + reason (no-such-doc / no-such-file / unresolvable)을 명명합니다 — 후속 edit에서 수정하세요. links({ kind: "dead" })는 권위 있는 최종 상태 감사입니다 (편집기의 빨간 밑줄은 슬러그 허용 오차가 있으며 거짓말을 하므로 도구를 신뢰하세요). 외부 웹 출처는 인라인 본문 링크가 아닙니다 (근거 참조). 전체 규칙 세트 + [[Page]] 레거시 참고: references/linking.md.
폴더, 프론트매터, 템플릿
모든 .md / .mdx는 YAML 프론트매터가 필요합니다 — title + description 필수, tags 권장. 두 가지 옵트인, 중첩된 폴더 메커니즘: 폴더 프론트매터 (<folder>/.ok/frontmatter.yml — 폴더 자체의 개방형 속성; 자체 전용, 계단식 전파되지 않음
…
[번역을 위해 잘림]