public/bluecraft
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

split agent-docs skills

Browse Source
This commit is contained in:
Ge Song
2026-04-23 01:29:16 +08:00
parent 0987c0bf0e
commit 2c22fcc4c3
23 changed files with 679 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

44
skills/agent-docs-audit/SKILL.md Normal file
View File

@@ -0,0 +1,44 @@
---
name: agent-docs-audit
description: Use when auditing AGENTS.md or agent-docs without editing files, especially for instruction quality review, adherence-risk assessment, findings-first reports, or rationality critiques.
---
# Agent Docs Audit
## Overview
Use this skill for read-only assessment of AGENTS and `agent-docs`. The output should prioritize findings, evidence, residual risks, and adherence impact instead of proposing patches first.
## When to Use
- The user asks for a review, audit, rationality check, or instruction-adherence assessment
- The user asks what remains wrong after a refactor
- The user asks why agents still fail to follow the docs
- The task is to list bugs, risks, or remaining problems before making changes
Do not use this skill as the main workflow when the task is to edit files. Switch to `agent-docs-refactor` for that.
## Workflow
1. Read the root `AGENTS.md` and every active child doc in scope.
2. Read `../agent-docs/references/audit-checklist.md`.
3. Use `../agent-docs/references/refactor-checklist.md` as the structural baseline.
4. Separate observed facts from inferences:
- observed facts: file contents, references, checklists, routing text, command output
- inferences: likely adherence impact, likely confusion points, likely maintenance risk
5. Evaluate:
- routing clarity
- single authoritative rule ownership
- shape fitness: rule doc vs inventory doc
- instruction density and likely adherence load
- residual cycles or secondary-index behavior
6. Report findings first, ordered by severity.
## Reporting
- Findings first
- Then open questions or assumptions
- Then an adherence assessment
- Then any optional summary
If no findings are discovered, state that explicitly and mention residual risks or coverage limits.

4
skills/agent-docs-audit/agents/openai.yaml Normal file
View File

@@ -0,0 +1,4 @@
interface:
display_name: "Audit agent-docs"
short_description: "Review agent-docs quality and adherence"
default_prompt: "Use $agent-docs-audit to evaluate AGENTS.md and agent-docs for instruction quality, routing clarity, and adherence risk."

41
skills/agent-docs-consistency/SKILL.md Normal file
View File

@@ -0,0 +1,41 @@
---
name: agent-docs-consistency
description: Use when checking the AGENTS.md and agent-docs graph for reachability, cycles, depth, duplicate authority, routing clarity, or rule-doc versus inventory-doc consistency.
---
# Agent Docs Consistency
## Overview
Use this skill for structural consistency checks across AGENTS and `agent-docs`. It focuses on the document graph and authority model, not repository behavior.
## When to Use
- The user asks whether there are cycles
- The user asks for document depth or routing structure
- The user asks whether two docs both own the same rule
- The user asks whether a doc has become a secondary router or mixed-shape document
## Workflow
1. Read the root `AGENTS.md`.
2. Read the active child docs in scope.
3. Read `../agent-docs/references/consistency-checklist.md`.
4. Inspect:
- root reachability
- shortest routing depth
- direct cycles and high-noise cross-links
- duplicate authority candidates
- out-degree hotspots
- rule-doc vs inventory-doc shape mismatches
5. Distinguish:
- blocking or high-noise structural problems
- acceptable cross-references
6. Report the structural findings without drifting into repository implementation review. Use `agent-docs-repo-alignment` for repo-fact comparison.
## Output
- Reachability summary
- Cycle summary
- Duplicate-authority or shape findings
- Residual risk assessment

4
skills/agent-docs-consistency/agents/openai.yaml Normal file
View File

@@ -0,0 +1,4 @@
interface:
display_name: "Check agent-doc consistency"
short_description: "Check graph and authority consistency"
default_prompt: "Use $agent-docs-consistency to inspect the agent-doc graph for reachability, cycles, duplicate authority, and shape mismatches."

