Skip to content

docs: add an agent skill for driving okf - #37

Open
ebertti wants to merge 1 commit into
okfcli:mainfrom
ebertti:add-okf-agent-skill
Open

ebertti wants to merge 1 commit into
okfcli:mainfrom
ebertti:add-okf-agent-skill

Conversation

@ebertti

@ebertti ebertti commented Sep 29, 2026

Copy link
Copy Markdown

What

Adds skills/okf/, a Claude Code skill (SKILL.md + two reference files) that teaches an agent the OKF authoring loop with this CLI: orient (list/search), write a concept, gate with validate/lint, regenerate with index, audit with graph/backlinks. Plus a short "Agent skill" section in the README with install instructions.

No Go code, no new dependencies, no CLI behavior change, so no tests to add.

Why

The README says okf is built to be driven by agents. A skill is the piece that tells an agent when to reach for it and how to sequence the commands, including the traps: a non-reserved .md without frontmatter aborts the whole bundle load, verified with a human: actor must not be written on someone's behalf, and okf schema is the source of truth for the CLI surface.

Verification

  • Ran the released v0.5.0 binary against a scratch bundle to confirm the command behavior and JSON shapes described in the skill.
  • Pasted every template from references/templates.md into a bundle created with okf init: okf validate reports valid: true, 0 errors.
  • Not tested: installing the skill in a live Claude Code session.

Notes for review

  • The skill tells agents to write stale_after as YYYY-MM-DD, because v0.5.0 rejects the spec's datetime form (validate rejects the spec's own §5.5 example for stale_after (datetime), demands YYYY-MM-DD #34). It links that issue so the note can be dropped when it is fixed.
  • I added a top-level skills/ directory. If you would rather keep it under docs/ or elsewhere, I am happy to move it. CONTRIBUTING suggests an issue first for non-trivial changes; I judged this docs-only, but say so if you want one opened.
  • Drafted with Claude Code; I reviewed the content and ran the checks above.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant