Diataxis Docs Writer
calf-ai/calfkit-sdk
Write or improve software documentation using the Diátaxis framework — four documentation types (tutorials, how-to guides, reference, explanation), each serving a different user need.
Use as the final documentation gate before a pydantic-ai-harness capability PR merges.
Install Docs Parity Reviewer
$ npx skills add pydantic/pydantic-ai --skill docs-parity-reviewer -a claude-codeProject install by default; add -g for ~/.claude/skills/.
$ gh skill install pydantic/pydantic-ai docs-parity-reviewer --agent claude-codeProject scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).
$ git clone --depth 1 https://github.com/pydantic/pydantic-ai.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.agents/skills/docs-parity-reviewer .claude/skills/docs-parity-reviewer && rm -rf skills-srcUse ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.
Claude Code skills documentation · loads skills from .claude/skills/
Install the "docs-parity-reviewer" agent skill from https://github.com/pydantic/pydantic-ai/tree/main/.agents/skills/docs-parity-reviewer into .claude/skills/docs-parity-reviewer/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "docs-parity-reviewer", then confirm the skill loads.Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$skill-installer install https://github.com/pydantic/pydantic-ai/tree/main/.agents/skills/docs-parity-reviewerType this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.
$ npx skills add pydantic/pydantic-ai --skill docs-parity-reviewer -a codexProject install goes to .agents/skills/; add -g for ~/.codex/skills/.
$ gh skill install pydantic/pydantic-ai docs-parity-reviewer --agent codexProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/pydantic/pydantic-ai.git skills-src && mkdir -p .agents/skills && cp -r skills-src/.agents/skills/docs-parity-reviewer .agents/skills/docs-parity-reviewer && rm -rf skills-srcUse ~/.agents/skills/ instead of .agents/skills for a personal install.
Codex skills documentation · loads skills from .agents/skills/
Install the "docs-parity-reviewer" agent skill from https://github.com/pydantic/pydantic-ai/tree/main/.agents/skills/docs-parity-reviewer into .agents/skills/docs-parity-reviewer/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "docs-parity-reviewer", then confirm the skill loads.Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add pydantic/pydantic-ai --skill docs-parity-reviewer -a cursorProject install goes to .agents/skills/; add -g for ~/.cursor/skills/.
$ gh skill install pydantic/pydantic-ai docs-parity-reviewer --agent cursorProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/pydantic/pydantic-ai.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/.agents/skills/docs-parity-reviewer .cursor/skills/docs-parity-reviewer && rm -rf skills-srcUse ~/.cursor/skills/ instead of .cursor/skills for a personal install.
Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/
Install the "docs-parity-reviewer" agent skill from https://github.com/pydantic/pydantic-ai/tree/main/.agents/skills/docs-parity-reviewer into .cursor/skills/docs-parity-reviewer/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "docs-parity-reviewer", then confirm the skill loads.Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gemini skills install https://github.com/pydantic/pydantic-ai.git --path .agents/skills/docs-parity-reviewer--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.
$ npx skills add pydantic/pydantic-ai --skill docs-parity-reviewer -a gemini-cliProject install goes to .agents/skills/; add -g for ~/.gemini/skills/.
$ gh skill install pydantic/pydantic-ai docs-parity-reviewer --agent gemini-cliProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/pydantic/pydantic-ai.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/.agents/skills/docs-parity-reviewer .gemini/skills/docs-parity-reviewer && rm -rf skills-srcUse ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.
Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/
Install the "docs-parity-reviewer" agent skill from https://github.com/pydantic/pydantic-ai/tree/main/.agents/skills/docs-parity-reviewer into .gemini/skills/docs-parity-reviewer/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "docs-parity-reviewer", then confirm the skill loads.Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gh skill install pydantic/pydantic-ai docs-parity-reviewerInstalls for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).
$ npx skills add pydantic/pydantic-ai --skill docs-parity-reviewer -a github-copilotProject install goes to .agents/skills/; add -g for ~/.copilot/skills/.
$ git clone --depth 1 https://github.com/pydantic/pydantic-ai.git skills-src && mkdir -p .github/skills && cp -r skills-src/.agents/skills/docs-parity-reviewer .github/skills/docs-parity-reviewer && rm -rf skills-srcUse ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.
GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/
Install the "docs-parity-reviewer" agent skill from https://github.com/pydantic/pydantic-ai/tree/main/.agents/skills/docs-parity-reviewer into .github/skills/docs-parity-reviewer/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "docs-parity-reviewer", then confirm the skill loads.GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add pydantic/pydantic-ai --skill docs-parity-reviewer -a opencodeOpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.
$ gh skill install pydantic/pydantic-ai docs-parity-reviewer --agent opencodeProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/pydantic/pydantic-ai.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/.agents/skills/docs-parity-reviewer .opencode/skills/docs-parity-reviewer && rm -rf skills-srcUse ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.
OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/
Install the "docs-parity-reviewer" agent skill from https://github.com/pydantic/pydantic-ai/tree/main/.agents/skills/docs-parity-reviewer into .opencode/skills/docs-parity-reviewer/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "docs-parity-reviewer", then confirm the skill loads.OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
Facts
- Skill name
docs-parity-reviewer- GitHub stars
- 21k
- Token cost
- ~1.4k tokens
- SKILL.md length
- 658 words
- Files
- 1
- Skills in repo
- 20
- Repo updated
- First seen
- Licence
- MIT
At a glance
Use as the final documentation gate before a pydantic-ai-harness capability PR merges.
- Works in 10 steps: Both docs updated. If the change alters… → Snippets parse and run. Run uv run… → README <-> unified doc consistency. The… → …
- Tasks that involve Technical documentation
- SKILL.md covers What you are given, Checks and Output
- Calls uv; reaches pydantic.dev
What it does
Docs Parity Reviewer is an agent skill from pydantic/pydantic-ai, published by the product's own GitHub organization. Use as the final documentation gate before a pydantic-ai-harness capability PR merges. Verifies that a user-facing change keeps the capability README under src/pydanticaiharness/pydanticaiharness/ and its docs/harness/ page in sync with each other and with the code, that every snippet is runnable, and that links follow repo convention. Reports gaps; does not edit. Skip it for changes that touch no harness capability or its docs.
Its SKILL.md is about 1.4k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.
It sits in Development, covering Technical documentation. It works with Pydantic AI. The repository describes itself as: How Python does AI. Agents, realtime voice, image generation, embeddings. Every model, every interface, typed end to end. The licence is MIT.
When your agent uses it
- Tasks that involve Technical documentation
Example prompts
- “/docs-parity-reviewer”
Workflow steps
10 steps, taken from the first numbered list in SKILL.md.
- Both docs updated. If the change alters user-facing behavior (public
- Snippets parse and run. Run uv run pytest tests/harness/test_doc_snippets.py;
- README <-> unified doc consistency. The two agree on install extras,
- Links. Unified doc: harness-internal links are relative .md
- Source link + API block. Every page links its source module
- Safety caveats preserved. Where the source carries access, sandbox, or
- Writing style. Both follow src/pydantic_ai_harness/AGENTS.md "Writing style": no em-dashes (use
- Purpose-first lead. The opening paragraph of both docs states what the
- Name matches the capability. The doc filename, its # H1, and the
- Stability framing. Graduated capabilities carry the soft "The API may
What it can do on your machine
Read from SKILL.md and the folder at commit 4c6fc3c. It shows what the files ask for, not the result of running them.
Tool permissions
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
Runs code
Shell commands in SKILL.md call:
uv
From the folder's file list and the shell code blocks in SKILL.md.
Network
Hosts in commands or code, which the agent is likely to contact:
pydantic.dev
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.
Context cost
Docs Parity Reviewer loads about 1.4k tokens when it runs. Until then it costs about 116 tokens; SKILL.md has 658 words of instructions outside code blocks.
Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.
Safety
Auto-check passed
The automated check found no risky patterns in SKILL.md.
Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.
SKILL.md
The full file from pydantic/pydantic-ai at commit 4c6fc3c, republished under its MIT licence (© pydantic). 658 words, ~1,376 tokens.
Download SKILL.mdSave it as
.claude/skills/docs-parity-reviewer/SKILL.md (or your agent's skills folder).- name
- docs-parity-reviewer
- description
- Use as the final documentation gate before a `pydantic-ai-harness` capability PR merges. Verifies that a user-facing change keeps the capability README under `src/pydantic_ai_harness/pydantic_ai_harness/` and its `docs/harness/` page in sync with each other and with the code, that every snippet is runnable, and that links follow repo convention. Reports gaps; does not edit. Skip it for changes that touch no harness capability or its docs.
- context
- fork
- model
- sonnet
- disallowed-tools
- Edit, Write, NotebookEdit
You are the documentation parity gate for pydantic-ai-harness. Every released
capability ships two docs that must stay in sync with the code and with each
other:
- README --
src/pydantic_ai_harness/pydantic_ai_harness/<capability>/README.md(orsrc/pydantic_ai_harness/pydantic_ai_harness/experimental/acp/README.mdfor ACP). Serves GitHub and PyPI. Keeps absolute links and its badges. - Unified doc -- flat at
docs/harness/<capability>.md. Renders on the docs site (https://pydantic.dev/docs/ai/harness/). No badges; links its source module and, where the capability exposes a public class, may end with::: pydantic_ai_harness.<Class>autodoc blocks. Thedocs/harness/folder is flat -- nocapabilities/orexperimental/subdirectories.
Both are hand-maintained. A change to one that is not reflected in the other is the failure mode you exist to catch.
What you are given
The diff or description of a capability change (the touched capability, and what
its user-facing behavior now is). If you are not told which capability changed,
infer it from the files the current branch changes under
src/pydantic_ai_harness/pydantic_ai_harness/ and docs/harness/.
Checks
Read the capability source, its README, and its unified doc, then report each problem as a finding (blocking / warning / nit) with a concrete fix.
- Both docs updated. If the change alters user-facing behavior (public class, constructor params, defaults, tool names, extras, safety semantics) and only one of README / unified doc reflects it, that is blocking. A doc describing behavior the code no longer has is also blocking.
- Snippets parse and run. Run
uv run pytest tests/harness/test_doc_snippets.py; this checks parsing and harness imports only. Execute every changed deterministic snippet unchanged. For snippets that need credentials or a live service, verify the complete runnable wrapper and require a fake-backed test for its control flow. Every block has all imports and capability wiring. Class names, params, and defaults match the source. Model ids are unchanged -- a changed model id is blocking. Illustrative signature pseudo-code uses{test="skip"}. - README <-> unified doc consistency. The two agree on install extras, option names, defaults, and safety caveats. They need not be identical prose, but they must not contradict each other or the code.
- Links. Unified doc: harness-internal links are relative
.md([Shell](shell.md)); other Pydantic AI pages are relative.mdlinks fromdocs/harness/([Toolsets](../toolsets.md)), and API elements use reference-style links ([RunContext][pydantic_ai.tools.RunContext]). No root-relative/ai/...paths or legacyai.pydantic.devlinks, no leftover../../README.md, and no badge markup. README: absolute links are fine. - Source link + API block. Every page links its source module
(
https://github.com/pydantic/pydantic-ai/tree/main/src/pydantic_ai_harness/pydantic_ai_harness/<module>/) so a reading agent can verify behavior -- a missing source link is a finding. Where the capability exposes a public class, the page may also end with a## API referencesection of::: pydantic_ai_harness...autodoc blocks (auto-expanded from the docstring, not hand-written). If a class docstring is too thin to render a useful API section, flag it -- the fix is a richer docstring, not a hand-written table. - Safety caveats preserved. Where the source carries access, sandbox, or command-control limits (Shell, CodeMode, FileSystem), both docs state them.
- Writing style. Both follow
src/pydantic_ai_harness/AGENTS.md"Writing style": no em-dashes (use--), no hype, plain ASCII punctuation. - Purpose-first lead. The opening paragraph of both docs states what the
capability is for and when to use it. An internal hook or class name
(
before_model_request,after_tool_execute, ...) in the first paragraph, ahead of the purpose, is a finding -- move the mechanism lower. - Name matches the capability. The doc filename, its
# H1, and the README# H1all use the capability's descriptive name (e.g. "Overflowing Tool Output", not "Overflow"). A short or ClassName-style heading is a finding. - Stability framing. Graduated capabilities carry the soft "The API may
change between releases..." note mirrored from the README, not a
HarnessExperimentalWarningblock or "removed in any release" wording. ACP is the only page that keeps an!!! warning "Experimental".
Show full SKILL.md (53 more words)Show less
If a released capability has a README but no docs/harness/ page (or vice versa), that
missing file is a blocking finding.
Output
A terse list of findings, most severe first, each naming the file, the severity, and the fix. If everything is in order, say so in one line. Do not edit files.
© pydantic, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file
Files
Just SKILL.md in .agents/skills/docs-parity-reviewer of pydantic/pydantic-ai.
Open the folder on GitHubat commit 4c6fc3c
Compare with similar skills
Docs Parity Reviewer next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.
| Skill | Stars | Used in | Tokens | Auto-check | Licence | Repo updated |
|---|---|---|---|---|---|---|
| Docs Parity Reviewer this skillpydantic/pydantic-ai | 21k | — | ~1.4k | Automated safety check: Pass | MIT | |
| Diataxis Docs Writercalf-ai/calfkit-sdk | 149 | 1 repos | ~3k | Automated safety check: Pass | Apache-2.0 | |
| Generate Readmedivar-ir/ai-doc-gen | 767 | — | ~996 | Automated safety check: Pass | MIT | |
| Diagram Designcathrynlavery/diagram-design | 48k | 1 repos | ~7.6k | Automated safety check: Pass | MIT | |
| Simple Englishmoeru-ai/airi | 50k | 2 repos | ~4.6k | Automated safety check: Pass | MIT | |
| Doc SyncJetBrains/ideavim | 10k | 2 repos | ~2.6k | Automated safety check: Pass | MIT |
Similar skills
Generate Readme
divar-ir/ai-doc-gen
Generate or refresh a comprehensive, professional README.md for a repository, with architecture overview, mermaid and optional C4 diagrams, repository structure, dependencies, and API documentation.
Diagram Design
cathrynlavery/diagram-design
Creates branded diagrams, from architecture, flowchart and sequence to charts and maps, as self-contained HTML with inline SVG, with import from draw.io, Mermaid and Excalidraw.
Simple English
moeru-ai/airi
Write or rewrite technical text with the rules of ASD-STE100 Simplified Technical English so it is clear, unambiguous, and free of AI slop.
- Official
Doc Sync
JetBrains/ideavim
Keeps IdeaVim documentation in sync with code changes. An agent skill from JetBrains/ideavim.
Mailspring App Screenshots
Foundry376/Mailspring
Captures screenshots of the running Mailspring dev app for docs, PRs or visual checks by launching it with a debugging port, driving the UI and clipping to an element.
More from pydantic/pydantic-ai
All 20 skills in this repo- Official
Pydantic AI Harness
pydantic/pydantic-ai
Adds optional capabilities to Pydantic AI agents from pydantic-ai-harness, led by Code Mode, which runs many tool calls as one sandboxed Python script.
- Official
Building Pydantic AI Agents
pydantic/pydantic-ai
Build AI agents with Pydantic AI — tools, capabilities (including on-demand loading), workspaces, structured output, streaming, testing, and multi-agent patterns.
- Official
Complete Partial PR
pydantic/pydantic-ai
Evaluate and complete an issue or PR where the submitted patch fixes only a narrow symptom of the reported pain point.
- Official
Testing Skill
pydantic/pydantic-ai
Record, rewrite, and debug VCR cassettes for HTTP recordings.
- Official
Migrating Agno To Pydantic AI
pydantic/pydantic-ai
Migrate Python Agno applications to Pydantic AI and, only when needed, Pydantic AI Harness.
- Official
Migrating Claude Agent SDK To Pydantic AI
pydantic/pydantic-ai
Migrate Python applications from the Claude Agent SDK to Pydantic AI and, only when needed, Pydantic AI Harness.
Related
Works with
Categories
Questions about Docs Parity Reviewer
What does Docs Parity Reviewer do?
Use as the final documentation gate before a pydantic-ai-harness capability PR merges. Docs Parity Reviewer is an agent skill from pydantic/pydantic-ai, published by the product's own GitHub organization. Use as the final documentation gate before a pydantic-ai-harness capability PR merges.
When should I use Docs Parity Reviewer?
Docs Parity Reviewer fits situations like: tasks that involve Technical documentation.
How do I install Docs Parity Reviewer in Claude Code?
Run `npx skills add pydantic/pydantic-ai --skill docs-parity-reviewer -a claude-code`. Or copy the skill folder (.agents/skills/docs-parity-reviewer in pydantic/pydantic-ai) into .claude/skills/docs-parity-reviewer in your project. Claude Code loads it when a task matches its description.
How do I install Docs Parity Reviewer in Codex?
Run `npx skills add pydantic/pydantic-ai --skill docs-parity-reviewer -a codex`. Or copy the skill folder (.agents/skills/docs-parity-reviewer in pydantic/pydantic-ai) into .agents/skills/docs-parity-reviewer in your project. Codex loads it when a task matches its description.
Can I use Docs Parity Reviewer in Cursor, Gemini CLI or GitHub Copilot?
Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add pydantic/pydantic-ai --skill docs-parity-reviewer -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/docs-parity-reviewer, .gemini/skills/docs-parity-reviewer, .github/skills/docs-parity-reviewer and .opencode/skills/docs-parity-reviewer in your project.
What does Docs Parity Reviewer need to run?
Going by SKILL.md and its folder, Docs Parity Reviewer needs the command-line tools its instructions call (uv).
Does Docs Parity Reviewer access the network?
SKILL.md names 1 domain. In commands or code: pydantic.dev; the agent is likely to contact it when it follows the instructions. This is read from the text; nothing was executed.
Is Docs Parity Reviewer safe to install?
Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.
What licence does Docs Parity Reviewer use?
Docs Parity Reviewer is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.
How many tokens does Docs Parity Reviewer use?
About 1.4k tokens (SKILL.md is roughly 5.5k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.
What are the alternatives to Docs Parity Reviewer?
Skills that share tags, products or a category with Docs Parity Reviewer: Diataxis Docs Writer (calf-ai/calfkit-sdk, 149 stars), Generate Readme (divar-ir/ai-doc-gen, 767 stars), Diagram Design (cathrynlavery/diagram-design, 48k stars) and Simple English (moeru-ai/airi, 50k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.
Who maintains Docs Parity Reviewer?
pydantic (a GitHub organization, an official publisher) maintains it in pydantic/pydantic-ai, which has 20,521 GitHub stars. The repository holds 20 skills in this directory. The repository was last updated on October 10, 2026.
Source: pydantic/pydantic-ai on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.