Generate Documentation

Documentation is the first thing clients ask for and the last thing engineers write. In outsourcing, this gap is especially costly: handoffs stall, new team members spend days reverse-engineering code instead of delivering features, and clients are left with systems they cannot operate independently. Sun Agent Kit generates production-quality documentation directly from your codebase — API references, architecture guides, README files, and structured client handoff packages — so your delivery is complete, not just functional.

Overview

Goal: Generate complete, accurate, and maintainable documentation from source code for client delivery, team rotation, or compliance
Time: 10–30 minutes (vs 2–4 hours of manual writing)
Agents used: doc-writer, scout, reviewer
Commands: /sk:docs init, /sk:docs update, /sk:docs summarize

Prerequisites

• Sun Agent Kit installed and authenticated (installation guide)
• Source code committed to git (the agent reads the repository, not just open files)
• For API docs: routes or controller files with consistent patterns (Express, FastAPI, Laravel, Spring Boot all supported)
• For architecture docs: a codebase with at least one identifiable layer (controllers, services, repositories, or equivalent)
• Optional: existing partial docs in /docs that the agent can extend rather than replace

Step-by-Step Workflow

Step 1: Generate initial documentation for a project

The first run scans the entire codebase and creates a comprehensive documentation set.

/sk:docs init

What happens: The agent:

1. Scans the project structure to detect framework, database, auth method, and deployment config
2. Extracts configuration surface — environment variables, npm scripts, Docker setup
3. Reads existing partial documentation and preserves it
4. Writes README, API overview, setup guide, and architecture summary to the docs/ directory

Step 2: Generate API reference documentation

Point the agent at your routes or controllers and it produces an API reference — endpoints, parameters, request/response shapes, and error codes.

/sk:docs "generate API reference documentation from the route files in src/routes/"

What happens: The agent:

1. Scans route files and discovers all endpoints with their HTTP methods and paths
2. Extracts request body shapes from validation schemas (Zod, Joi, etc.)
3. Infers response shapes from controller return statements and error handlers
4. Writes a structured API reference document to docs/

Step 3: Generate architecture documentation

Produce a technical architecture guide that explains the system structure — useful for new team members and client technical reviews.

/sk:docs "generate architecture guide — include system overview, layer diagram, data flow, and key design decisions"

What happens: The agent:

1. Analyzes the codebase layer structure (controllers, services, repositories, etc.)
2. Maps external integrations and background job processing
3. Documents inferred design patterns and architectural decisions
4. Writes an architecture guide with diagrams to docs/

Step 4: Update existing documentation after a sprint

After features are added or APIs change, refresh docs to match the current codebase without rewriting everything.

/sk:docs update

What happens: The agent:

1. Re-analyzes the codebase and compares against existing documentation
2. Identifies new endpoints, modified interfaces, and removed features
3. Updates the affected doc files while preserving manually-written sections
4. Reports what changed in the update

Step 5: Generate a client handoff package

This is the deliverable that marks the formal end of an engagement — everything a client needs to operate, maintain, and extend the system independently.

/sk:docs "generate complete handoff documentation — include system overview, operations guide, runbook, and known issues"

What happens: The agent:

1. Collects all existing documentation and identifies gaps
2. Generates an operations runbook (deploy, rollback, environment setup, health checks)
3. Documents known issues from GitHub issues or TODO comments in code
4. Assembles everything into an indexed handoff package in docs/

Complete Example: Generate Handoff Documentation for Japanese Client

Scenario

Your team has completed a six-month engagement building a B2B SaaS platform for a Japanese logistics company. Delivery date is Friday. The client’s in-house team (two engineers, neither of whom was involved in the build) will take over operations starting Monday. The client’s PM has sent a requirements checklist: system overview, API documentation, environment setup guide, deployment procedure, and a runbook for common operational tasks. You have three hours before the handoff meeting.

Commands chained

