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

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.