Documentation Engineer
Technical documentation: docs-as-code workflows, API documentation (OpenAPI, AsyncAPI), architecture decision records, Docusaurus/MkDocs setup, and info architecture.
A technical documentation skill that treats docs as a first-class engineering artifact. It covers docs-as-code tooling (Docusaurus, MkDocs, Mintlify), OpenAPI/AsyncAPI spec writing, ADR templates, information architecture design, and the CI pipelines that keep documentation accurate and current. Opinionated on what makes developer docs actually get used.
Added Mar 20, 2026
$npx skills add johnefemer/skillfish --skill documentation-engineer What This Skill Can Do
Concrete capabilities you get when you install this skill.
Set up docs-as-code pipelines with Docusaurus, MkDocs, or Mintlify including CI validation
Write and validate OpenAPI 3.1 and AsyncAPI specs from code or prose descriptions
Design information architecture: navigation structure, content taxonomy, and search optimization
Create and maintain Architecture Decision Records (ADRs) with context-decision-consequences format
Build automated documentation freshness checks that flag stale pages in CI
Produce developer guides that combine conceptual explanation with working code examples
Real Conversations
See how the Documentation Engineer skill responds to actual requests. These are representative examples of what your AI agent will produce.
Our REST API docs are always out of date. Developers update the code but forget the OpenAPI spec. How do we keep them in sync?
The root cause: docs live separately from code, so updates aren't a natural part of the development flow. Fix with a code-first approach where the spec is generated from code annotations, not written separately.
Option A — TypeScript/Node.js with tsoa or Zod + openapi-zod-adapter
// Define schema once in Zod
const CreateUserSchema = z.object({
email: z.string().email(),
name: z.string().min(1),
});
// Generate OpenAPI spec automatically
import { generateSchema } from '@anatine/zod-openapi';
const openApiSchema = generateSchema(CreateUserSchema);
Option B — Python with FastAPI (spec is always current)
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class CreateUser(BaseModel):
email: str
name: str
@app.post("/users", response_model=User)
def create_user(body: CreateUser): ...
# /docs and /openapi.json auto-generated, always accurate
CI validation for any approach:
# .github/workflows/docs.yml
- name: Validate OpenAPI spec
run: npx @redocly/cli lint openapi.yaml
- name: Check spec is up to date
run: |
npm run generate:openapi
git diff --exit-code openapi.yaml || (echo 'OpenAPI spec is stale — run npm run generate:openapi' && exit 1)
The CI check fails if anyone merges a code change without updating the spec. Takes 2 minutes to set up; prevents months of drift.
Get Started
How to install and use this skill in your preferred environment.
Skills are designed for AI coding agents (Claude Code, Cursor, Windsurf) and IDE-based workflows where the agent can read files, run scripts, and act on your codebase.
Models & Context
Which AI models and context windows work best with this skill.
Recommended Models
Works well with Claude Sonnet or GPT-4o. Documentation writing benefits from models with strong prose quality; OpenAPI spec generation is reliable across frontier models.
Context Window
SKILL.md is ~8KB. Load existing docs structure, sample pages, and OpenAPI spec in context for information architecture and spec review sessions.
Pro tips for best results
Be specific
Include numbers — users, budget, RPS — so the skill can size the architecture.
Share constraints
Compliance needs, team size, and existing stack all improve the output.
Iterate
Start with a high-level design, then ask follow-ups for IaC, cost analysis, or security review.
Combine skills
Pair with companion skills below for end-to-end coverage.
Works Great With
These skills complement Documentation Engineer for end-to-end coverage. Install them together for better results.
Ready to try Documentation Engineer?
Install the skill and start getting expert-level guidance in your workflow — any agent, any IDE.
$npx skills add johnefemer/skillfish --skill documentation-engineer