57
skills/agent-docs-refactor/SKILL.md Normal file
View File

@@ -0,0 +1,57 @@
---
name: agent-docs-refactor
description: Use when creating, updating, splitting, merging, rerouting, renaming, or deleting AGENTS.md and agent-docs, especially when references, child docs, or document responsibilities must change together.
---
# Agent Docs Refactor
## Overview
Use this skill to edit the root `AGENTS.md` or files under `agent-docs/`. It is the production workflow for restructuring the document tree while preserving explicit routing and single-home rule ownership.
## When to Use
- The user asks to optimize, refactor, split, merge, or rewrite AGENTS or `agent-docs`
- A rule must move from one document to another
- A new child doc must be introduced or an obsolete one removed
- Cross-references, routing text, and checklists must be updated together
## Workflow
1. Read the root `AGENTS.md` and affected child docs.
2. Read the smallest relevant references from `../agent-docs/references/`:
- `root-agents-template.md`
- `rule-doc-template.md`
- `inventory-doc-template.md`
- `child-doc-template.md`
- `linking-patterns.md`
- `refactor-checklist.md`
3. Decide the target shape before editing:
- keep as one rule doc
- split rule doc from inventory
- merge overlapping docs
- delete obsolete leaf doc
4. Apply edits so that:
- the root remains the starting point
- every active child doc remains reachable from the root
- each rule has one authoritative home
- stale references are removed in the same change
5. If the change alters routing, authority ownership, or document shape, hand off to `agent-docs-consistency`.
6. If the change alters claims that depend on repository facts, hand off to `agent-docs-repo-alignment`.
7. Finish with `agent-docs-verification`.
## Refactor Rules
- Prefer the smallest change that reduces ambiguity or maintenance cost.
- Do not split only for symmetry.
- Do not split when one short document already governs one clear topic.
- Do not keep a child doc that is no longer reachable from the root.
- Do not leave topic-specific rules in the root file once a narrower child doc exists.
- Do not let inventory docs become policy docs.
- Do not add an intermediate file that only repeats links without adding scope or decision logic.
- Do not create a new child doc unless it reduces ambiguity, repetition, or maintenance cost.
- In monorepos, keep common constraints in the root file and keep project-specific rules in documents near that project instead of the general rules layer.
- Do not mix general agent-doc governance with business rules, product instructions, or end-user documentation.
- Titles and filenames should state purpose directly.
- Each opening should explain purpose, trigger, and that the document must be followed in scope.
- Use repository-relative paths in backticks when referencing repo files from AGENTS or `agent-docs`.

4
skills/agent-docs-refactor/agents/openai.yaml Normal file
View File

@@ -0,0 +1,4 @@
interface:
display_name: "Refactor agent-docs"
short_description: "Edit or restructure agent-docs"
default_prompt: "Use $agent-docs-refactor to create, split, merge, reroute, or rewrite AGENTS.md and agent-docs, including necessary follow-up consistency, repo-alignment, and verification steps."

41
skills/agent-docs-repo-alignment/SKILL.md Normal file
View File

@@ -0,0 +1,41 @@
---
name: agent-docs-repo-alignment
description: Use when checking whether AGENTS.md and agent-docs still match repository facts such as scripts, ports, directory structure, contract ownership, runtime behavior, or verification commands.
---
# Agent Docs Repo Alignment
## Overview
Use this skill to compare AGENTS and `agent-docs` against the real repository. It detects drift between documentation and code, config, scripts, tests, and folder structure.
## When to Use
- The user asks whether docs still match the repository
- A doc mentions commands, ports, packages, stack choices, routes, DTO ownership, or runtime behavior
- A previous audit found wording that might be stale
- A refactor changed scripts or layout and the docs may need follow-up updates
## Workflow
1. Read the docs in scope.
2. Read `../agent-docs/references/repo-alignment-checklist.md`.
3. Inspect the repository facts relevant to the claim:
- scripts and `package.json`
- ports and proxy config
- directory and package structure
- shared contracts and DTO ownership
- tests or verification commands
- runtime and thread-sync code paths when relevant
4. Record observed facts first.
5. Compare doc claims against repo facts.
6. Report:
- confirmed matches
- must-fix drift
- wording drift or ambiguity
## Boundary
- This skill checks docs against repo facts.
- It does not replace structural graph checks from `agent-docs-consistency`.
- It does not perform the actual doc rewrite; use `agent-docs-refactor` for that.

