okf-knowledge
暂无简介
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-11
- Stars
- ★ 0
- Forks
- 0
02 资源文件 22
- 参考文档references/conventions-schema.md4.3 KB
- 参考文档references/spec-digest.md2.6 KB
- 脚本scripts/_okf.py14.3 KB
- 脚本scripts/index.py3.7 KB
- 脚本scripts/index.py.lock15.4 KB
- 脚本scripts/lint.py17.8 KB
- 脚本scripts/lint.py.lock15.4 KB
- 脚本scripts/status.py3.6 KB
- 脚本scripts/status.py.lock15.4 KB
- 脚本scripts/verify.py11.6 KB
- 脚本scripts/verify.py.lock15.4 KB
- 参考文档templates/adr.md416 B
- 参考文档templates/CONVENTIONS.md1.6 KB
- 参考文档templates/github/okf-lint.yml620 B
- 参考文档templates/github/okf-status.yml554 B
- 参考文档templates/github/okf-verify.yml1.1 KB
- 参考文档templates/glossary.md278 B
- 参考文档templates/metric.md386 B
- 参考文档templates/note.md205 B
- 参考文档templates/reference.md320 B
- 参考文档templates/runbook.md403 B
- 参考文档templates/table.md463 B
03 SKILL.md 正文
okf-knowledge
The team keeps knowledge as an OKF v0.2 bundle: markdown files with YAML frontmatter, reviewed in pull requests. Your job is to write knowledge that a reader can trust for the right reasons, and never to fake the reasons.
<skill-dir> below is the base directory shown when this skill loads.
Scripts run with uv run <skill-dir>/scripts/<name>.py; they declare their own dependencies.
Find the bundle
A bundle is a directory whose root holds a CONVENTIONS.md with type: OKF Conventions.
knowledge/ is the default name, but any directory works, and a repository may hold several bundles (not nested).
Work in the bundle that contains the file at hand: the nearest ancestor directory with such a CONVENTIONS.md.
Below, <bundle> is that directory; pass it to every script, and write /-rooted paths (rule 5) relative to it.
Read its okf_conventions before writing: it holds the type vocabulary, each type's stale_after_days, and which types need a human verification.
If there is no bundle and the user wants one, see "Set up a bundle".
Rules
- Never add anything to
verified. Only the okf-verify workflow writes there, recording a person's/okf verifycomment ashuman:<id>, and CI rejects anyhuman:entry that does not match such a comment and any other entry added by hand, such asprocess:(OKF006). You may not verify on a person's behalf, even if asked; tell them how to do it instead. - When you create or change a concept's content, set
generated: { by: claude-code/<your model ID>, at: <now> }. Leavegeneratedalone when you change nothing butverified. - Every timestamp is an ISO 8601 datetime with an offset. Get the current time with
date -u +%Y-%m-%dT%H:%M:%SZ. - Set
stale_afteron every new concept: now plus the type'sstale_after_days. Compute it with the command below before writing the file; do not type the date by hand.python3 -c "from datetime import *; print((datetime.now(timezone.utc)+timedelta(days=180)).strftime('%Y-%m-%dT%H:%M:%SZ'))" - Paths in frontmatter (
resource,sources[].resource) are URLs or bundle paths starting with/. Neverpolicies/x.mdor../x.md. - Record where a claim came from: add a
sourcesentry with anid, and cite it with a footnote whose label is that id ([^id]). - Use only types in the vocabulary. If none fits, say so to the user rather than inventing one.
Write or update a concept
- Pick the type and copy its template from
<skill-dir>/templates/(runbook.md,adr.md,table.md,metric.md,glossary.md,reference.md,note.md). - Replace every
<PLACEHOLDER>. Delete body sections that do not apply rather than leaving them empty. - Link related concepts with bundle paths:
[orders](/tables/orders.md). - Regenerate the indexes:
uv run <skill-dir>/scripts/index.py <bundle>. - Lint until there are no errors:
uv run <skill-dir>/scripts/lint.py <bundle> --base origin/main. The rules are inreferences/conventions-schema.md. - In the pull request description, list the concepts that need a person to check them, and ask for verification (next section).
Ask for a verification
Verification means a person compared the content with its sources or the system it describes. Ask the person who can do that to check the pull request's latest commit, and then comment on the pull request, naming that commit:
/okf verify @<head commit SHA> knowledge/runbooks/restart-api.md
Several paths may follow; each must be a file the pull request changed, and all of them in one bundle (use one comment per bundle).
The workflow adds { by: human:<their GitHub ID>, at: <comment time> } and pushes a commit.
It refuses commenters without write access, a SHA that is not the head, and (when the conventions say so) people who opened or committed to the pull request.
If the content changes afterwards, the verification no longer covers it (OKF007), and types that require one block the merge (OKF008).
Read knowledge before relying on it
Before you use a concept to answer a question or make a change, check its frontmatter:
status: deprecated: do not rely on it; follow the link to its replacement.stale_afterin the past: treat it as possibly outdated, and say so.- No
human:entry inverified: it has not been checked by a person; say so when it matters. generated.atnewer than the latestverified[].at: the latest change is unverified.
Take stock
uv run <skill-dir>/scripts/status.py <bundle> lists stale, deprecated, unverified, changed-since-verification and unreadable concepts.
For each one, propose one of:
- Re-verify: still true; ask a person for
/okf verify. - Update: no longer true; edit it (rules 2–4 apply).
- Deprecate: superseded; set
status: deprecatedand link the replacement in the body.
Set up a bundle
- Ask the user where the bundle should live; suggest
knowledge/. Call the answer<bundle>. - Copy
<skill-dir>/templates/CONVENTIONS.mdto<bundle>/CONVENTIONS.mdand adjust it with the team. - Create
<bundle>/index.mdwithokf_version: "0.2"in its frontmatter, then runindex.py <bundle>. - Copy the workflows in
<skill-dir>/templates/github/to.github/workflows/, and setbundle: <bundle>in each, pluspaths: ["<bundle>/**"]in okf-lint. Leave theuses:lines as they are. If the repository already has okf workflows for another bundle, add a job per bundle to them instead: add"<bundle>/**"to okf-lint'spathslist (it filters the whole workflow), and give the new okf-status job its ownlabel. - Add a line to the repository's
CLAUDE.md: knowledge lives in<bundle>/; start from<bundle>/index.md. - Tell the user what to set in GitHub, which you cannot do from here: protect the default branch (pull requests required; the okf-lint job
<job> / lintas a required check; Code Owners review), add/<bundle>/CONVENTIONS.mdtoCODEOWNERS, and optionally a GitHub App for okf-verify. The README's "Protect the default branch" section has the details.
References
references/spec-digest.md: what OKF v0.2 requires, and the pitfalls these rules exist for.references/conventions-schema.md: everyokf_conventionskey with its default, and every lint rule.