How to use the Technical Documentation agent skill

What an agent skill is and what this one makes the agent do

An agent skill is a folder of instructions that an AI agent loads when a task matches it. This skill, named technical-documentation, is licensed MIT and is aimed at repository documentation and agent instruction files.

Once installed, the agent follows a fixed sequence rather than improvising. It inventories the governance and docs files in scope, including AGENTS.md, CONTRIBUTING.md, alias files such as CLAUDE.md or .cursorrules, docs folders and READMEs. It then checks them for drift, broken commands and policy conflicts.

• Classifies the task as build or review, and as brownfield (existing project) or evergreen (long-lived, timeless wording).
• Treats AGENTS.md as the canonical instruction file when present and keeps alias files as compatibility surfaces.
• Looks for missing files, broken commands, stale paths and conflicting rules.
• Fixes high-confidence defects in the same pass unless you ask for report-only mode.
• For large repositories, can delegate discovery and review to sub-agents and merge their findings into one prioritized fix plan.

Install the skill from the ZIP or the Claude apps

There are two routes. Download the ZIP for this skill from our page and unzip it. For a personal setup, place the unzipped folder in ~/.claude/skills/. To limit it to one project, place it in that project's .claude/skills/ folder.

If you use the Claude apps instead, upload the skill under Settings → Capabilities → Skills.

• Personal install: unzip into ~/.claude/skills/ so it is available across your projects.
• Project install: unzip into the .claude/skills/ folder inside the repository, so teammates who clone it get the skill too.
• Claude apps: upload through Settings → Capabilities → Skills.

Trigger the skill with natural requests

You do not need a special command. Describe the documentation job in plain language and mention the files or problem involved. The skill's description covers building and reviewing technical docs and agent instruction files, so requests about those areas are the ones that match.

Say whether you want a review only. The skill applies fixes by default, so add a phrase such as report only if you want findings without edits.

• "Review our README, docs folder and AGENTS.md for drift and broken commands. Report only, don't edit."
• "Our CLAUDE.md and .cursorrules disagree with AGENTS.md. Make AGENTS.md the source of truth and keep the others as aliases."
• "Build a contributor guide for this open-source project based on CONTRIBUTING.md and the existing docs."
• "Audit the whole repo's documentation. Use sub-agents if it helps, and give me one prioritized fix plan."

Examples of what the agent returns

For a review, expect a list of autodetected issues, the fixes applied (or the findings if you asked for report-only), and validation notes saying what was checked and what remains. For governance work, expect a summary of how the instruction files map to AGENTS.md and a note on any conflicts.

For large audits, the agent can run discovery, governance and framework checks as separate sub-agents and then merge the results into a single plan, with blockers listed before non-blocking improvements.

What the skill needs and where it is not a fit

The skill needs access to the repository files the agent reads and edits. Sub-agent support in the host agent is optional and only matters for large audits. The skill does not run scripts and does not use the network. It cites external sources such as the Matt Palmer and OpenAI principles, but those are referenced in its files and not bundled as code.

Skip the skill for simple one-off text edits, where its process adds nothing. Also skip it for projects with no docs framework or governance files, because much of the workflow would have nothing to act on.

• Requires: access to repository files the agent reads and edits.
• Optional: sub-agent support for large audits.
• Runs scripts: no. Uses network: no.

Safety notes before you let it edit

The skill may apply fixes directly by default. Changes can introduce unwanted edits, so work in a branch, review the diff, or ask for report-only mode first. Be especially careful with AGENTS.md and CONTRIBUTING.md, since changes there alter how future agents and contributors work.

• Commit or branch before running a full audit so you can revert.
• Use report-only mode for a first pass on an unfamiliar repository.
• Review every change to governance files before merging.