BF doc-governance
Installs a documentation governance architecture in a project and diagnoses what it is missing. Three actions: audit diagnoses the current state against seven components (source-of-truth layering / decision records / cascade discipline / planning system / checkpoints bound to actions / gates / incident traceability); init installs what is missing (config, a script copy, a pre-commit gate, two Claude Code hooks, decision and plan templates); check keeps verifying that what the docs claim about reality still holds (TODOs left hanging too long, cascade memos never carried out, plan status that doesn't match reality, broken references, broken links, § section references pointing to the wrong place, missing index entries, broken tables, endpoints the docs declare but the code doesn't have). The framework was distilled from the documentation system of a large protocol project, and every check is tied to a real incident. ⚠️ init modifies the repository and installs hooks that keep running after the session ends (a git pre-commit gate and two Claude Code hooks that can block commits and new plan files); without --yes it only lists the planned changes. audit and check are read-only. Use only when the user explicitly asks about documentation governance in the current repository: "doc governance", "audit the docs against the code", "set up a documentation system for this project", "audit before I write a plan", "is the spec the single source of truth", or when a commit or file write was blocked by this skill's own gate output.
Installs a documentation governance architecture in a project and diagnoses what it is missing.
As a process F 35/100 · Will not run — References files that are not bundled: scripts/governance.py
How to improve
- Shorten the description to 1024 characters.
- The text references files that are not there: add them or drop the references.
- Your own cases (evals/evals.json, 4–6 real requests with expected answers): the full check would then run those instead of a model-drafted suite.
- A spec.yaml with trigger phrases and assertions — a behaviour contract for CI; `skilltest init` writes a template.
Guard findings · 0
✓ No critical or high findings
Files scanned: 10. Evidence is masked. Grey chips explain why severity was lowered.
Against the Agent Skills spec
- error
description-longdescription is 1541 chars, limit 1024 - warning
missing-refreference to a missing file: scripts/governance.py - note
description-budgetdescription takes 1541 of the ~15000-char shared budget for all skills - note
edit-residuethe text marks something as outdated (lines 25): check that old rules are not kept next to new ones — the full check reads the text for contradictions
Process rating: all ten parameters 35/100
- 0Tools and files. 1 referenced file(s) missing: scripts/governance.py
- 0Result and completion. Does not say what the result is
- 0Inputs and preconditions. Does not say what the process needs to start
- 25Steps. 1 steps
- 30Running it twice. 20 mutating operations with no state check
- 60Failures and branches. 2 branches
- 70When it triggers. States when to use, but not when not to
- 100Consistency. Name and required fields are in place
- 100Execution cost. Instruction body is 3239 tokens
- 100Progress reporting. Reports progress
- medium Safety rules and hard prohibitions inside a skill: they belong in the system prompt, here they protect nothing
Everything here is measured from the skill text rather than judged by a model, so the numbers are checkable. A parameter weighs more when it is a more common reason for the process to stall.
Quality signals
- +4Description does not say when NOT to use the skill (false activations)
- +3Description length 1541: 120–800 characters recommended
- +3No numbered steps or checklist
- +3Output format is not stated: the model decides each time
- -5TODO / placeholder text left in the skill
- +1No license
- +2Single-language instructions
- +5Description quotes 5 example trigger phrases
- +4Structure: 9 headings
- +4Has examples (1 code blocks)
Quality base 70; lint remarks subtract, signals add up to 100. Result: 44.