4
skills/agent-docs-repo-alignment/agents/openai.yaml Normal file
View File

@@ -0,0 +1,4 @@
interface:
display_name: "Check agent-doc repo alignment"
short_description: "Compare agent-docs against repo facts"
default_prompt: "Use $agent-docs-repo-alignment to compare AGENTS.md and agent-docs against the repository facts: code, scripts, structure, and configuration."

56
skills/agent-docs-verification/SKILL.md Normal file
View File

@@ -0,0 +1,56 @@
---
name: agent-docs-verification
description: Use when AGENTS.md or agent-docs have been changed and you need post-change validation evidence such as diff cleanliness, routing checks, cycle checks, or summary of what was verified.
---
# Agent Docs Verification
## Overview
Use this skill after changing AGENTS or `agent-docs` to gather verification evidence and report exactly what was checked. It is the completion gate for documentation-tree changes.
## When to Use
- A doc refactor is complete and needs verification
- The user asks whether the change is really done
- You need to summarize what was validated versus what was not
## Workflow
1. Read `../agent-docs/references/verification-checklist.md`.
2. If the change edited this skill suite itself, also read `../agent-docs/references/skill-maintenance-checklist.md`.
3. Run the strongest repository validation that actually applies.
4. At minimum for docs-only work:
- run `git diff --check`
5. When the change touched routing or structure, also re-check:
- root reachability
- stale references
- direct cycles if relevant
- duplicate authority or document-shape regressions when relevant
6. When the change touched repository-dependent claims, confirm those claims against current files, config, scripts, or command output rather than memory.
7. Treat the following as behavior-check-required changes:
- root routing changes
- child-doc reference changes
- conflict-resolution changes
- workflow changes that affect required follow-up skills such as `refactor -> consistency -> repo-alignment -> verification`
8. For behavior-check-required changes, run a small behavior check with 1 to 3 representative prompts and inspect whether the agent:
- reads the root entrypoint before choosing a specialized workflow
- follows the intended route and required follow-up checks
- escalates duplicate-authority or routing ambiguity instead of guessing
- states any unverified remainder explicitly
9. When the change edited the `agent-docs` skill suite itself, also confirm:
- each `agents/openai.yaml` still matches its `SKILL.md`
- every shared reference still has a direct reference path from the relevant skill
- no stale filenames, old skill names, or outdated terms remain after renames or splits
- one concept still uses one term across `SKILL.md`, `agents/openai.yaml`, and `references/`
10. Report command evidence and exact scope:
- what was verified
- what was not verified
- whether the claim is limited to docs structure only
- whether representative behavior was checked or only static structure was reviewed
## Reporting Rules
- Do not say a change is complete without fresh evidence from the current turn.
- Name the commands that were run.
- If only a minimum docs-only gate was available, say so explicitly.

4
skills/agent-docs-verification/agents/openai.yaml Normal file
View File

@@ -0,0 +1,4 @@
interface:
display_name: "Verify agent-doc changes"
short_description: "Run post-change validation for agent-docs"
default_prompt: "Use $agent-docs-verification to run post-change validation for AGENTS.md and agent-docs and summarize the evidence."

97
skills/agent-docs/SKILL.md Normal file
View File

@@ -0,0 +1,97 @@
---
name: agent-docs
description: Use when a task involves AGENTS.md or agent-docs and you need to choose the correct specialized workflow for auditing, refactoring, consistency checks, repo alignment, or verification.
---
# Agent Docs
## Overview
Use this skill as the entrypoint for AGENTS.md and `agent-docs/` work. It routes the task to the narrowest specialized skill and points to the shared templates and checklists under `references/`.
Treat covered files as required instructions. If one applies in scope, it must be followed, not treated as optional background reading.
## When to Use
- The user asks to create, update, split, merge, delete, or refactor `AGENTS.md` or `agent-docs/`
- The user asks whether the instruction tree is rational, consistent, or easy for agents to follow
- The user asks whether agent docs match repository reality
- The user asks for post-change validation of AGENTS or `agent-docs`
Do not use this skill as the main workflow when the task is already clearly one of the specialized categories below. Switch directly to the matching skill.
Do not use it for end-user documentation, product manuals, or README content that is not part of AGENTS or `agent-docs`.
## Quick Triage
1. Identify the concrete scope first:
- root `AGENTS.md` only
- one or more child docs under `agent-docs/`
- both root and child docs
- documentation-tree refactor
2. Then choose the narrowest workflow:
- read-only rationality or adherence review
- structural graph or authority inspection
- repository-fact comparison
- document editing with follow-up checks
## Routing
- Use `agent-docs-audit` when the task is read-only evaluation: rationality review, instruction-adherence assessment, problem listing, or findings-first reporting.
- Use `agent-docs-refactor` when the task requires editing files: create, split, merge, reroute, rename, delete, or rewrite `AGENTS.md` or `agent-docs`.
- Use `agent-docs-consistency` when the task is structural inspection: reachability, cycles, depth, duplicate authority, or rule-doc vs inventory-doc shape checks.
- Use `agent-docs-repo-alignment` when the task asks whether AGENTS or `agent-docs` match repository facts such as scripts, ports, directories, DTO ownership, or runtime behavior.
- Use `agent-docs-verification` when the task is to validate a completed doc change and summarize the verification evidence.
- After `agent-docs-refactor`, also use `agent-docs-consistency` when routing, authority ownership, reference depth, or document shape changed.
- After `agent-docs-refactor`, also use `agent-docs-repo-alignment` when the edited docs make claims about repository facts or when stale wording may depend on current code, config, or commands.
- Finish edited work with `agent-docs-verification`. Verification is the completion gate, not a substitute for structural or repo-fact review.
## Conflict Resolution
- Prefer the most specific applicable document over a broader one.
- Prefer a child doc's scoped rule over a general reminder in the root file.
- Prefer a document with explicit `Applies To` coverage over background wording that only mentions the topic indirectly.
- Prefer rule-doc behavior constraints over inventory entry wording when both mention the same topic.
- If two active docs both appear to own the same rule, treat that as duplicate authority and route to `agent-docs-consistency` or `agent-docs-refactor` instead of guessing.
- If two active docs are equally specific and both explicitly apply, treat that as unresolved duplicate authority and report the ambiguity instead of choosing one.
## Which Reference To Read
- Root `AGENTS.md` update: read `references/root-agents-template.md`.
- Child rule or policy doc: read `references/rule-doc-template.md`.
- Child inventory or registry doc: read `references/inventory-doc-template.md`.
- Unsure whether a child doc is a rule doc or inventory doc: read `references/child-doc-template.md`.
- Cross-reference or document-tree change: read `references/linking-patterns.md`.
## Shared References
Read only the files needed for the current task.
- Root doc template: `references/root-agents-template.md`
- Rule doc template: `references/rule-doc-template.md`
- Inventory doc template: `references/inventory-doc-template.md`
- Child doc chooser: `references/child-doc-template.md`
- Linking patterns: `references/linking-patterns.md`
- Refactor checklist: `references/refactor-checklist.md`
- Audit checklist: `references/audit-checklist.md`
- Consistency checklist: `references/consistency-checklist.md`
- Repo-alignment checklist: `references/repo-alignment-checklist.md`
- Verification checklist: `references/verification-checklist.md`
- Skill-maintenance checklist: `references/skill-maintenance-checklist.md`
## Shared Constraints
- Treat the root `AGENTS.md` as the starting point for required `agent-docs`.
- Keep one authoritative home for each rule.
- Keep repository-wide rules in the root file and topic-specific rules in child docs.
- In monorepos, keep common constraints in the root file and put subproject-specific rules in the relevant nearby docs.
- Match document shape to job: use rule docs for policy and inventory docs for maintained classifications or registries.
- Remove stale references and obsolete files in the same change when restructuring the tree.
- Write for maintainers. State actions, constraints, and decision criteria directly.
- Rules should be actionable, not slogan-like.
- Prefer standard Markdown headings and lists over wrapper tags for structure.
- Keep the root focused on the next reading decision and list only the child docs that are actually needed.
- Keep references directional and explicit: parent docs point to the child docs that refine them.
- Prefer stable, semantic filenames and direct titles that state purpose.
- When referencing repository files from AGENTS or `agent-docs`, use repository-relative paths in backticks, not Markdown links or machine-local absolute paths.
- Do not mix general agent-doc governance with project-specific business rules, product manuals, media planning, or end-user documentation in the same general-purpose document.
- Unless a document explicitly says otherwise, treat paths as relative to the root of the current Git worktree.

