Keep AI Skill Documents in One Place and Write Them for AI to Look Up
Use when maintaining AI skill documents. It keeps one source file and regenerates copies from it, puts decision tables first and details in reference files, tests behavior before and after changes, and lets automated releases set versions.
To use this AI rule
## Edit Only the Source File and Regenerate Copies From It
Identify the canonical skill document and treat generated integrations, manifests, or platform-specific projections as derived artifacts. Edit the source and its references, then regenerate derivatives with the repository’s generator.
Never hand-edit CI-owned outputs. Keep a check mode in continuous integration that regenerates in memory or a temporary area and fails when committed derivatives drift from the source.
When the same skill is distributed through multiple platforms, share content rather than maintaining forks. Record which file owns content, metadata, and version values so contributors do not create competing sources.
Keep installation and end-user usage outside contributor instructions. Contributor documentation should explain maintenance, validation, testing, and release behavior without duplicating the product guide.
## Keep Decisions in the Main Document and Move Details to Reference Files
Use the main skill document as the retrieval entry point and load detailed references only when needed. Place:
- decision frameworks and high-frequency patterns in the entry document;
- detailed guides, templates, and extended examples in reference files;
- baseline scenarios and rationalization records in test documentation;
- installation and usage in user-facing documentation;
- contributor process detail in the contribution guide.
Use stable relative links between the entry document and adjacent references. Preserve top-level reference anchors used by routing tables even when restructuring lower-level subsections.
Apply one placement test: if an item determines which path to choose, keep it near the entry point; if it explains how to execute one chosen path in depth, move it to a reference.
## Write Short, Direct Instructions With Decision Tables First
Optimize for an agent that classifies intent, selects a branch, and executes—not for a reader consuming the guide from beginning to end.
When several approaches are valid, place a compact decision table before the playbook. Order each section as:
1. decision table;
2. default procedure;
3. alternatives;
4. concise rules and gotchas.
Use imperative voice and one fact per bullet. Convert advisory scaffolding such as “you should consider,” “note that,” or “keep in mind” into direct actions. Prefer terse positive and negative rules for non-obvious distinctions.
Every table, example, and code block must add a fact not already stated. Remove before-and-after diffs, repeated rationale, teaching asides, and completeness-only examples when the procedure already carries the instruction.
Keep rationale to at most one opening sentence. Set a subsection token target and split or compress sections that exceed it without removing decision criteria, required actions, constraints, or exceptions.
## Check Document Structure and Test AI Behavior After Changes
Match validation to the artifact. Documentation-oriented skills may not need compilation, but they still require automated structural checks and manual behavior tests.
Automate checks for required frontmatter fields, naming rules, line or token budgets, internal links, generated-artifact synchronization, and repository-specific lint rules. Treat soft size targets as warnings and hard integrity constraints as failures.
For a content change:
1. edit the canonical skill or a reference;
2. run local structural validation;
3. reload the skill in its host;
4. execute realistic user queries that exercise the changed branch;
5. compare behavior against baseline scenarios for regressions.
Require before-and-after evidence for affected scenarios in the pull request. For substantive information-architecture changes, obtain an independent review focused on retrieval shape, compression, and missing decision branches.
## Require Pull Request Checks and Let Automated Releases Set Versions
Protect the main branch: require pull requests, validation checks, and a valid conventional title. If changes are squash-merged and the pull-request title becomes the release commit, validate that title because it drives versioning.
Map conventional change types to version bumps, including an explicit major-change signal. Let the release workflow update the changelog, canonical version metadata, platform manifests, and generated artifacts in one release change.
Never edit synchronized version numbers manually. Keep one canonical version source and let the release pipeline propagate it before creating the tag.
Before merge, confirm:
- generated outputs match the canonical source;
- decision tables precede branching playbooks;
- redundant scaffolding and examples are removed;
- routed anchors remain stable;
- changed baseline scenarios include evidence;
- required validation and title checks pass.