Communitygithub.com

okf-loom — 저장소-지역 스킬

마크다운 문서 번들을 검증된 OKF 지식 그래프로 변환하는 툴킷입니다. 로컬 스튜디오, 정적 사이트 출력 및 에이전트 친화적인 CLI를 제공합니다.

okf-loom — 저장소-지역 스킬란 무엇인가요?

okf-loom은 Open Knowledge Format(OKF) 번들을 조작하기 위한 저장소-지역 스킬입니다. 마크다운 개념 파일의 유효성 검사, 검색, 발견, 업데이트, 라이브 협업 스튜디오 제공, 정적 사이트 생성 및 에이전트 기반 저작을 지원합니다. 클로드 코드, 커서, 코덱스 등의 AI 에이전트와 함께 사용하도록 설계되었으며, 설치된 패키지 대신 체크아웃-로컬 스크립트(`scripts/okf-loom`)를 통해 실행됩니다. 주요 기능으로는 번들 부트스트랩, 엄격한 유효성 검사, 하이브리드 검색, 라이브 스튜디오 서빙(로컬 및 터널 모드), 댓글 기반 협업 루프 등이 있습니다. 콘텐츠 변경은 원자적이고 마커-세이프하며, 스튜디오 세션이 활성화된 동안에는 변경 내역 추적 및 실행 취소가 가능한 변형자(mutator) 사용을 권장합니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add ojamin/okf-loom

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

okf-loom — 저장소-지역 스킬은(는) 무엇을 하나요?

이 저장소가 스킬입니다. 클론하고, 이 SKILL.md를 로드한 다음, 아래에 나와 있는 소규모 리소스 파일과 체크아웃-로컬 스크립트를 사용하세요. 배울 패키지 게시 워크플로는 없습니다. 지속적인 아티팩트는 이 git 저장소 레이아웃입니다.

기본 동작 (요청 없이 수행할 것)

이 스킬을 사용하는 모든 에이전트에 대한 상시 기대사항입니다.

  1. 문서는 OKF 번들입니다. 사용자가 문서, 노트, 지식 베이스 또는 "이것을 정리해줘"를 요청하면 OKF 개념으로 작성하세요 — 각 개념은 하나의 마크다운 파일이며 완전한 프론트매터(type, title, description, tags, timestamp 및 실제 정보를 담고 있는 경우 aliases/entities/relations/provenance/citations)를 포함합니다. 새 번들은 scripts/okf-loom bootstrap <dir>로 시작하거나 기존 번들에 추가하세요. docs-bundle/demo/showcase.md는 완전히 갖춰진 개념의 표준 예시입니다 (렌더링된 상태로 열어 각 키가 왜 필요한지 확인하세요).

  2. 작성 후 검증하세요. 배치 작성 후 scripts/okf-loom validate <bundle>을 실행하고 발견된 사항을 수정하세요; 주기적으로 scripts/okf-loom discover <bundle>을 실행하여 누락된 링크/인덱스/설명을 찾으세요. index.md 파일이 오래된 경우 scripts/okf-loom index <bundle>이 생성된 블록을 재생성합니다 (마커-세이프 — okf:generated 마커 사이만 다시 작성합니다; 마커가 없는 수동 저작 인덱스 텍스트는 대체되므로 git diff를 확인하세요).

  3. 적극적으로 서빙하세요. 렌더링된 위키가 결과물이며 디버그 화면이 아닙니다. 사용자가 문서를 보거나, 읽거나, 검토하거나, 댓글을 달고 싶어 할 때 — 또는 당신이 방문자가 보고 싶어할 만한 번들을 방금 빌드/변경했을 때 — 요청을 기다리지 않고 스튜디오를 시작하고 URL을 알려주세요:

    scripts/okf-loom serve path/to/bundle --no-open          # 로컬: http://127.0.0.1:8787/
    scripts/okf-loom serve path/to/bundle --no-open --tunnel # + 공개 https URL (cloudflared 필요)
    

    --tunnel은 이 머신에 없는 사용자를 위한 https://…trycloudflare.com 링크를 출력하고 터널 호스트를 스튜디오의 크로스-오리진 허용 목록에 자동으로 추가합니다. 사용자에게 텍스트를 선택하여 댓글을 달 수 있다고 알려주세요; 그래프는 /__graph에 있습니다.

  4. 협업 루프를 실행하세요. 스튜디오가 실행 중인 동안 사용자 댓글은 당신의 작업입니다: scripts/okf-loom wait <bundle>은 댓글 또는 변경이 있을 때까지 블록되고, 그런 다음 claim → 편집 → resolve (comment-claim / mutators / comment-resolve)합니다. 첫 번째 루프 전에 resources/studio-agent-loop.md를 읽으세요.

  5. 스튜디오 세션이 활성화된 동안 콘텐츠 변경에는 가변자(mutator)를 선호하세요 (write-concept, set-frontmatter, link-add, entity-add, update): 이들은 속성이 기록되고, 실행 취소가 가능하며, 열린 탭에 실시간으로 브로드캐스트됩니다. 그 외의 경우 직접 파일 편집도 괜찮습니다 — 감시자가 변경을 감지합니다.

빠른 시작

okf-loom/ 내부에서:

scripts/okf-loom --help
scripts/okf-loom validate docs-bundle --strict

일반 문서 검증을 위해 기본 런타임 설치 단계는 필요하지 않습니다. PyYAML이 있으면 사용되고, 없으면 okf-loom은 보수적인 내장 YAML 폴백을 사용합니다.

체크아웃 이름이 okf-loom/인 상위 워크스페이스에서:

okf-loom/scripts/okf-loom validate okf-loom/docs-bundle --strict

예제는 로컬 셸 래퍼나 설치된 콘솔 스크립트 대신 체크인된 헬퍼를 직접 사용합니다.

무엇을, 언제 읽을지

상황읽을 것
항상, 먼저 (60초 오리엔테이션 + 기본 경로)resources/overview.md
번들에 처음 쓰기 전resources/gotchas.md
CLI 동사 실행 / 플래그가 확실하지 않을 때resources/command-reference.md
개념 파일을 수동으로 작성 또는 편집할 때resources/format-basics.md 그 다음 resources/authoring.md
"좋은" 프론트매터가 어떤 모양인지 결정할 때docs-bundle/demo/showcase.md — 작업 예제
검증 실행 실패 또는 CI 게이팅 필요resources/validation.md
검색 모드, 발견, 계획, 정적 빌드resources/advanced-operations.md
스튜디오가 실행 중이고 사용자가 댓글을 달고 있을 때resources/studio-agent-loop.md
scripts/okf_loom/ 아래 런타임 변경resources/architecture-map.md
모호한 모든 것 — 바인딩 계약docs-bundle/reference/spec.md
인간 사용자를 위한 최종 사용자 문서docs-bundle/

저장소 레이아웃

okf-loom/
├── SKILL.md                 # 로드 가능한 스킬 진입점
├── resources/               # 에이전트가 읽을 수 있는 작은 가이드 파일
├── scripts/
│   ├── okf-loom              # 체크인된 헬퍼 명령
│   ├── okf_loom/             # 체크아웃-로컬 런타임 패키지
│   ├── build_skill_archive.py
│   ├── capture_readme_media.py
│   ├── capture_viewer_proof.py
│   ├── capture_signal_controls.py
│   └── lint-js.sh
├── docs-bundle/             # OKF 문서 번들
├── samples/                 # OKF 번들 예제
├── tests/                   # 체크아웃 스크립트용 pytest 증명
├── docs/                    # README 미디어 (docs/media/), 스크린샷, 설계 계획
├── README.md                # 인간 개요
├── AGENTS.md                # AGENTS를 먼저 읽는 에이전트를 위한 얇은 포인터
└── CLAUDE.md                # CLAUDE를 먼저 읽는 에이전트를 위한 얇은 포인터

핵심 명령

# 번들 검증.
scripts/okf-loom validate path/to/bundle --strict

# 검사 / 검색.
scripts/okf-loom info path/to/bundle
scripts/okf-loom search path/to/bundle "고객 주문" --mode hybrid

# 라이브 협업 스튜디오 서빙 (공개 링크를 위해 --tunnel 추가).
scripts/okf-loom serve path/to/bundle --no-open

# 격차 발견 및 안전한 가변 적용.
scripts/okf-loom discover path/to/bundle --out /tmp/okf-suggestions.json
scripts/okf-loom link-add --bundle path/to/bundle --source tables/orders --target tables/customers

# 스튜디오가 실행 중일 때 협업 루프 (현재 스펙 §12).
scripts/okf-loom wait path/to/bundle        # 댓글/변경이 도착할 때까지 블록
scripts/okf-loom comment-claim path/to/bundle <comment-id> --summary "내가 할 일"
scripts/okf-loom comment-resolve path/to/bundle <comment-id> --summary "내가 한 일"

양보할 수 없는 사항

  • scripts/okf-loom을 사용하세요; 설치된 패키지나 콘솔 스크립트를 가정하지 마세요.
  • PyYAML이 있으면 선호되지만, 번들된 폴백은 일반 런타임/문서 검증에 충분하며 지원되지 않는 고급 YAML에서 실패합니다.
  • PyPI/패키지 게시 워크플로를 기본 경로로 추가하지 마세요.
  • 알 수 없는 프론트매터 키와 수동으로 작성된 번들 콘텐츠를 유지하세요.
  • type은 OKF v0.1에서 유일하게 필수인 개념 프론트매터 키입니다.
  • 깨진 링크는 소비자에게 기본적으로 경고입니다; 작성 가변자는 --allow-forward-reference가 명시되지 않는 한 누락된 대상에서 실패합니다.
  • 모든 okf-loom 쓰기는 원자적이고 마커-세이프해야 합니다.

더 자세한 규칙은 resources/gotchas.md를 읽으세요.

관련 스킬