Agent Skill for Documentation

An agent skill for documentation is a reusable procedure for drafting, reviewing, and maintaining docs from trusted source material. It tells the agent which sources to inspect first, which document type is being produced, which claims need evidence, where uncertainty must be surfaced, and how the draft should be verified before publication.

That is a different job from "write a help article." Documentation work is usually a chain of evidence: code changed, an API contract changed, a support pattern emerged, a release shipped, or a migration path needs explanation.

OpenAI's Codex Agent Skills docs describe skills as packages of instructions, references, scripts, and assets. Anthropic's Agent Skills overview uses a similar frame: skills package domain expertise for repeatable work. Documentation is a strong fit because the expert judgment is not only style. It is deciding what source is authoritative, what belongs in which doc type, and what needs verification before the answer becomes public.

If you are still deciding whether your workflow deserves a skill at all, start with What Is an Agent Skill?. For documentation, the short version is this: use a skill when the output must be repeatable, source-backed, and reviewable.

Documentation deserves a skill when the task repeats and accuracy depends on source discipline. A one-off announcement draft may only need a prompt. A weekly release-note workflow that reconciles pull requests, changelog entries, customer impact, and upgrade instructions should be a skill.

Documentation job	What the skill should inspect	Why a skill helps
API reference update	OpenAPI schema, SDK code, examples, generated docs	Prevents parameter drift and broken examples
Migration guide	Old behavior, new behavior, release notes, compatibility flags	Forces before/after instructions and edge cases
Release notes	Merged PRs, issue tracker, changelog, rollout notes	Separates shipped facts from marketing interpretation
How-to guide	Product workflow, screenshots, prerequisites, error states	Keeps steps ordered around the user's task
Concept explanation	Architecture docs, source examples, glossary, support questions	Prevents vague definitions and missing tradeoffs
Docs gap review	Current docs, source code, changelog, support tickets	Produces a prioritized maintenance backlog

Diataxis is useful here because it splits documentation into tutorials, how-to guides, reference, and explanation (Diataxis). A good documentation skill should know which mode it is in. A migration guide that reads like a tutorial will bury the breaking change. An API reference page that reads like a concept essay will frustrate a developer trying to find a parameter.

Generic docs prompts fail when they ask for "clear documentation" but do not define the job. The skill should make the task concrete enough that a reviewer can tell whether the agent did the right work.

A documentation skill should include a source hierarchy. Without one, the agent may give equal weight to stale docs, product guesses, internal chat, and the current implementation.

Trust level	Source examples	Rule
Primary	Current code, API schema, generated reference, merged PR, official docs, release tag	Use for factual claims and examples
Secondary	Existing docs, design docs, support threads, community questions, customer tickets	Use for context, wording, and known confusion
Tertiary	Old drafts, blog posts, roadmap notes, meeting notes, chat history	Use only with caveats or reviewer confirmation

The rule should be explicit: if primary and secondary sources disagree, the draft must say so instead of quietly choosing the nicer sentence. That matters for docs-as-code workflows, where docs live near the product and move through review, automation, and publishing steps (Write the Docs docs-as-code guide). A documentation skill should reinforce that model: inspect the source, make the change, and leave review evidence.

If the API schema shows that visibility is required, the skill can document that. If the product rationale exists only in a Slack thread, the skill should mark it as unverified or ask for the release brief.

Before writing the long body of a skill, define its contract. This mirrors the broader advice in How to Write an Agent Skill That Actually Works: name one repeatable job, define trusted inputs, require visible completion evidence, and add stop rules.

A strong documentation skill contract includes:

• Job: the exact documentation task, such as "update API docs for a changed endpoint" or "draft release notes from merged PRs."
• Audience: developer, admin, end user, support engineer, partner, buyer, or internal teammate.
• Doc type: tutorial, how-to, reference, explanation, release note, migration guide, or troubleshooting page.
• Trusted sources: file paths, schemas, docs URLs, issue queries, changelog locations, screenshots, or API explorers.
• Output shape: Markdown article, changelog entry, reference patch, docs gap report, or review findings.
• Verification evidence: commands run, examples checked, links opened, screenshots captured, or unresolved questions.
• Stop rules: conditions where the agent must pause instead of guessing.

