Keep Docs and Skills in Sync

TL;DR

Docs hold durable engineering knowledge. Skills control agent execution. When either surface changes, update the skill-to-doc map, review the other surface, run documentation health checks, and evaluate any affected skill behaviour.

When to use this workflow

Use this workflow when you:

• Change a principle, service handbook, workflow guide, runbook, or reference page that an agent skill may load.
• Create, edit, split, rename, or remove an agent skill.
• Move durable guidance from a skill into the docs site.
• Add a docs page that should become canonical context for an existing skill.
• Change skill trigger wording, safety gates, verification commands, or reference-loading instructions.

Source-of-truth rule

Workflow: changing docs

1. Identify affected skills. Check the skill-to-doc map for skills that depend on the page.
2. Update the docs page. Keep the page human-readable and agent-readable. Do not write prompt-like instructions into human docs.
3. Update freshness metadata. Change last_reviewed only after checking the claims against the source of truth.
4. Review affected skills. Check whether the skill still points to the right page, loads the right context, and verifies the right behaviour.
5. Update skill references if needed. Keep the skill concise; point to docs instead of copying durable guidance.
6. Run health checks. Use ./dev docs health from the platform root.
7. Run skill evals when behaviour changed. If trigger wording, routing, or safety gates changed, run representative skill prompts before merging.

Workflow: changing skills

1. Decide whether the change is knowledge or execution. Move durable knowledge to docs. Keep execution behaviour in the skill.
2. Update the source skill. Edit tools/skill-factory/skills/<skill>/ first; sync to .agents/skills/ after review.
3. Update the skill-to-doc map. Add, remove, or rename canonical docs dependencies.
4. Review mapped docs pages. Confirm the docs still contain the knowledge the skill is expected to load.
5. Create or update eval prompts. Include should-trigger and should-not-trigger cases for trigger changes.
6. Run health checks. Confirm mapped docs pages and skill paths exist.
7. Sync consumed skills. Run ./dev sync skills or copy the reviewed skill into .agents/skills/ using the approved repository workflow.

Skill-to-doc map rules

Each maintained skill should declare:

• The skill name.
• The source skill path.
• The consumed skill path.
• Canonical docs dependencies by docs slug.
• Optional secondary docs used for specific task variants.
• The review owner.

The map is intentionally lightweight. It does not prove semantic correctness; it makes affected-surface review discoverable.

Review checklist

• Does the skill still trigger for the right user prompts?
• Does the skill avoid triggering for adjacent but wrong prompts?
• Does the skill load canonical docs instead of duplicating them?
• Does the docs page avoid agent-only prompt language?
• Do docs, skills, code, generated specs, and ADRs agree on the source-of-truth hierarchy?
• Did last_reviewed change only after a real review?
• Did generated llms-full.txt and Markdown exports stay current?

Anti-patterns

• Shadow policy in skills. Durable rules copied into SKILL.md instead of linked to docs.
• Prompt-shaped docs. Human docs that read like system prompts.
• Unmapped skills. A skill that depends on docs but is invisible to health checks.
• Blind freshness updates. Changing last_reviewed without validating claims.
• Eval-free trigger edits. Changing trigger wording without testing realistic prompts.

Related

• Documentation
• Documentation Freshness
• Correct Documentation Drift
• Docs are canonical knowledge and skills are the agent execution layer