Documentation Quality
- 19 installs
- 7 repo stars
- Updated August 2, 2026
- practicalswan/agent-skills
documentation-quality is a Claude Code skill for documentation.
About
documentation-quality is a Claude Code skill for documentation. It helps solo builders move faster with AI-assisted development.
- documentation-quality
- Documentation
- AI-coding skill
Documentation Quality by the numbers
- 19 all-time installs (skills.sh)
- +1 installs in the week ending Aug 4, 2026 (Skillselion tracking)
- Ranked #1,011 of 1,879 Documentation skills by installs in the Skillselion catalog
- Data as of Aug 4, 2026 (Skillselion catalog sync)
npx skills add https://github.com/practicalswan/agent-skills --skill documentation-qualityAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 19 |
|---|---|
| repo stars | ★ 7 |
| Last updated | August 2, 2026 |
| Repository | practicalswan/agent-skills ↗ |
How do I helps with documentation tasks.?
Helps with documentation tasks.
Who is it for?
Best when you're working on documentation and need structured help with documentation quality.
Skip if: Teams with no documentation needs, or anyone wanting a generic chat assistant without this specific workflow.
When should I use this skill?
When you need to helps with documentation tasks., or when documentation-quality is a claude code skill for documentation.
What you get
Structured output aligned to documentation-quality: documentation-quality, Documentation.
Files
Documentation Quality Standards
Use this skill when documentation should be judged against explicit standards instead of subjective preference.
- Leverage native parallel subagent dispatch and 200k+ context windows where available.
Activation Conditions
Use symptom -> action triggers: when one matches, apply this skill and verify with the protocol below.
- Reviewing docs before merge
- Creating or updating a style guide
- Defining expectations for examples, structure, and terminology
- Auditing a docs set for consistency and readability
Core Standards
- Clear audience and scope
- Stable heading hierarchy
- Runnable or honest examples
- Consistent terminology
- Explicit edge cases, constraints, and failure modes
Documentation Stack Reference
Inherit the shared stack from documentation-patterns: source-of-truth discovery, audience framing, structure selection, verification, and freshness checks. Keep this skill focused on quality gates instead of restating the full stack.
Anti-Patterns
- Writing for the author instead of the reader: It bakes in unstated context and leaves the actual audience unsure what to do next.
- Skipping concrete examples or commands: Abstract guidance is easy to approve and hard to apply correctly.
- Letting links, screenshots, or versions drift: Polished formatting does not help if the instructions are no longer true.
Verification Protocol
Before claiming "skill applied successfully":
1. Pass/fail: The Documentation Quality output identifies audience, purpose, source of truth, and freshness requirements. 2. Pass/fail: Shared documentation-stack guidance is referenced instead of duplicating another documentation skill. 3. Pass/fail: Claims, links, commands, examples, and screenshots are verified or explicitly marked unverified. 4. Pressure-test scenario: Apply the skill to a doc request with a stale command, missing owner, and conflicting audience. 5. Success metric: Zero undocumented assumptions; every reader-facing claim is sourced or scoped.
Quality Checklist
- [ ] Title and purpose are clear
- [ ] Heading levels do not jump unexpectedly
- [ ] Code examples have language tags and realistic inputs
- [ ] Commands match current tooling
- [ ] Links and file paths are accurate
Cross-Skill Workflow
- Use documentation-authoring when the content itself still needs to be drafted or clarified.
- Use documentation-patterns when the review shows that the problem is document shape rather than wording.
- Use this skill as the final standards check before publish or merge.
Agent Prompt Template
Use the documentation-quality skill to review this document against explicit standards.
Artifact: [file or pasted draft].
Audience: [who will read it].
Check for clarity, completeness, accurate examples, terminology consistency, and stale references.
Report concrete findings first, then suggest the smallest high-value fixes.References & Resources
Documentation
- Writing Standards - Clarity, example quality, terminology, and formatting guidance
Scripts
- Doc Style Audit - Check Markdown files for heading jumps, long lines, tabs, and trailing whitespace
<!-- PORTABILITY:START -->
Cross-Client Portability
This skill is written to stay usable across GitHub Copilot, Claude Code, Codex, and Gemini CLI.
- GitHub Copilot: keep the folder in a Copilot-visible skill or plugin path, or wrap the workflow as project instructions if the host does not support portable skill folders directly.
- Claude Code: keep the folder in a local skills directory or a compatible plugin or marketplace source.
- Codex: install or sync the folder into
$CODEX_HOME/skills/<skill-name>and restart Codex after major changes. - Gemini CLI: this repository generates a project command named
/skills:documentation-qualityfrom this skill. Rebuild commands withpython scripts/export-gemini-skill.py documentation-qualityand then run/commands reloadinside Gemini CLI.
<!-- PORTABILITY:END -->
<!-- MCP:START -->
MCP Availability And Fallback
Preferred MCP Server: None required
- Fallback prompt: "Use the Documentation Quality Standards skill without MCP. Rely on the local
SKILL.md, bundled references or scripts, and manual verification. Show the exact commands, evidence, and final checks you used before concluding." - If the current host does not expose a matching server, use the bundled references, scripts, native toolchain, and manual workflow already described in this skill.
- Treat direct local verification, rendered output, logs, tests, or screenshots as the fallback evidence path before completion.
<!-- MCP:END -->
Related Skills
- documentation-authoring: Use it when the workflow also needs drafting structured technical or product documents.
- documentation-patterns: Use it when the workflow also needs reusable documentation structures and templates.
- documentation-verification: Use it when the workflow also needs final documentation validation before publishing.
- notion-docs: Use it when the workflow also needs Notion page and database publishing workflows.
Changelog
[2026-04-25] - Version 1.2 Verification Protocol Refresh
Added
- Added a
Verification Protocolsection with skill-specific pass/fail checks, one pressure-test scenario, and a measurable success metric. - Added guidance to leverage native parallel subagent dispatch and 200k+ context windows where available.
- Added or referenced the shared documentation-stack approach to reduce duplicated documentation guidance.
Changed
- Updated
SKILL.mdfrontmatter toversion: "1.2"andlast_updated: 2026-04-25. - Reframed activation guidance toward symptom -> action triggers and standardized two-stage review wording where applicable.
[2026-04-24] - Version 1.1 Refresh
Changed
- Updated the SKILL frontmatter version to
1.1for the 2026-04-24 catalog refresh.
All notable changes to this skill will be documented in this file.
[2026-04-24] - Skill Refresh
Changed
- Standardized the SKILL frontmatter with version metadata, last-updated date, tags, and a concise catalog description.
- Reformatted the portability and MCP guidance with a preferred server line, a copy-paste fallback prompt, and consistent bullet lists.
- Added a catalog-standard Anti-Patterns section and refreshed the Related Skills links at the end of the skill.
- Added stronger cross-references to documentation-authoring and documentation-patterns, plus a ready-to-copy agent prompt template.
[2026-04-04] - Cross-Client Portability Refresh
Changed
- Added a standard portability note covering GitHub Copilot, Claude Code, Codex, and Gemini CLI.
- Clarified that the core workflow does not require a dedicated MCP server and can run with local tools alone.
Tested
- Validated
SKILL.mdfrontmatter, portability sections, and Gemini export readiness withpython scripts/validate-skills.py.
[2026-03-09] - Workspace Modernization
Changed
- Reworked the skill around explicit documentation-quality standards and review criteria
Added
scripts/doc-style-audit.pyfor lightweight Markdown quality checks
[2026-02-28] — Description Rewrite & Cross-References
Changed
- Rewrote skill description to ~200 characters with clear, specific activation keywords
- Improved keyword specificity to reduce overlap with related skills
Added
## Related Skillscross-reference table with 2-4 related skills and "Use When" guidance
MIT License
Copyright (c) 2026 Sithu Win San
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
Documentation Writing Standards
Language Principles
- Concise: Use the fewest words necessary to convey meaning
- Clear: Avoid ambiguity and jargon unless defined
- Active Voice: Prefer active over passive voice (e.g., "The function validates" not "Validation is performed by the function")
- Present Tense: Describe functionality in present tense
- Beginner-Friendly: Explain concepts that may be unfamiliar to new users
Formatting Standards
- Use consistent heading hierarchy (H1 → H2 → H3)
- Include code fences with language specification: \
\\javascript \\\ - Use inline code for function names, variables, and file paths with backticks
- Define list items with proper indentation
Code Best Practices
- Include imports and setup code
- Ensure examples are complete and runnable
- Document expected output clearly
- Use meaningful variable names
- Add comments for non-obvious logic
Common Pitfalls
- ❌ Using vague descriptions ("does something useful")
- ❌ Outdated code examples
- ❌ Missing critical steps
- ❌ Using undocumented assumptions about user knowledge
- ❌ Failing to document error scenarios
#!/usr/bin/env python3
"""Audit Markdown files for a few high-signal style issues."""
from __future__ import annotations
import argparse
import re
from pathlib import Path
HEADING_RE = re.compile(r"^(#+)\s+")
FENCE_RE = re.compile(r"^\s*(```|~~~)")
SKIP_DIRS = {".git", ".gemini", ".serena"}
def is_table_row(line: str) -> bool:
stripped = line.strip()
return stripped.startswith("|") and stripped.endswith("|")
def audit(path: Path) -> list[str]:
findings: list[str] = []
previous_level = 0
in_code_fence = False
for index, line in enumerate(path.read_text(encoding="utf-8", errors="replace").splitlines(), start=1):
if FENCE_RE.match(line):
in_code_fence = not in_code_fence
if "\t" in line:
findings.append(f"{path}:{index}: contains tab characters")
if line.rstrip() != line:
findings.append(f"{path}:{index}: trailing whitespace")
if not in_code_fence and not is_table_row(line) and len(line) > 140:
findings.append(f"{path}:{index}: line exceeds 140 characters")
if in_code_fence:
continue
match = HEADING_RE.match(line)
if match:
level = len(match.group(1))
if previous_level and level > previous_level + 1:
findings.append(f"{path}:{index}: heading jumps from H{previous_level} to H{level}")
previous_level = level
return findings
def main() -> int:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("paths", nargs="+", help="Markdown files or directories")
args = parser.parse_args()
findings: list[str] = []
for raw in args.paths:
path = Path(raw)
files = [path] if path.is_file() else sorted(
file_path
for file_path in path.rglob("*.md")
if not any(part in SKIP_DIRS for part in file_path.parts)
)
for file_path in files:
findings.extend(audit(file_path))
if findings:
print("\n".join(findings))
return 1
print("No style issues found by the lightweight audit.")
return 0
if __name__ == "__main__":
raise SystemExit(main())
Related skills
Lark MarkdownInstantly turn any markdown file into clean, formatted Lark/Figma-compatible documents without manual reformatting.488k
Lark DocCreate, read, update, summarize, rewrite and manage Feishu/Lark cloud documents directly from agent workflows.401k16.1kLark WikiCreate, organize, query, and manage documents, spaces, and members inside Lark (Feishu) knowledge bases directly from AI agent workflows.397k16.1k
Domain ModelingBuild and sharpen a project's domain model: pin down domain terminology in a glossary and record architectural decisions as ADRs.318k202k
Opensource Guide CoachGet expert, attribution-safe guidance on launching and sustaining an open-source project.270k71Readme I18nMaintain consistent, updatable language selector blocks across every README variant in a multilingual repository.270k71FAQ
What does documentation-quality do?
documentation-quality is a Claude Code skill for documentation.
When should I use documentation-quality?
When you need to helps with documentation tasks., or when documentation-quality is a claude code skill for documentation.
What are the main capabilities?
documentation-quality; Documentation; AI-coding skill.
Documentationdocs