4
skills/agent-docs/agents/openai.yaml Normal file
View File

@@ -0,0 +1,4 @@
interface:
display_name: "Maintain agent-docs"
short_description: "Route agent-docs maintenance work"
default_prompt: "Use $agent-docs to route AGENTS.md and agent-docs maintenance tasks to the correct specialized skill and required follow-up checks."

14
skills/agent-docs/references/audit-checklist.md Normal file
View File

@@ -0,0 +1,14 @@
# Audit Checklist
Use this checklist for read-only audits of `AGENTS.md` and `agent-docs/`.
- Is the root `AGENTS.md` still the clear entrypoint?
- Can a maintainer tell which document to read first for each common task?
- Does any document act like a secondary router without enough reason?
- Does each rule appear to have one authoritative home?
- Does any inventory document contain policy language that should live in a rule doc?
- Does any general-purpose agent-doc mix in project-specific business rules, product instructions, or end-user documentation?
- Do key workflow docs state their edge cases and failure modes clearly enough that an agent would not have to infer them?
- Are there residual cycles or cross-links that materially increase adherence cost?
- Which findings are observed facts, and which are inferences about adherence risk?
- If there are no concrete findings, what residual risks remain?

19
skills/agent-docs/references/child-doc-template.md Normal file
View File

@@ -0,0 +1,19 @@
# Child `agent-docs/` Template Chooser
Use this reference when you know you are editing a Markdown file inside `agent-docs/`, but still need to decide which child template fits.
## Choose The Smallest Matching Template
- Use `rule-doc-template.md` for instructions, constraints, policy, decision criteria, or workflow guidance.
- Use `inventory-doc-template.md` for maintained lists, registries, migration queues, or cleanup backlogs.
- Split the document if one file tries to serve both purposes and the split would reduce ambiguity.
## Quick Tests
- If the document mainly tells maintainers what to do and what to avoid, use the rule template.
- If the document mainly tracks entries that need to be updated over time, use the inventory template.
- If the document has a long list of repeated entries under one governing policy, keep the policy brief and let the inventory structure carry the list.
## Compatibility Note
Older repositories may still refer to `references/child-doc-template.md` as the default child template. Keep this file as the entrypoint, but point new work to the specific template that matches the document's job.

12
skills/agent-docs/references/consistency-checklist.md Normal file
View File

