JPeetz/agent-skills / skills/documentation-content/technical-documentation
technical-documentation
VerifiedUse this skill when creating, maintaining, or auditing technical documentation — READMEs, ADRs, API docs, runbooks, onboarding guides, changelogs, knowledge bases, and AI agent context files (AGENTS.md/CLAUDE.md). Covers documentation- driven development, OpenAPI generation, markdown best practices, and completeness/accuracy audits. For all major agentic platforms.
| File | Kind | Size |
|---|---|---|
| CHANGELOG.md | markdown | 2.3 KB |
| LICENSE | other | 1.0 KB |
| SKILL.md | skill md | 29.9 KB |
| evals/evals.json | config | 5.0 KB |
| references/adr-template.md | markdown | 2.5 KB |
| references/api-docs-checklist.md | markdown | 5.6 KB |
| references/markdown-style-guide.md | markdown | 5.4 KB |
| references/runbook-template.md | markdown | 6.0 KB |
| scripts/validate_skill.pyexecutable | script | 12.3 KB |
evals/evals.json
View on GitHub{
"skill": "technical-documentation",
"version": "1.0.0",
"cases": [
{
"id": "pos-01",
"description": "README generation for new project",
"input": "I just created a new Python microservice for user authentication using FastAPI and PostgreSQL. Can you write a README for it?",
"shouldTrigger": true,
"expect": "Standard README generation request. The agent should infer the stack (FastAPI, PostgreSQL) from the user's description and produce a structured README following the template in the skill body.",
"assertions": [
"Quick Start",
"Installation",
"Usage",
"License"
]
},
{
"id": "pos-02",
"description": "ADR generation for architectural decision",
"input": "We decided to use Redis for our session store instead of storing sessions in PostgreSQL. Can you write an ADR for this decision?",
"shouldTrigger": true,
"expect": "ADR generation request. The agent should use the ADR template from references/adr-template.md, compare Redis vs PostgreSQL for session storage, and produce a complete ADR with all sections.",
"assertions": [
"Status",
"Context and Problem Statement",
"Decision Drivers",
"Considered Options",
"Decision Outcome",
"Positive Consequences",
"Negative Consequences"
]
},
{
"id": "pos-03",
"description": "API documentation generation",
"input": "Document our REST API for the orders service. We have endpoints for creating orders, listing orders, getting order details, and cancelling orders. Authentication uses Bearer JWT tokens.",
"shouldTrigger": true,
"expect": "API documentation request. The agent should produce structured API documentation covering all mentioned endpoints with authentication details, error codes, and examples.",
"assertions": [
"endpoint",
"authentication",
"error",
"request",
"response"
]
},
{
"id": "pos-04",
"description": "Documentation audit request",
"input": "Audit our documentation. We have a README, some ADRs in docs/adr/, and API docs generated from our OpenAPI spec. I'm worried things might be stale.",
"shouldTrigger": true,
"expect": "Documentation audit request. The agent should assess existing docs against the three audit dimensions, identify gaps and staleness, and produce a structured audit report.",
"assertions": [
"completeness",
"accuracy",
"freshness",
"finding",
"recommendation"
]
},
{
"id": "pos-05",
"description": "AI agent context file generation",
"input": "We're adopting AI coding agents on our team. Can you write an AGENTS.md for our project? It's a Go microservices platform with gRPC for service-to-service communication, PostgreSQL for persistence, and Kubernetes for deployment. We use conventional commits and require test coverage above 80%.",
"shouldTrigger": true,
"expect": "AGENTS.md generation request. The agent should produce a structured agent context file following the template in the skill body, including project identity, architecture description, coding conventions, and constraints.",
"assertions": [
"Project Identity",
"Architecture",
"Conventions",
"Constraints"
]
},
{
"id": "neg-01",
"description": "Code comments / docstrings request (not documentation)",
"input": "Add docstrings and type hints to every function in my auth.py module.",
"shouldTrigger": false,
"expect": "User is asking for code-level docstrings and type annotations, not standalone documentation. The 'doc' in 'docstrings' is incidental \u2014 this is a code generation/completion task.",
"assertions": [
"Code editing with docstring and type hint additions"
]
},
{
"id": "neg-02",
"description": "Blog post writing request (not technical docs)",
"input": "Write a blog post about how we migrated from a monolith to microservices \u2014 it should be engaging and highlight the business benefits.",
"shouldTrigger": false,
"expect": "User is asking for a marketing/thought-leadership blog post, not technical reference documentation. Blog posts are narrative-driven and persuasive; technical docs are factual and instructional.",
"assertions": [
"Blog post or article writing"
]
},
{
"id": "neg-03",
"description": "Code review request (not documentation)",
"input": "Review my PR \u2014 I added a new payment processing module. Can you check the code for security issues and suggest improvements?",
"shouldTrigger": false,
"expect": "User is asking for a code review (security, quality assessment of code), not documentation. The word 'review' triggers code-review, not technical-documentation.",
"assertions": [
"Structured code review with security analysis"
]
}
]
}
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |