agent-documentation · git:20261110.bb488e2 · 2026-11-10 · sha256 fcb8e0564713f8d6

agent-documentation git:20261110.bb488e2A

Immutable. This exact content never changes and is served at /api/v1/blob/fcb8e0564713f8d6.

No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_tighdw3nsqiqvixd/fcb8e0564713f8d623584ff166b2997d1e8e9e8102fd49f94498af0a6b30b5a9.json

Then /plugin install agent-documentation@markdownregistry-tighdw3nsqiqvixd in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.

---
name: agent-documentation
description: |-
    Use for creating, editing, reviewing, auditing, or maintaining project-authored agent documentation, including `AGENTS.md`, `.agents/PROJECT.md`, skill documentation, reusable handoff and decision capture prompts, templates, canonical public-surface assets, and public skill READMEs. Also use for project agent documentation setup, repository independence, cross-repository alignment, documentation authority, ownership, composition, routing, redundancy, and token efficiency.

    Defer agent documentation maintenance to a more specific project workflow when one exists. Exclude ordinary source, script-only work without documentation changes, other consumer documentation, public API documentation, release notes, and source comments alone.

metadata:
    internal: true
---

# Project Agent Documentation

## Apply Documentation Principles

- Apply `human-facing-writing` when the authorized work creates, changes, or evaluates wording, rendered meaning, reading path, or information architecture in project-authored agent documentation or its assets, including descriptions and other metadata. Purely mechanical work that preserves wording, rendered meaning, reading path, and information architecture doesn’t require that composition, but retains applicable domain and validation requirements. Preserve the agent documentation contract and exact machine-readable, externally owned, and quoted content. Treat this as source authoring composition rather than an installed runtime dependency. When maintaining `human-facing-writing` itself, apply the same criterion without routing recursively.
- Apply the global **Explicit user direction** policy to this workflow’s procedural requirements and conventions, including its routed references. Preserve requested scope and every applicable approval, mutation, security, and submission boundary.
- Before deferring a section, separate and rehome the rules that only look domain-specific. Ensure the destination skill’s description states every applicability condition supported clients must recognize, including conditions encountered during a task. Keep any prerequisite needed to recognize those conditions on the surface that always loads. Retain an explicit route only for deliberate skill composition or when the description can’t carry the required condition.
- Give any identifier scheme referenced from code or documentation, such as numbered checks or requirement labels, one canonical definition in the same repository. Drop the identifiers when no such definition exists, because a reader can’t resolve the reference or tell which members are missing.
- Give each proposition one canonical definition. Secondary occurrences must serve a distinct purpose, such as routing, application, rationale, examples, or required standalone context. Remove a secondary occurrence when it merely paraphrases the definition. Keep it only when its distinct role requires wording there, using the shortest wording that preserves that role. When a secondary occurrence contains a more complete rule than its expected owner, promote the complete rule to the canonical owner before removing or reducing the secondary copy.
- Optimize the complete context path loaded for a task rather than an individual file’s size. Treat applicable `AGENTS.md` files, skill descriptions, and `SKILL.md` entrypoints as direct-path context. Keep wording there only when most invocations need it. Move coherent conditional detail into a conditional reference in an existing skill that owns the relevant domain when the saved direct-path context exceeds the navigation cost.
- Specify required outcomes, constraints, and decision criteria. Prescribe a method, sequence, or intermediate record only when it is necessary for correctness, a safety boundary, interoperability, or an explicitly chosen workflow. Otherwise, leave execution to the agent’s judgment. Don’t add reminders that merely restate following instructions or using available context.
- Weigh a deferral against its own overhead. A model-invocable skill’s description adds recurring context when the client exposes it, so deferring content that doesn’t clearly exceed that overhead costs more than it saves. Move smaller conditional detail into a reference of an existing skill instead.
- Write instructions that require no conversational context. Define non-obvious terms. Don’t make a project’s documentation depend on `agent-documentation`, `skill-development`, their canonical repository, or their installation paths merely because those tools were used to author it.

## Resolve Local Documentation Model

1. Identify the project’s agent documentation surfaces, authority model, project-specific documentation skills, and skill management metadata.
2. Use a locally defined authority or ownership model when one exists. When an ownership decision is required and the project hasn’t defined a model, read the [Default Agent Documentation Authority Model](references/default-agent-documentation-authority-model.md).
3. Treat generated, managed, third-party, or vendored skills as outside project-authored documentation unless the user explicitly includes them and applicable project instructions permit the work.

