bluecraft/skills/bluecraft-agentic-docs/SKILL.md

name, description

name	description
bluecraft-agentic-docs	Use when creating, updating, splitting, merging, reviewing, auditing, deleting, or refactoring the root AGENTS.md or agent-docs files, especially when cross-references, child docs, or orphan docs may need cleanup

Maintain AGENTS.md and agent-docs

Overview

Use this skill to maintain the root AGENTS.md file and the applicable agent-docs/ files in the current Git working tree.

Treat covered files as required instructions. 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 explicit references between AGENTS.md and agent-docs/ files
• auditing whether AGENTS.md and agent-docs/ stay coherent, minimal, and fully connected

Do not use this skill for end-user documentation, product manuals, README content that is not part of AGENTS.md or agent-docs/, or project-specific business rules that do not govern agent-facing docs.

Quick Triage

1. Identify the files and scope.

Start with the concrete files and scope that need to change:

• root AGENTS.md
• one or more agent-docs/ files
• both root and child files
• documentation-tree refactor

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.

Core Constraints

• 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.
• When referencing repository files from AGENTS.md or agent-docs/, prefer plain repository-relative paths in backticks such as agent-docs/example.md, not Markdown links.
• Do not embed machine-local absolute filesystem paths such as /home/....
• 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.
• Keep common, repository-wide constraints in the 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/.
• Treat the root AGENTS.md as the starting point for required agent-docs.
• Keep AGENTS.md focused on the next reading decision: reference only the agent-docs files that are actually needed.
• 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 references behind.
• Delete or update any agent-docs file that is no longer referenced from the root AGENTS.md.
• Prefer stable, semantic filenames.
• Unless a specific instruction explicitly defines another base path, treat every path mentioned in the conversation or in the docs as relative to the root of the current Git working tree, not relative to the current file.
• Keep references directional and explicit: a parent document should point to the child documents that refine it.
• Every active agent-docs file must still be reachable from the root AGENTS.md.
• 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.

Common Mistakes

• Putting topic-specific rules in the root AGENTS.md when they belong in one child doc.
• Adding a new agent-docs file without adding an explicit reference path from the root AGENTS.md.
• Repeating the same rule in multiple active files instead of linking to one authoritative source.
• Splitting a document only for symmetry, without reducing ambiguity or maintenance cost.
• Forcing a maintained list into a rule-doc shape instead of using an inventory doc.

When Not To Split

• Do not split when one short document already governs one clear topic.
• Do not add an intermediate file that only repeats links without adding scope or decision logic.
• Do not create a new child doc when it would not reduce ambiguity, repetition, or maintenance cost.

Verification

• Read references/refactor-checklist.md as the final pass.
• Check that the root AGENTS.md is still the starting point for required agent-docs.
• 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.

Validation Steps

• Confirm agents/openai.yaml still matches the skill title, scope, and trigger language.
• Confirm every file in references/ is directly referenced from this SKILL.md.
• Confirm there are no stale filenames or old terms left behind after renames.
• Confirm one concept still uses one term across SKILL.md and references/.

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
• Linking patterns: references/linking-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 starting point for required agent-docs?
• 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?