The stop rules matter most when the agent has tools. A docs skill may read a repository, use an MCP server to inspect issues, capture screenshots, or open a docs platform. The Model Context Protocol introduction explains how apps connect models to external tools and data sources. A documentation skill should say when the agent may read, when it may edit local files, and when it must ask before publishing to a live docs site.

Use this sequence as the default workflow:

1. Identify the exact documentation job and audience.
2. Classify the doc type: tutorial, how-to, reference, explanation, release note, migration guide, or troubleshooting page.
3. Read the user brief and existing target page.
4. Inspect primary sources before drafting.
5. Capture facts, assumptions, unknowns, and conflicts separately.
6. Draft in the required structure and voice.
7. Check every command, parameter, screenshot, and procedural step against source material.
8. Add examples only if they are source-backed or clearly labeled as illustrative.
9. Return the draft with source notes, verification steps, and open questions.

For public docs, the quality bar is stricter than grammatical correctness. The draft should help a real developer ship an integration, avoid a known mistake, recover from an error, or understand a tradeoff they would otherwise learn through support.

Google's developer documentation style guidance is useful because it emphasizes task-oriented writing, clear headings, and writing for the user rather than the internal organization (Google developer documentation style guide). That is also the right instinct for a skill: optimize for what the reader needs to do next.

The skill should change behavior by doc type.

Doc type	Required checks	Common failure
API reference	Parameter names, types, defaults, auth, errors, examples	Example compiles against an old SDK
Migration guide	Old path, new path, breaking changes, rollback, compatibility window	Explains the happy path but misses mixed-version states
Release notes	Shipped change, user impact, action required, links to details	Lists internal work without telling users what changed
How-to guide	Prerequisites, ordered steps, expected result, troubleshooting	Assumes setup that the reader has not done
Troubleshooting	Symptom, cause, diagnosis, fix, prevention	Gives fixes without helping users confirm the cause
Explanation	Concept, tradeoffs, boundaries, examples, links to procedures	Becomes abstract and impossible to apply

Named examples help the skill avoid abstraction. Stripe's docs are a good model for upgrade-sensitive documentation: API versions, changelog entries, and upgrade guides are distinct surfaces, and the reader can move from reference detail to migration guidance when behavior changes (Stripe API upgrades). Twilio's changelog separates shipped changes from the deeper docs users may need next (Twilio Changelog). Keep a Changelog is useful because it pushes release notes toward human-readable categories instead of raw commit lists (Keep a Changelog).

Those examples point to a practical rule: do not force one docs surface to do every job. API reference, release notes, and migration guides should link to each other without collapsing into the same article.

## Documentation Source Rules

- Treat current code, generated API schemas, official product docs, and merged release PRs as primary.
- Treat old docs as examples of voice and structure, not as truth.
- If sources conflict, report the conflict and do not silently resolve it.
- Do not invent behavior, parameters, limits, screenshots, or product rationale.
- Mark missing source material as "unknown" and ask for the owner or source.
- Include source links, issue IDs, or file paths for claims that affect implementation.

## Workflow

1. Identify the doc type and target reader.
2. Read the existing page before drafting.
3. Inspect primary sources.
4. Draft the change.
5. Verify commands, examples, links, and edge cases.
6. Return the draft, source notes, open questions, and verification checklist.

## Stop Rules

- Stop if the source of truth is missing.
- Stop before publishing to a live docs platform.
- Stop if a public doc would reveal internal-only details.
- Stop if a product claim is not supported by release or product evidence.

This keeps the agent from converting uncertainty into confident prose. It also makes review easier because the output contains the evidence path, not just the polished draft.

Consider a small SDK change: client.skills.publish() now requires an explicit visibility value. A weak docs prompt might update one paragraph and miss the examples. A documentation skill can define the full job.

The skill should require the agent to inspect the merged code, generated types, existing examples, release notes, and any migration guide. It should find every old call shape, update the reference page, add a migration note if the old call breaks, and run or at least syntax-check snippets. If the code shows a required field but the product reason is not documented, the skill should mark the reason as unknown instead of inventing one.