@@ -0,0 +1,12 @@
# Consistency Checklist
Use this checklist for structural inspection of the AGENTS and `agent-docs` graph.
- Is every active child document directly or indirectly reachable from the root?
- What is the shortest routing depth for each child doc?
- Are there direct cycles? If so, which ones are harmless and which ones are noisy?
- Does any document have unusually high out-degree and behave like a secondary index?
- Does any intermediate document only restate links without adding scope or decision logic?
- Is any rule likely owned by more than one active document?
- Does each document's actual shape still match its declared job: root, rule doc, or inventory?
- Are there stale references to deleted or renamed docs?

63
skills/agent-docs/references/inventory-doc-template.md Normal file
View File

@@ -0,0 +1,63 @@
# Inventory `agent-docs/` Template
Use this structure for Markdown files inside `agent-docs/` when the document's main job is to track a maintained set of entries: media plans, registries, migration queues, or cleanup lists.
## Recommended Shape
```md
# <Document Title>
<Opening statement: what this inventory tracks, when it should be used or updated, and that it must be followed in scope.>
## Applies To
- <tasks that require reading or updating this inventory>
## Does Not Apply To
- <tasks that belong in a rule doc, public docs, or another inventory>
## Maintenance Rules
- <how to add, update, remove, or rewrite entries>
## Reclassification Rules
- <when an entry changes status or grouping>
- <when repeated notes should become policy in a rule doc>
- <when this inventory should split or link to a narrower rule doc>
## Entries
### <Grouping Heading>
#### <Entry Title>
<Recommended fields; keep only the ones that materially help maintainers.>
Source:
- <path or owning document>
Status:
- <planned / in progress / complete / remove / optional>
Notes:
- <what to capture, why it matters, or what to clean up>
## Maintenance Checklist
- <questions for keeping the inventory current and unambiguous>
```
## Notes
- Prefer an inventory template when the document is mostly a maintained list rather than a rules essay.
- Start with a small field set. `Source`, `Status`, and `Notes` are common defaults, not mandatory fields.
- Add, rename, or remove entry fields to match the repository's actual maintenance needs.
- Keep entry fields stable enough within one document that maintainers can scan and update them consistently.
- Use grouping headings only when they materially improve navigation.
- Separate durable maintenance rules from the entries themselves.
- If the governing policy becomes large, move it to a rule doc and link to it from the inventory.
- Add `Reclassification Rules` when entry state changes or repeated review decisions would otherwise stay implicit.
- Write for maintainers and make update decisions explicit.
- If the document references repository files, write repository-relative paths in backticks, not Markdown links or machine-local absolute filesystem paths.

62
skills/agent-docs/references/linking-patterns.md Normal file
View File

@@ -0,0 +1,62 @@
# Linking Patterns
## Preferred Patterns
### Root -> Topic Docs
Use when the repository has a small set of clearly separate instruction topics.
```md
# Required `agent-docs` Before Editing
- Read and follow `agent-docs/topic-a.md` when ...
- Read and follow `agent-docs/topic-b.md` when ...
```
### Root -> Project Doc -> Leaf Docs
Use only when the intermediate layer reduces ambiguity or repeated cross-reference text.
```md
AGENTS.md
-> agent-docs/project-guidelines.md
-> agent-docs/topic-a.md
-> agent-docs/topic-b.md
```
### Root -> Subproject `agent-docs/`
Use in monorepos when a subproject has its own scoped instruction set.
```md
AGENTS.md
-> apps/docs/agent-docs/project-guidelines.md
-> services/api/agent-docs/backend-guidelines.md
```
Common rules stay in the root `AGENTS.md`. Subproject-specific rules stay near the subproject they govern.
## Anti-Patterns
- Root file linking to every leaf doc in a large tree without grouping
- Child docs that are never reachable from the root
- Topic-specific rules stored in the root file without a reference reason
- Extra index files that only restate links without adding scope or decision logic
- Moving rules out of the root file without leaving an explicit reference to the new child file
- Keeping monorepo-wide and subproject-specific constraints mixed together in the same root section when they can be separated cleanly
## Explicit Reference Rule
Parent documents should point to the child documents that refine them.
If a child document exists and is active, there must be an explicit reference path from the root `AGENTS.md` to that document.
The root `AGENTS.md` should list only the next `agent-docs` documents that are actually needed. Do not add unnecessary next-step links just for completeness.
## Conflict Resolution Rule
- More specific scope beats broader scope.
- A child doc with explicit task scope beats a generic note in the root file.
- A rule doc's behavior rule beats an inventory entry's shorthand wording.
- If two active docs both read like authoritative owners for the same rule, do not improvise a priority. Treat it as duplicate authority and refactor the tree.
- If two sibling docs are equally specific and both explicitly apply, do not break the tie by tone or wording. Report the ambiguity and refactor the tree.

