scaccogatto/okf-skills

The OKF toolkit for Claude Code — author, maintain, validate & visualize Open Knowledge Format bundles. Plugin, agent skills, and a GitHub Action.

📚 okf‑skills – Open Knowledge Format (OKF)를 위한 Claude Code 플러그인 & 스킬 세트

개요 – Claude 기반 코딩 에이전트(Claude Code, Cursor, Codex 등)가 Open Knowledge Format (OKF) v0.2로 작성된 지식 번들을 생성, 검증, 유지 관리 및 시각화할 수 있도록 해주는 작은 오픈 소스 툴킷입니다. 이 저장소에는 세 가지 Claude Code 스킬(okf, validate, visualize), Claude 마켓플레이스 플러그인, CI 게이팅용 GitHub Action 및 자체 포함형 HTML 그래프 렌더러가 제공됩니다.

중요성 – OKF는 구글이 발표한 벤더 중립적인 새로운 방식으로, 구조화된 지식을 YAML front‑matter가 포함된 일반 텍스트 Markdown 파일로 저장합니다. 사양을 Claude의 워크플로우에 직접 통합함으로써 개발자는 문서, 설계 결정, 메트릭 등을 에이전트가 읽고, 업데이트하고, 추론할 수 있는 형식으로 유지하면서도 여전히 사람이 편집할 수 있고 버전 관리가 가능한 상태를 유지할 수 있습니다.

Key components

Component Role
/okf:okf skill 프롬프트에서 OK‑OKF 번들을 생성하거나 업데이트합니다(예: "OKF로 인증 서비스 문서화").
/okf:validate skill OKF v0.2 사양에 대해 결정론적 적합성 검사기를 실행합니다(엄격 모드에서는 빌드가 실패할 수 있음).
/okf:visualize skill 번들을 viz.html로 변환합니다. 이는 대화형이며 백엔드가 필요 없는 그래프로, 각 노드는 렌더링된 Markdown, 신뢰 등급, 최신 상태, 출처 및 백링크를 표시합니다.
action.yml CI에서 번들을 자동으로 검증하기 위해 모든 저장소에 추가할 수 있는 복합 GitHub Action(Claude가 설치되지 않은 경우에도 가능).
templates/CLAUDE‑okf.md 프로젝트의 CLAUDE.md에 추가하면 Claude가 작업 전에 번들을 자동으로 사용하고 변경 후에 업데이트를 다시 작성하도록 하는 스니펫.
.okf/ directory (self‑documented) 라이브 데모 및 유효성 검사기/시각화기에 대한 내부 테스트에 사용되는 예제 번들.

Installation & quick start

# As a Claude Code marketplace plugin
/plugin marketplace add scaccogatto/okf-skills
/plugin install okf@scaccogatto

# Or as a generic Claude skill via skills.sh (works for Cursor, Codex, etc.)
npx skills add scaccogatto/okf-skills

Local development – 저장소를 복제하고 claude --plugin-dir /path/to/okf-skills를 사용하여 Claude를 해당 위치로 지정합니다.

Typical workflow

  1. 번들 Create / update:
    /okf:okf produce .okf          # Claude writes markdown files under .okf
  2. 커밋 전 Validate:
    /okf:validate .okf --strict    # fails on any spec violation
    (제공된 GitHub Action을 통해 CI에서 실행할 수도 있습니다.)
  3. 지식 그래프 Visualise:
    /okf:visualize .okf -o viz.html --title "My project" --link "https://github.com/me/project"
    아무 브라우저에서나 viz.html을 엽니다 – 서버가 필요하지 않습니다. 노드는 딥 링크가 가능합니다(viz.html#services/auth-api).
  4. Keep it fresh – .okf/index.md에 upkeep: enforced를 추가하여 번들이 업데이트되지 않은 경우 Claude가 작업을 차단하도록 하거나, CLAUDE‑okf.md의 소프트 모드 스니펫을 사용하여 자동 백그라운드 업데이트를 수행합니다.

How it works under the hood

  • Spec‑driven – 저장소에는 전체 OKF v0.2 사양(skills/okf/reference/SPEC.md)이 벤더링되어 있습니다. 모든 스킬은 결정론적 동작을 보장하기 위해 이 파일을 읽습니다.
  • Zero‑config Python scripts – 검증 및 시각화는 순수 Python 스크립트(okf_validate.py, okf_visualize.py)이며 uv(또는 일반 python3 + pyyaml)로 실행됩니다. 외부 서비스가 필요하지 않습니다.
  • Self‑contained graph – 시각화 도구는 Markdown, 계산된 신뢰 등급, 최신 상태 배지 및 백링크 데이터가 포함된 단일 HTML 파일을 작성합니다. 모든 것이 클라이언트 측에서 계산되므로 데모 페이지는 데이터를 어디로도 전송하지 않습니다.
  • GitHub Action – action.yml은 유효성 검사 스크립트를 래핑하여 bundle 및 strict/max-warnings 입력을 노출하며, 모든 저장소(Claude가 없는 경우에도)가 OKF 규정 준수를 강제할 수 있도록 합니다.

Who might use this

  • 이미 Claude Code를 사용 중이며 에이전트가 읽고/쓸 수 있는 구조화되고 버전이 관리되는 지식 베이스를 원하는 팀.
  • CI에서 지식 번들의 품질을 게이팅하려는 DevOps / 문서 엔지니어.
  • AI 증강 문서 파이프라인을 실험 중인 연구원 또는 제품 그룹.

License & credits

  • 코드 및 콘텐츠: MIT License © Marco Boffo (@scaccogatto).
  • OKF 사양: Apache‑2.0, Google Cloud의 Knowledge Catalog 저장소에서 가져오고 저작자 표시.

Quick links

  • Live demo – https://scaccogatto.github.io/okf-skills/
  • OKF spec (v0.2) – skills/okf/reference/SPEC.md
  • GitHub Action – action.yml
  • Installation commands – 위의 Installation 섹션을 참조하십시오.

관련

  • 프로젝트
    Prorise-cool/Claude-Code-Multi-Agent

    Claude Code Multi‑Agent는 Anthropic의 Claude Code 프로젝트에 인식 능력과 전문가 에이전트 기능을 제공하는 오픈소스 프레임워크입니다. Python Hook 시스템과 로컬에서 실행되는 Ollama 모델을 사용해 코드베이스 유형을 자동 감지하고, 사용자 의도를 분석하며, 300개 이상의 도메인 전용 "스킬"(백엔드, 프론트엔드, 테스트, 보안 등)을 로드하고, 자동 문서화(DEVELOPMENT.md, KNOWLEDGE.md, CHANGELOG.md)를 강제합니다. 리포지토리를 클론하고 Ollama, 모델, uv를 설치한 후 프로젝트를 리포지토리에 넣기만 하면, Claude Code는 즉시 컨텍스트를 이해하고 적절한 도구를 제안하며, `/backend‑specialist` 또는 `/kiro/spec`와 같은 슬래시 명령어로 조작할 수 있습니다. 주요 특징: - 제로 설정 시작; 모든 설정은 `.claude/settings.json`과 `prompts.json`에 저장. - 세션 시작, 사용자 프롬프트, 도구 사용 등에 따라 실행되는 Hooks로 프로젝트 감지, 의도 분석, 문서 업데이트 처리. - Skills는 `SKILL.md` 파일로 정의되며 자동 탐지됨. - 외부 API를 전혀 사용하지 않고 완전히 로컬에서 동작. Git과 통합 가능. MIT 라이선스. 개인 개발자나 소규모 팀이 재현 가능하고 온프레미스 AI 코딩 보조 도구를 원할 때 이상적입니다.

  • 프로젝트
    sangrokjung/claude-forge

    A professional equipment pack for Claude Code that adds specialist agents, safety hooks, and automated workflows to transform the terminal AI into a full-scale development kit.

  • 프로젝트
    himself65/trade-skills

    Open Knowledge Format을 사용하여 32개의 함정과 사례를 포함하는 옵션 거래 지식 기반을 제공하는 Claude Code 플러그인

  • 프로젝트
    mhattingpete/claude-skills-marketplace

    Claude Code용 플러그인, 스킬, 에이전트의 엄선된 마켓플레이스로 소프트웨어 엔지니어링 워크플로우를 자동화하고, 토큰 효율적인 대규모 작업을 위한 로컬 실행 런타임을 제공합니다.

  • 프로젝트
    coreyhaines31/makerskills

    makerskills는 의사 결정, 리서치, 도메인 탐색, 개인/기업 지식 베이스, 재무 모델링 및 콘텐츠 제작과 같은 창업자 작업을 위한 20개의 문서화된 "기술(skills)"(소규모 버전 관리 에이전트 워크플로우)이 포함된 Claude Code 플러그인입니다. 플러그인을 설치하고 구성 디렉토리를 설정한 다음 슬래시 명령(예: `/decide`, `/paste`)을 통해 기술을 호출합니다. 각 기술은 `SKILL.md` 파일에 정의되어 있으며 조합이 가능하고 서로를 호출할 수 있습니다. 이 저장소는 문서, 예시 및 명확한 아키텍처를 제공하여 `skillify`, `toolify`, `loopify`를 통해 워크플로우를 확장하거나 예약하면서도 개인 데이터를 저장소 외부로 유지합니다.