# 1. Generate the README if it is out of date
/sk:docs "Refresh README.md — verify all setup steps are accurate, add Docker deployment section, add troubleshooting for common local setup issues"

# 2. Full API reference for the client's engineering team
/sk:docs "Generate complete API reference from src/routes/ — all endpoints, authentication requirements, request/response examples, error codes"

# 3. Architecture guide — the client's team needs to understand the system
/sk:docs "Generate architecture overview for client handoff — plain language descriptions, focus on how to extend the system"

# 4. Generate the operations runbook
/sk:docs "Generate operations runbook — daily health checks, how to deploy, rollback procedure, database backup verification, monitoring alerts guide"

# 5. Assemble the complete handoff package
/sk:docs "Assemble complete handoff package — include all docs generated today"

# 6. Review for completeness and accuracy
/sk:code-review --pending

Result

Two and a half hours before the handoff meeting, you have a comprehensive documentation package covering every item on the client’s checklist. The architecture guide uses plain language. The operations runbook includes exact CLI commands. The API reference has examples for every endpoint. The client’s engineers spend the handoff meeting asking about business logic and edge cases — not asking where to find the documentation or how to deploy the application.

Time Comparison

Documentation Types Reference

Best Practices

1. Run /sk:docs update at the end of every sprint, not just at delivery ✅

Documentation that is updated continuously stays accurate. Documentation that is written once and updated at project end is often 30–40% stale by the time it reaches the client. A quick doc sync at sprint review is negligible; a multi-hour catch-up before handoff is not.

2. Include the handoff package in your Definition of Done ✅

Add “handoff docs up to date” as an explicit acceptance criterion on the final sprint. Clients who receive a complete, accurate handoff package have consistently higher satisfaction scores and fewer post-handoff support requests. Make it a delivery standard, not an optional extra.

3. Do not edit agent-generated docs without marking manual additions ❌

If you add manual context to a generated doc — client-specific business rules, decisions made verbally in a meeting — mark those sections with a comment like <!-- Manual addition -->. This prevents the next /sk:docs update from overwriting context that the agent cannot infer from code alone.

4. Do not use docs as a substitute for clean code ❌

A massive god-object with a multi-page explanation is still a massive god-object. Documentation describes what code does — it does not fix code that is hard to understand. If the architecture doc needs paragraphs to explain why a module works the way it does, consider whether /sk:plan "refactor" is the better investment.

Troubleshooting

Problem: API reference is generated but response shapes are incorrect

Solution: The agent infers response shapes from controller return statements. If your controllers return generic objects or use a shared transformer function, the agent may not be able to infer the full shape. Provide more context in the prompt: /sk:docs "generate API reference — include request/response examples using data from test files".

Problem: Architecture doc describes the planned architecture, not the actual one

Solution: This happens when the codebase diverges from the intended layer structure — for example, when repositories make HTTP calls or controllers run SQL queries. The agent documents what exists, but flags divergences. If you see warnings about layer violations, address the structural issues with a refactoring pass before regenerating the docs.

Problem: Handoff package has gaps that say “manual input required”

Solution: Some information cannot be derived from code: business context, client-specific constraints, verbal decisions, and on-call escalation paths. The agent marks exactly what needs human input. Fill in each placeholder section before sending the package to the client.

Problem: /sk:docs update overwrites sections you had manually customised

Solution: Mark manually written sections with HTML comments so the agent preserves them on update. Add a note at the top of the file indicating which sections are auto-generated vs manually maintained.

Next Steps

• Code Review — Generate a delivery checklist alongside handoff documentation for a complete quality record
• Security Audit & Scan — Include a security audit report in the handoff package for compliance-conscious clients
• Refactor Legacy Code — Improve code clarity before generating architecture docs to make the handoff more useful

Key takeaway: Documentation written at the last minute under deadline pressure is documentation full of gaps — Sun Agent Kit generates it continuously from the codebase itself, so your handoff is accurate, complete, and ready before the client asks for it.