## Choose Workflow

- When the task affects a project-authored skill’s documentation, metadata, assets, category, or supported installation, apply `skill-development` for the skill-specific contracts before the affected work. Also apply it when a global instruction changes or is evaluated and supplies a public skill mirror or standalone default, even when the request names only the global source. Compose once, then continue the shared workflow here rather than restarting either skill.
- For reusable prompt assets, follow [Maintain Prompt Assets](references/compose-documentation.md#maintain-prompt-assets). Use `subagent-review-flow` for coordinated reviewer prompts and `agent-task-relay` for general relays or decision capture prompts. The selected skill owns the operational content contract, not the authoring lifecycle.
- When establishing or assessing repository independence, setting up project agent documentation, selecting or relocating project requirements, or aligning documentation across repositories, follow [Repository Independence](references/repository-independence.md) before resolving ownership or composing changes.
- For a documentation-only review or audit, inspect implementation and adjacent tests only as bounded evidence for a specific observable contract, then stop once the claim is established. Don’t assess algorithms, internal structure, language idioms, performance, dead code, duplication, or general test quality unless the user explicitly includes implementation. Evaluation criteria such as security, maintainability, or project values apply within the resolved scope and don’t expand it.
- When the resolved scope explicitly includes implementation, follow applicable project, domain, and language implementation and validation workflows for internal concerns. Keep the agent documentation pass focused on contract consequences, and update agent documentation only when the contract, routing, or documented invocation changes.
- For an explicit change, including a request that also uses review or audit language, use the change workflow. Treat inspection as the evidence gathering phase, then resolve the canonical owner, compose the change, and validate the final contents.
- For a standalone ordinary review, keep the reviewed material read-only. Resolve the canonical owner and validate the existing contents without editing them.
- For a standalone audit, keep the audited material read-only. Follow an applicable model-invocable project audit workflow when one exists. Otherwise, start from Git-tracked paths, add only explicitly named untracked documentation when local policy permits it, inspect the resolved documentation scope, report findings, and stop without formatting or changing that material.
- Treat naming and prose punctuation policies as file-scoped unless a narrower surface contract defines another scope.

## Resolve Canonical Owner

Use the selected local or fallback authority model to resolve ownership. Search applicable project-authored agent documentation for existing definitions, rationale, inventories, and links concerning the detail. Keep it with one canonical owner and align secondary documents with that owner. Resolve material ownership ambiguity before editing rather than choosing an owner merely because the detail already appears there.

## Compose Changes

Before editing, follow [Compose Documentation](references/compose-documentation.md). Reviews and audits use its applicable authoring rules as criteria without composing or mutating content.

## Validate Documentation

Use [Select Validation Scope](references/validate-documentation-changes.md#select-validation-scope) before loading detailed checks. Apply the global **Invariant scope** policy. When Markdown linting is permitted, follow [Check Markdown](references/check-markdown.md).

### Run Complete-Scope Checks

For every change, review, or audit:

1. For each affected proposition or shared wording contract, search the complete applicable documentation family for its distinctive wording and close semantic variants. Apply the [Documentation Boundary Checks](references/documentation-boundary-checks.md) to routed or layered surfaces. When a global instruction changes or is evaluated, identify every affected public skill mirror or standalone default, including rephrased variants, and apply `skill-development` to align each with public policy. Confirm that one normative definition remains and that every secondary occurrence has a distinct required role or links to the canonical owner.
2. When guidance is added, expanded, or redistributed, assess its effect on the complete context loaded for affected tasks. In a review or audit, report unjustified growth without editing.
3. When an in-scope change moved guidance from a `SKILL.md` into references, map every removed proposition to its destination and confirm that every task that previously received it still deterministically loads that destination. Treat a missing behavioral distinction, condition, exception, or route as a contract regression.

For a review or audit, use only read-only diagnostics and identify anything that couldn’t be verified.

### Complete Change Validation

For changes, complete [Validate Documentation Changes](references/validate-documentation-changes.md) after the shared checks above and before delivery. Reviews and audits remain on the read-only validation path.

## Report Results

Apply the global **Validation reporting** policy.

- For a change, identify the canonical owner and any redundant definitions removed or replaced with links.
- For a review or audit, lead with concrete findings, their evidence, the canonical owner, and the suggested fix.
- Report any ownership decision that remains unresolved instead of distributing the detail across multiple documents.