From 8d704cf4069be94aa613ae5aa813b65869dd400e Mon Sep 17 00:00:00 2001 From: Ge Song Date: Thu, 19 Mar 2026 15:00:56 +0800 Subject: [PATCH] feat(bluecraft-agentic-docs): add agentic docs skill templates Add the Bluecraft Agentic Docs skill with guidance for maintaining root `AGENTS.md` files and `agent-docs/` trees. Include OpenAI agent metadata plus reference templates and checklists for root routing, rule docs, inventory docs, and refactor validation. --- skills/bluecraft-agentic-docs/SKILL.md | 140 ++++++++++++++++++ .../bluecraft-agentic-docs/agents/openai.yaml | 4 + .../references/child-doc-template.md | 19 +++ .../references/inventory-doc-template.md | 54 +++++++ .../references/refactor-checklist.md | 19 +++ .../references/root-agents-template.md | 29 ++++ .../references/routing-patterns.md | 56 +++++++ .../references/rule-doc-template.md | 35 +++++ 8 files changed, 356 insertions(+) create mode 100644 skills/bluecraft-agentic-docs/SKILL.md create mode 100644 skills/bluecraft-agentic-docs/agents/openai.yaml create mode 100644 skills/bluecraft-agentic-docs/references/child-doc-template.md create mode 100644 skills/bluecraft-agentic-docs/references/inventory-doc-template.md create mode 100644 skills/bluecraft-agentic-docs/references/refactor-checklist.md create mode 100644 skills/bluecraft-agentic-docs/references/root-agents-template.md create mode 100644 skills/bluecraft-agentic-docs/references/routing-patterns.md create mode 100644 skills/bluecraft-agentic-docs/references/rule-doc-template.md diff --git a/skills/bluecraft-agentic-docs/SKILL.md b/skills/bluecraft-agentic-docs/SKILL.md new file mode 100644 index 0000000..7347725 --- /dev/null +++ b/skills/bluecraft-agentic-docs/SKILL.md @@ -0,0 +1,140 @@ +--- +name: bluecraft-agentic-docs +description: Use when creating, updating, splitting, merging, reviewing, auditing, or deleting the AGENTS.md at the root of the current Git working tree, or Markdown files inside any agent-docs/ directory +--- + +# Agentic Docs + +## Overview + +Use this skill to maintain agent-facing documentation trees centered on the `AGENTS.md` at the root of the current Git working tree and child instruction documents in `agent-docs/`. + +Treat covered documents as instruction documents. If one applies in scope, it must be followed, not treated as optional background reading. + +## When To Use + +Use this skill when a task involves any of the following: + +- creating or editing the `AGENTS.md` at the root of the current Git working tree +- creating, editing, splitting, merging, or deleting Markdown files inside any `agent-docs/` directory +- changing routing between `AGENTS.md` and `agent-docs/` files +- auditing whether an agentic documentation tree is coherent, minimal, and fully connected + +Do not use this skill for end-user documentation, product manuals, README content that is not part of the agentic documentation tree, or project-specific business rules that do not govern agent-facing docs. + +## Core Rules + +- Each covered document should own one clear topic. +- Titles and filenames should state purpose directly. +- The opening section should explain what the document governs, when it applies, and that it must be followed in scope. +- Rules should be actionable, not slogan-like. +- Prefer standard Markdown headings and lists over wrapper tags for structure. +- Write for maintainers. State actions, constraints, and decision criteria directly. +- Do not mix general agentic-documentation rules with project-specific business rules, product instructions, media planning, or end-user documentation guidance in the same general-purpose file. +- Treat the `AGENTS.md` at the root of the current Git working tree as the primary routing entrypoint. +- Keep common, repository-wide constraints in that root `AGENTS.md`. +- In monorepos, keep common constraints in the root `AGENTS.md` and place subproject-specific constraints in the relevant `agent-docs/` directory near that subproject. +- Put project-specific or topic-specific constraints in the relevant child documents under `agent-docs/`. +- The root `AGENTS.md` should reference only the instruction documents that are actually needed as next-step routing targets. +- The combined set of the root `AGENTS.md` and active `agent-docs/` files should form a connected documentation tree. +- Each active instruction document must be reachable through explicit references from the root entrypoint. +- Do not leave orphan instruction documents. +- Keep one authoritative home for each rule; link instead of duplicating. +- When a file, path, or rule is obsolete, remove or update it in the same change instead of leaving stale routing behind. +- Prefer stable, semantic filenames. +- Unless a specific instruction explicitly defines another base path, treat every path mentioned in the conversation or in agentic documentation as relative to the root of the current Git working tree, not relative to the current file. +- Make routing directional and explicit: a parent document should point to the child documents that refine it. +- Match the child document shape to the document's job. Do not force inventory or registry documents into the same structure as rule or policy documents. + +## Workflow + +1. Identify the change type. + +Choose the smallest accurate category: + +- root routing change +- repository-wide constraint change +- child instruction document change +- documentation-tree refactor + +2. Identify the child document type. + +Use the smallest fitting type: + +- rule doc: instructions, constraints, decision rules, policy, or workflow guidance +- inventory doc: maintained list, registry, media plan, page-by-page backlog, or cleanup queue +- hybrid doc: only when one short inventory is inseparable from the governing rules; otherwise split it + +If a document spends most of its space enumerating items to maintain, do not force it into the rule-doc shape. + +3. Decide rule placement. + +Use this placement standard: + +- Root `AGENTS.md`: routing entrypoint and repository-wide constraints +- `agent-docs/` child docs: scoped instructions for a topic, project area, or workflow + +If a rule only matters within one child topic, do not keep it in the root file. + +4. Update routing explicitly. + +- Add or adjust references from the root file to the necessary child files. +- If a child file introduces narrower subtopics, route to them explicitly. +- Avoid extra routing layers unless they materially reduce ambiguity. +- When moving project-specific constraints out of the root `AGENTS.md`, replace them with an explicit route to the new child document instead of leaving the route implicit. + +See `references/routing-patterns.md` for routing patterns and anti-patterns. + +5. Remove stale structure. + +- Delete obsolete files, references, and filenames in the same change. +- If a split removes the need for an intermediate layer, remove that layer. +- If a new file is added, ensure it is reachable from the root entrypoint. + +6. Apply the standard document shape. + +- For a root file update, use `references/root-agents-template.md`. +- For a rule or policy child doc, use `references/rule-doc-template.md`. +- For an inventory or registry child doc, use `references/inventory-doc-template.md`. +- Use `references/child-doc-template.md` only as the compatibility entrypoint when you need help choosing between child templates. +- Use standard Markdown headings and lists unless a narrower instruction requires another structure. +- Treat inventory entry fields as a recommended starter shape, not a fixed schema. Keep only the fields that materially help maintainers scan and update the inventory. + +Adapt the wording to the repository, but preserve the routing and scope model. + +7. Verify. + +- Check that the root `AGENTS.md` still acts as the primary entrypoint. +- Check that every active child doc is reachable from the root through explicit references. +- Check that no rule is duplicated across multiple active files without a clear reason. +- Check that rule docs and inventory docs are not mixed together without a clear reason. +- Run the validation command actually used by the repository if the change affects rendered documentation or project checks. + +Use `references/refactor-checklist.md` as the final pass. + +## Templates And References + +- Root file template: `references/root-agents-template.md` +- Rule child template: `references/rule-doc-template.md` +- Inventory child template: `references/inventory-doc-template.md` +- Child template chooser: `references/child-doc-template.md` +- Routing patterns: `references/routing-patterns.md` +- Refactor checklist: `references/refactor-checklist.md` + +Read only the reference files needed for the current task. + +## Completion Checklist + +- Does each covered document own one clear topic? +- Does the filename clearly express the document's purpose? +- Does the opening explain the document's purpose, trigger, and in-scope follow requirement? +- Is the `AGENTS.md` at the root of the current Git working tree still the primary routing entrypoint? +- Is every active `agent-docs/` file reachable from the root through explicit references? +- Are obsolete paths, filenames, and documents removed? +- Were obsolete index layers removed? +- Does each rule live in one authoritative place? +- Is the default path basis still the root of the current Git working tree unless an instruction explicitly overrides it? +- Are repository-wide rules still in the root file? +- Are topic-specific rules still in child files? +- Are project-specific rules still kept in project-specific documents rather than the general rules layer? +- Was the relevant repository validation command run if needed? diff --git a/skills/bluecraft-agentic-docs/agents/openai.yaml b/skills/bluecraft-agentic-docs/agents/openai.yaml new file mode 100644 index 0000000..daa246e --- /dev/null +++ b/skills/bluecraft-agentic-docs/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Bluecraft Agentic Docs" + short_description: "Maintain AGENTS.md and agent-docs trees" + default_prompt: "Use $bluecraft-agentic-docs to maintain the AGENTS.md and agent-docs documentation tree." diff --git a/skills/bluecraft-agentic-docs/references/child-doc-template.md b/skills/bluecraft-agentic-docs/references/child-doc-template.md new file mode 100644 index 0000000..122a82a --- /dev/null +++ b/skills/bluecraft-agentic-docs/references/child-doc-template.md @@ -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 you 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, media plans, registries, page-by-page backlogs, or cleanup queues. +- 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 route new work to the specific template that matches the document's job. diff --git a/skills/bluecraft-agentic-docs/references/inventory-doc-template.md b/skills/bluecraft-agentic-docs/references/inventory-doc-template.md new file mode 100644 index 0000000..ba3124a --- /dev/null +++ b/skills/bluecraft-agentic-docs/references/inventory-doc-template.md @@ -0,0 +1,54 @@ +# 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, per-page suggestions, registries, migration queues, or cleanup lists. + +## Recommended Shape + +```md +# + + + +## Use This For + +- + +## Do Not Use This For + +- + +## Maintenance Rules + +- + +## Entries + +### + +#### + + + +Source: +- + +Status: +- + +Notes: +- + +## Maintenance Checklist + +- +``` + +## 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. diff --git a/skills/bluecraft-agentic-docs/references/refactor-checklist.md b/skills/bluecraft-agentic-docs/references/refactor-checklist.md new file mode 100644 index 0000000..87fb048 --- /dev/null +++ b/skills/bluecraft-agentic-docs/references/refactor-checklist.md @@ -0,0 +1,19 @@ +# 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 `AGENTS.md` at the root of the current Git working tree still the primary routing entrypoint? +- 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 remove any orphan instruction docs created by the refactor? +- 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? +- 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? +- Did you keep routing depth minimal? +- If the repository has a validation command, did you run it? diff --git a/skills/bluecraft-agentic-docs/references/root-agents-template.md b/skills/bluecraft-agentic-docs/references/root-agents-template.md new file mode 100644 index 0000000..3a3846d --- /dev/null +++ b/skills/bluecraft-agentic-docs/references/root-agents-template.md @@ -0,0 +1,29 @@ +# Root `AGENTS.md` Template + +Use this structure for the `AGENTS.md` at the root of the current Git working tree. + +## Recommended Shape + +```md +# Root Entry + +- State that this file is the primary routing entrypoint for the repository's agentic documentation tree. +- Define the default path basis. + +# Common Constraints + +- Keep repository-wide rules here. +- Do not repeat topic-specific rules that belong in child docs. + +# Required Instructions Before Editing + +- Route to the required child instruction docs. +- Use explicit "Read and follow ..." wording. +``` + +## Notes + +- Keep this file short. +- Treat this file as an instruction document, not a passive index. +- Route to child docs only when they are actually needed. +- Do not turn the root file into a dump of all topic-specific rules. diff --git a/skills/bluecraft-agentic-docs/references/routing-patterns.md b/skills/bluecraft-agentic-docs/references/routing-patterns.md new file mode 100644 index 0000000..6ca2e17 --- /dev/null +++ b/skills/bluecraft-agentic-docs/references/routing-patterns.md @@ -0,0 +1,56 @@ +# Routing Patterns + +## Preferred Patterns + +### Root -> Topic Docs + +Use when the repository has a small set of clearly separate instruction topics. + +```md +# Required Instructions 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 when one project-specific document can route to several closely related leaf docs. + +```md +AGENTS.md + -> agent-docs/project-guidelines.md + -> agent-docs/topic-a.md + -> agent-docs/topic-b.md +``` + +Use this only when the intermediate layer reduces ambiguity or repeated routing text. + +### 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 routing 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 route 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 + +## Routing 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 path from the root `AGENTS.md` to that document. + +The root `AGENTS.md` should route only to the next instruction documents that are actually needed. Do not add unnecessary next-step links just for completeness. diff --git a/skills/bluecraft-agentic-docs/references/rule-doc-template.md b/skills/bluecraft-agentic-docs/references/rule-doc-template.md new file mode 100644 index 0000000..74199fb --- /dev/null +++ b/skills/bluecraft-agentic-docs/references/rule-doc-template.md @@ -0,0 +1,35 @@ +# 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 +# + + + +## Applies To + +- + +## Does Not Apply To + +- + +## + +- + +## Checklist + +- +``` + +## Notes + +- Make the scope explicit. +- Keep the document responsible for one topic. +- Use semantic filenames and headings. +- State the user or maintainer decision directly: what to do, what to avoid, and how to choose. +- Prefer linking to inventories, examples, or narrower child docs instead of embedding long registries inline.