Skip to content

JPeetz/agent-skills / skills/documentation-content/technical-documentation

technical-documentation

Verified

Use 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.

FileKindSize
CHANGELOG.mdmarkdown2.3 KB
LICENSEother1.0 KB
SKILL.mdskill md29.9 KB
evals/evals.jsonconfig5.0 KB
references/adr-template.mdmarkdown2.5 KB
references/api-docs-checklist.mdmarkdown5.6 KB
references/markdown-style-guide.mdmarkdown5.4 KB
references/runbook-template.mdmarkdown6.0 KB
scripts/validate_skill.pyexecutablescript12.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"
      ]
    }
  ]
}
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: 471kUpdated Claude CodeCodexVerifiedInstall
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: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall