agent-documentation · git:20261025.e4e10c6 · 2026-10-25 · sha256 e40a83a0ffd3fcf7

agent-documentation git:20261025.e4e10c6A

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

No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_tighdw3nsqiqvixd/e40a83a0ffd3fcf7d7f50b71a6c697b1d40aa286d301141c0c718f09bdf8cb1a.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` whenever authoring, reviewing, auditing, or maintaining project-authored agent documentation or any human-facing writing in an asset owned by that documentation. 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 composition once 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 and classify every secondary occurrence as routing, surface-specific application, rationale, example, 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.
- 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. Read every applicable `AGENTS.md` file before evaluating other project documentation.
2. Identify the project’s agent documentation surfaces, authority model, project-specific documentation skills, and skill management metadata.
3. 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).
4. 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 relay or decision capture prompt assets, follow [Maintain Prompt Assets](references/compose-documentation.md#maintain-prompt-assets). Use `agent-task-relay` for their operational content contract, not their 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

1. State the durable detail being changed or evaluated in one sentence.
2. Use the selected local or fallback authority model to identify its expected owner.
3. Search applicable project-authored agent documentation for existing definitions, rationale, inventories, and links concerning that detail.
4. Name one canonical owner and identify every other document that should link to it or remove a stale paraphrase.
5. Don’t edit until one owner can be named. Don’t choose 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. Re-read every applicable `AGENTS.md` file and each in-scope documentation file that the current task has not already loaded unchanged. Use Git status and diff to identify what changed since it was loaded.
2. 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.
3. For every in-scope change to a direct-path surface, compare its before-and-after context footprint. In a review or audit, report unjustified growth without editing.
4. 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

- For a change, identify the canonical owner and any redundant definitions removed or replaced with links. Follow the applicable communication policy for validation reporting.
- 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.