The output might say:

Updated:
- `docs/api/skills.md`: added required `visibility` parameter.
- `docs/examples/publish-skill.md`: updated Node example.
- `docs/migrations/2026-05-visibility.md`: added before/after call shape.

Verified:
- Compared against `app/src/sdk/skills.ts`.
- Checked generated TypeScript type `PublishSkillInput`.
- Did not run SDK examples because dependencies are unavailable.

Open question:
- Product rationale for requiring explicit visibility is not present in the release brief.

Documentation failures are rarely only writing failures. They are source, example, verification, and ownership failures.

Release notes are another strong use case because the source material is scattered. The agent may need merged pull requests, issue labels, customer impact notes, feature flags, rollout status, and deprecation dates. The skill should not simply summarize commits. A recurring community complaint is that writers rely on partial engineering input and cannot manually verify every change; the skill should make that dependency visible instead of hiding it (Reddit technical writing discussion).

For a breaking API change, the release-note skill should require:

• the shipped version or date
• who is affected
• what changed
• whether action is required
• the migration path
• the deadline or compatibility window
• links to reference docs and examples

The migration guide should then carry the procedural detail: before/after code, changed error cases, testing advice, rollback constraints, and known edge cases. Release notes should be short enough to scan. Migration guides should be complete enough to execute.

A docs gap review skill is useful when teams know the docs are drifting but do not know where to start. The skill should compare current docs against the product surface and return a prioritized backlog, not a rewritten website.

For example, if support tickets show repeated confusion about OAuth callback URLs, the skill might inspect the setup guide, current app settings, error logs, and support examples. A strong finding would be:

High - OAuth setup guide omits the production callback URL requirement.

Evidence:
- `docs/integrations/oauth.md` only shows localhost.
- Current app settings require both development and production callback URLs.
- Three support tickets in June mention `redirect_uri_mismatch` after deployment.

Recommended doc change:
- Add a production callback URL step before app review.
- Add a troubleshooting row for `redirect_uri_mismatch`.

That is more useful than "improve OAuth docs" because it identifies the reader problem, missing source-backed step, and practical fix.

Documentation platforms like Mintlify and ReadMe show a useful operating pattern: developer docs often combine guides, API references, examples, changelogs, and interactive surfaces. Mintlify can generate API docs from OpenAPI files (Mintlify OpenAPI setup). ReadMe exposes guides, API reference, recipes, changelogs, and developer hubs as separate surfaces (ReadMe docs).

A documentation skill should not copy a platform's style blindly. It should borrow the lesson that different surfaces have different jobs and examples need maintenance. If an endpoint example appears in a guide, API reference, SDK README, and onboarding tutorial, the skill should search for all affected copies or require a shared snippet source.

Before considering the skill output complete, check:

• Does the draft name the target reader and doc type?
• Are steps ordered the way a user would perform them?
• Are commands, examples, parameters, limits, and error cases source-backed?
• Are old examples updated or intentionally left alone with a reason?
• Are prerequisites and caveats visible before the user needs them?
• Does the draft separate shipped behavior from planned behavior?
• Are internal-only details removed from public docs?
• Are links working and authoritative?
• Does the final answer include source notes, open questions, and verification evidence?

For a related pattern, read Agent Skill for Code Review. A documentation skill and a code review skill share the same operating principle: findings and claims need evidence. The difference is the final artifact. Code review produces blockers and suggestions. Documentation work produces a reader-facing asset plus the proof that it matches reality.

An agent skill for documentation should make docs more accurate, traceable, and maintainable. It should not make the agent a more fluent guesser.

Use tools to reach repositories, issue trackers, docs platforms, screenshots, and schemas. Use scripts for deterministic checks like link validation, OpenAPI diffing, or snippet tests. Use the skill for judgment: which sources count, which doc type is being written, when to ask for help, and what evidence the reviewer needs.

That is why documentation is a high-value category for Skillfully authors. The work repeats, the output can be inspected, and small workflow improvements compound across future docs tasks.