technical-docs — Claude Code skill: features and installation
This skill helps write and maintain technical docs, create Mermaid diagrams, and compare documentation coverage with code. Use it for doc-as-code workflows and audits.
MIT 177 installs ★ 29 updated 2026-08-17
npx skills add oakoss/agent-skills --skill technical-docs -a claude-codeWhat technical-docs does
The skill treats documentation as part of the codebase: docs are version-controlled, linted, and checked in CI. Its guidance covers feature docs and audits that compare code changes and exported symbols with documentation. It is meant for technical docs that live alongside code, not marketing copy or blog posts.
For diagrams, it uses Mermaid syntax for sequences, ERDs, git graphs, and flowcharts. ERDs can be derived from Drizzle or Prisma schemas. The guidance also includes ADR and runbook formats, Markdown conventions, and a drafting workflow in which a person checks AI-generated text. Large diagrams should be split into subgraphs with 15–20 nodes per diagram.
For API references, the skill recommends generating documentation from JSDoc or TSDoc annotations rather than writing it by hand. Its coverage audit compares git diff main...HEAD with an export scan, so that workflow relies on Git and a main branch.
What it helps with
- find code exports missing from the docs
- draw a Mermaid sequence diagram for service calls
- derive an ERD from a Drizzle or Prisma schema
- record an architecture decision with its context and consequences
- write a runbook covering symptoms and diagnosis
Example prompts for the agent
- Compare
main...HEADwith documented exports and list the gaps. - Draw a Mermaid sequence diagram for calls between these services.
- Draft an ADR for this decision with its context, status, and consequences.
How to install technical-docs
1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill technical-docs -a claude-code2Manually: put the files in place
~/.claude/skills/technical-docs/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/technical-docs/
1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill technical-docs -a codex2Manually: put the files in place
.agents/skills/technical-docs/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill technical-docs -a cursor2Manually: put the files in place
.cursor/skills/technical-docs/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install oakoss/agent-skills skills/technical-docs2Manually: put the files in place
.github/skills/technical-docs/SKILL.md1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill technical-docs -a gemini-cli2Platform CLI
gemini skills install https://github.com/oakoss/agent-skills --path skills/technical-docsManually: put the files in place
.devin/skills/technical-docs/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill technical-docs -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about technical-docs
How do I install technical-docs in Claude Code?
Run npx skills add oakoss/agent-skills --skill technical-docs -a claude-code. The skill file is at ~/.claude/skills/technical-docs/SKILL.md.
What does the technical-docs skill do?
It provides workflows for maintaining technical docs alongside code, creating Mermaid diagrams, and auditing documentation against code changes. It also covers Markdown, ADRs, and runbooks.
How does technical-docs handle ERDs?
It describes Mermaid erDiagram diagrams using Crow’s Foot notation and suggests deriving them from Drizzle or Prisma schemas.
Source text
SKILL.md · MIT
--- name: technical-docs description: 'Technical documentation writing and diagram generation. Use when creating docs, syncing documentation with code changes, building Mermaid diagrams, running doc coverage audits, or establishing writing style guides. Use for doc-as-code workflows, ERD generation, sequence diagrams, documentation gap analysis, and AI-assisted drafting.' license: MIT metadata: author: oakoss version: '1.2' --- # Documentation Technical writing, diagram-as-code, and documentation lifecycle management. Treats docs as code: version-controlled, linted, and CI-verified. **When to use**: Creating or updating technical documentation, generating Mermaid diagrams (flowcharts, ERDs, sequence diagrams), auditing documentation coverage against code, or establishing style guides. **When NOT to use**: Writing marketing copy, blog posts, or content that does not live alongside code. ## Quick Reference | Task | Approach | Key Point | | -------------------- | ----------------------------------------------- | -------------------------------------------- | | Doc sync audit | `git diff main...HEAD` + export scan | Compare symbols against doc coverage | | Sequence diagram | Mermaid `sequenceDiagram` + `autonumber` | Map messages to function calls | | ERD | Mermaid `erDiagram` + Crow's Foot | Derive from Drizzle/Prisma schemas | | Gitgraph | Mermaid `gitGraph` | Standardize on main/develop/feature branches | | Feature release doc | Overview + Config + Examples + Troubleshooting | Checklist for every new feature | | API reference | Generate from JSDoc/TSDoc annotations | Never write API refs manually | | Style guide | Active voice + present tense + direct address | Conversational but precise | | AI-assisted drafting | Inventory + gap analysis + draft + human review | AI drafts, humans verify accuracy | | Markdown standard | YAML frontmatter + language-tagged code blocks | Always specify code block language | | Complex diagrams | Split into focused sub-diagrams + subgraphs | Limit to 15-20 nodes per diagram | | README template | Badges + description + quick start + API link | First thing users see; keep under 200 lines | | ADR format | Status, context, decision, consequences | Numbered, immutable once accepted | | Runbook | Symptoms, diagnosis, resolution, escalation | Written for 3 AM incidents; no ambiguity | ## Common Mistakes | Mistake | Correct Pattern | | ------------------------------------------- | ----------------------------------------------------------------- | | Using static images for technical diagrams | Write Mermaid syntax inline in Markdown | | Generic participant names like `Agent1` | Use specific service or role names matching the architecture | | Manually writing API reference docs | Generate from JSDoc/TSDoc annotations in source code | | Diagrams with 20+ nodes and no grouping | Use subgraphs to group related nodes; limit to 15-20 | | Documentation referencing outdated defaults | Run doc sync audit comparing exports against coverage | | Using "Click here" link text | Use descriptive anchor text for accessibility and clarity | | Skipping heading hierarchy levels | Never go from H2 to H4; keep hierarchy sequential | | Mixing wall-of-text paragraphs | Use bullet points, tables, and diagrams for scannability | | No ADRs for architectural decisions | Record decisions with context, status lifecycle, and consequences | ## Delegation - **Scan codebase for undocumented exports and documentation gaps**: Use `Explore` agent - **Generate a full documentation site with diagrams from an existing codebase**: Use `Task` agent - **Plan documentation architecture and information hierarchy for a new project**: Use `Plan` agent > If the `mermaid-diagrams` skill is available, delegate complex diagram creation and advanced Mermaid syntax questions to it. > Otherwise, recommend: `npx skills add oakoss/agent-skills --skill mermaid-diagrams` > If the `tldr-expert` skill is available, delegate summary and brief generation to it. ## References - [Writing Style](references/writing-style.md) -- Voice, tone, formatting rules, error message guidelines, and structural standards - [Mermaid Diagrams](references/mermaid-diagrams.md) -- Sequence, ERD, gitgraph, flowchart patterns with anti-patterns and troubleshooting - [Doc Coverage](references/doc-coverage.md) -- Feature inventory, gap analysis, code-first and doc-first audit workflows - [AI Collaboration](references/ai-collaboration.md) -- AI-human doc workflow, hallucination handling, documentation-as-code practices - [Markdown Standards](references/markdown-standards.md) -- Frontmatter, headings, code blocks, tables, callouts, and link conventions - [Runbooks and Onboarding](references/runbooks-and-onboarding.md) -- Incident runbook templates, escalation paths, and developer onboarding guides
© oakoss · MIT · oakoss/agent-skills