| name | okf-author |
| description | Create or update OKF concepts for domain knowledge and agent/harness graphs. Use when documenting tables, metrics, agents, workflows, decision records, shared state, tools, ticket links, playbooks, or runbooks. Supports provenance, trust, lifecycle, and proper absolute Markdown linking. |
OKF Author
Author high-quality OKF concept files that work as both knowledge nodes and agent-graph nodes.
Rules
- Every concept file must have YAML frontmatter with at least
type.
- Always include
title, description, and timestamp (ISO-8601).
- Prefer recommended types (see below).
- For derived or agent-generated content, set
generated: true and populate sources.
- Use absolute Markdown links:
[Label](/path/to/concept.md).
- When the concept is an agent or workflow, document inputs, outputs, routing, and shared state.
- After writing, offer to run validation and impact analysis on the new/changed concept.
Recommended types
Knowledge: Dataset, Table, Metric, Playbook, Runbook, API, Reference
Graph-engineering / harness: AgentNode, Workflow, Harness, DecisionRecord, SharedState, ToolCapability, TicketLink
Process
- Clarify concept purpose, type, and placement (directory under the OKF bundle).
- Choose a stable path/slug (
agents/researcher.md, knowledge/orders-table.md).
- Fill frontmatter from templates in
templates/.
- Write a concise body: overview, key sections, related links.
- Update parent
index.md catalog entry if one exists.
- Append a one-line entry to
log.md.
- Validate (prefer
okf validate; fallback okf-graph.py validate).
- If this is an update to an existing high-degree node, run impact analysis.
Optional richer links (non-breaking)
Skills interpret plain Markdown links first. Optional frontmatter form:
links:
- target: /agents/researcher.md
rel: routes_to
- target: /knowledge/orders.md
rel: depends_on
- target: /tickets/mvp-plugin-scaffold.md
rel: tracks
Common rel values: depends_on, routes_to, implements, documents, uses, owns, supersedes, related_to, tracks, maps_to.
Deep reference: references/typed-edges.md.
TicketLink (WikiTicket / worklog)
When bridging to SLDC systems, use type: TicketLink with worklog_id and optional external_id / external_system.
bin/worklog fold | python3 "${CLAUDE_PLUGIN_ROOT}/scripts/okf-ticket-link.py" emit --bundle <bundle> --open-only
Deep reference: references/ticketlink-sldc.md. Template: templates/ticket-link.md.
Provenance & trust
| Field | Purpose |
|---|
verified | Human or CI confirmed correctness |
status | active, draft, deprecated, proposed, accepted |
stale_after | ISO date after which content should be rechecked |
generated | true if agent-authored |
sources | List of upstream concept paths or URLs |
owners | Optional team or person tags |
Templates
See templates/ for AgentNode, Workflow, DecisionRecord, SharedState, knowledge, and TicketLink skeletons.
Done when
- File written with complete frontmatter and at least one meaningful body section
- Catalog/index updated if applicable
- Links resolve (or known TODOs are marked clearly)