27
skills/agent-docs/references/refactor-checklist.md Normal file
View File

@@ -0,0 +1,27 @@
# Refactor Checklist
Use this checklist after changing the root `AGENTS.md` or any file in `agent-docs/`.
- Does each covered document own one clear topic?
- Does each filename clearly express the document's purpose?
- Does each opening explain purpose, trigger, and that the document must be followed in scope?
- Is the root `AGENTS.md` still the starting point for required `agent-docs`?
- Does every active `agent-docs/` file have an explicit path from the root?
- Does each child doc use the right shape for its job: rule doc versus inventory doc?
- Did you remove stale references, filenames, and replaced paths?
- Did you delete or update any `agent-docs` file that is no longer referenced from the root `AGENTS.md`?
- Did you avoid duplicating the same rule across multiple active docs?
- Did you avoid mixing long entry inventories into rule docs when a separate inventory would be clearer?
- Did you avoid adding an intermediate router or index doc that only repeats links?
- If you split a doc, did the split reduce ambiguity, repetition, or maintenance cost?
- If a document grew broader, did you check whether it now owns more than one real decision surface and should be split?
- If a workflow is fragile or easy to misapply, did you add explicit edge cases or failure modes instead of hiding them in prose?
- Is the default path basis still the root of the current Git working tree unless explicitly overridden?
- Are repository-wide constraints still in the root file?
- Are topic-specific constraints still in child docs?
- Are project-specific rules still kept in project-specific documents rather than the general rules layer?
- Did you avoid mixing general agent-doc governance with project-specific business rules or end-user documentation?
- Do repository file references still use plain repository-relative paths in backticks rather than Markdown links or machine-local absolute paths?
- Did you keep reference depth minimal?
- Does the root still act like a route map instead of a topic dump?
- If the repository has a validation command, did you run it?

12
skills/agent-docs/references/repo-alignment-checklist.md Normal file
View File

@@ -0,0 +1,12 @@
# Repo Alignment Checklist
Use this checklist when comparing AGENTS or `agent-docs` against repository facts.
- Which exact doc claims depend on repository reality?
- Which repository files or commands provide the authoritative fact for each claim?
- Do the rule docs expose enough authority or source-of-truth anchors that a maintainer can verify the claim without guessing?
- Do scripts, ports, paths, or package names still match the docs?
- Do the documented verification commands still match actual script behavior?
- Do layering, contract-boundary, or runtime-topology claims still match code structure?
- Which mismatches are must-fix drift versus wording cleanup?
- Are the conclusions grounded in current files and command output rather than memory?

38
skills/agent-docs/references/root-agents-template.md Normal file
View File

@@ -0,0 +1,38 @@
# Root `AGENTS.md` Template
Use this structure for the `AGENTS.md` at the root of the current Git working tree.
## Recommended Shape
```md
# Root AGENTS.md
- State that this file is the starting point for the repository's required `agent-docs`.
- Define the default path basis.
# Common Constraints
- Keep repository-wide rules here.
- Do not repeat topic-specific rules that belong in child docs.
# Required `agent-docs` Before Editing
- List the required `agent-docs` explicitly.
- Use explicit "Read and follow ..." wording.
```
## Notes
- Keep this file short.
- Treat this file as an instruction document, not a passive index.
- Reference child docs only when they are actually needed.
- Write for maintainers and keep decisions explicit.
- When referring to child docs, write repository-relative paths in backticks such as `agent-docs/example.md`, not Markdown links or machine-local absolute filesystem paths.
- Do not turn the root file into a dump of all topic-specific rules.
- If the root starts collecting multiple topic-specific rule blocks, split them into child docs and keep only the routing decision here.
## Complexity Budget
- Keep the root focused on three jobs only: entrypoint, repository-wide constraints, and next-step routing.
- If a root section starts carrying topic-specific decision logic, move that logic to a child doc and leave only the routing cue behind.
- Treat multiple topic-specific rule blocks in the root as a refactor trigger, not as a sign to keep extending the root file.

51
skills/agent-docs/references/rule-doc-template.md Normal file
View File

@@ -0,0 +1,51 @@
# Rule `agent-docs/` Template
Use this structure for Markdown files inside `agent-docs/` when the document's main job is to govern behavior: rules, policy, constraints, decision criteria, or workflow guidance.
## Recommended Shape
```md
# <Document Title>
<Opening statement: what this doc governs, when it applies, and that it must be followed in scope.>
## Applies To
- <specific task or document types>
## Does Not Apply To
- <out-of-scope task or document types>
## Authority
- <source of truth: owning doc, repository path, command, or code area>
## <Rule Section>
- <instructions>
## Edge Cases
- <exceptions, ambiguous cases, or branch conditions>
## Failure Modes
- <what usually goes wrong and how to recover>
## Checklist
- <validation questions>
```
## Notes
- Make the scope explicit.
- Keep the document responsible for one topic.
- Use semantic filenames and headings.
- Write for maintainers. State actions, constraints, and decision criteria directly.
- If the document references repository files, write repository-relative paths in backticks, not Markdown links or machine-local absolute filesystem paths.
- State the user or maintainer decision directly: what to do, what to avoid, and how to choose.
- Add `Authority` when the rule depends on a repository fact, owning document, or other source of truth that later reviews must verify.
- Add `Edge Cases` and `Failure Modes` when the workflow is easy to misapply or the scope boundary is easy to misunderstand.
- Prefer linking to inventories, examples, or narrower child docs instead of embedding long registries inline.

9
skills/agent-docs/references/skill-maintenance-checklist.md Normal file
View File

@@ -0,0 +1,9 @@
# Skill Maintenance Checklist
Use this checklist when editing the `agent-docs` skill suite itself: any `SKILL.md`, `agents/openai.yaml`, or shared file under `references/`.
- Does each `agents/openai.yaml` still match the skill title, scope, and trigger language in the corresponding `SKILL.md`?
- Is every file in `references/` directly referenced from the router skill or the specialized skill that requires it?
- Are there stale filenames, old skill names, or outdated terms left behind after renames or splits?
- Does one concept still use one term across `SKILL.md`, `agents/openai.yaml`, and `references/`?
- If a shared checklist or template changed, do the affected skills still point to the right file and workflow step?

12
skills/agent-docs/references/verification-checklist.md Normal file
View File

@@ -0,0 +1,12 @@
# Verification Checklist
Use this checklist after changing `AGENTS.md` or `agent-docs/`.
- Did you run the strongest repository validation that actually applies?
- For docs-only work with no stronger validator, did you at least run `git diff --check`?
- If routing changed, did you re-check root reachability?
- If cross-links changed, did you re-check for stale references or direct cycles where relevant?
- If root routing, child references, conflict rules, or required follow-up workflow changed, did you test 1 to 3 representative prompts?
- Did those representative prompts confirm that the agent read the root entrypoint first, chose the intended specialized workflow, ran required follow-up checks, and surfaced ambiguity instead of guessing?
- Does the completion claim match the commands actually run?
- If part of the change was not verified, is that limitation stated explicitly?