agentleFS
tosin2013tosin2013/mcp-adr-analysis-server/.agents/skills/document-specialist/SKILL.md

documentation-specialist

Skill35 starsChanged 20 days agoMITView on GitHub

This skill should be used when creating professional software documentation (SRS, PRD, OpenAPI, SDD, architecture docs, user manuals, tutorials, runbooks) from templates (greenfield) or reverse-engineering documentation from existing code like Spring Boot or FastAPI (brownfield). Also handles documentation audits/reviews, format conversion (Markdown, DOCX, PDF), and diagram generation (Mermaid first: C4, sequence, class, ER, state, flowchart; PlantUML Salt for UI wireframes and leftover UML). Use when asked to "create documentation", "document my code", "write SRS", "generate PRD", "write DESIGN_DOC.md", "architecture document", "wireframe", or "documentation specialist".

4 other projects use a version of this, 1 of them edited.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

8 rules. About 0 are common, 4 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Greenfield: - Create documentation from templates (SRS, PRD, SDD/DESIGN_DOC.md, architecture, OpenAPI, User Manuals, Tutorials, Runbooks)

    line 22
  2. Distinctive:

    Every document this skill writes uses exactly one voice pack.

    line 49
  3. Very specific:

    Do not use an em dash (—) or a double hyphen standing in for one (-- as punctuation).

    line 62
  4. Distinctive:

    Do not start a sentence with So, That, Thus, or Hence.

    line 63
  5. Distinctive:

    Do not start a sentence with a dangling demonstrative ("That is why..." as a lead).

    line 64
  6. Distinctive:

    After the draft exists, run the chosen pack:

    line 68
  7. Very specific:

    When intent is DESIGN, save the SDD as DESIGN_DOC.md (or docs/DESIGN_DOC.md).

    line 91
  8. Very specific:

    When WikiTicket SDD asks for an architecture doc, a code walkthrough, or a requirements doc, use this skill for prose and wireframes, …

    line 173

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Documentation Specialist Skill

Quick Start

Software documentation creation, extraction, conversion, and diagramming capabilities.

Capabilities:

  1. Greenfield - Create documentation from templates (SRS, PRD, SDD/DESIGN_DOC.md, architecture, OpenAPI, User Manuals, Tutorials, Runbooks)
  2. Brownfield - Reverse-engineer documentation from code (Spring Boot, FastAPI)
  3. Audit - Review and improve existing documentation
  4. Convert - Transform formats (MD to DOCX to PDF)
  5. Diagram - Mermaid first (C4, sequence, class, ER, state, flowchart). PlantUML Salt for UI wireframes. PlantUML for leftover UML (use case, timing, ArchiMate, nwdiag, WBS).

Example Requests:

Create an SRS for a billing system with PCI-DSS compliance
Write DESIGN_DOC.md for this repository using arc42
Create an architecture document with C4-style Mermaid
Document my Spring Boot application at ~/projects/customer-api
Create a user manual for my SaaS product
Write a database failover runbook
Audit my API documentation at docs/api/openapi.yaml
Convert docs/srs.md to Word format
Create a C4 container diagram for my microservices
Draw a login wireframe

Execution Flow:

  1. Classify intent to 2. Choose one voice pack to 3. Load workflow to 4. Execute steps to 5. Generate documentation to 6. Present post-processing options

Voice pack (required, pick one)

Every document this skill writes uses exactly one voice pack. Do not mix them.

PackWhenSource
STE100 (default)Procedures, runbooks, manuals, architecture docs, code walkthroughs, requirements, and any request that does not name Google styleste100 skill (SpillwaveSolutions/ste100-agent-plugins)
google-docs-styleUser says "Google style", "Google docs style", or "developer style guide"google-docs-style skill (SpillwaveSolutions/google-docs-style)

Default is STE100. Switch only when the user names Google style. If both are named, ask which pack to use. Do not apply both.

Hard bans (both packs)

These apply even if a template or prior draft used them:

  • Do not use an em dash (—) or a double hyphen standing in for one (-- as punctuation). Use a period or a comma.
  • Do not start a sentence with So, That, Thus, or Hence.
  • Do not start a sentence with a dangling demonstrative ("That is why..." as a lead).

STE100 also requires: short sentences, one instruction per step, active voice, no contractions, no e.g. / i.e. / etc., no weak modals in steps. Load 11-voice-and-style.md.

After the draft exists, run the chosen pack:

  • STE100: follow the local orchestrator / editor / adversary loop in the ste100 skill. No network.
  • Google style: run python3 scripts/google_docs_style.py --lint --check when that skill is installed.

Intent Classification

IntentKeywordsWorkflow
CREATE_NEW"create", "generate", "write" + doc typegreenfield-workflow.md
DESIGN"DESIGN_DOC.md", "SDD", "software design document", "arc42", "architecture document", "architecture.md"design-workflow.md
CODE_TO_DOCS"document", "extract", path referencebrownfield-workflow.md
AUDIT"audit", "review", "check", "improve"audit-workflow.md
CONVERT"convert", "to Word", "to PDF"convert-workflow.md
DIAGRAM"diagram", "C4", "sequence", "ER", "class", "state", "wireframe", "mock", "Salt"diagram-workflow.md
USER_DOCS"user manual", "how-to", "getting started"user-docs-workflow.md
TUTORIAL"tutorial", "API guide", "CLI docs"tutorial-workflow.md
RUNBOOK"runbook", "procedure", "incident"runbook-workflow.md

CRITICAL: Load only the workflow needed for the current intent. Avoid loading multiple workflows.

When intent is DESIGN, save the SDD as DESIGN_DOC.md (or docs/DESIGN_DOC.md). Save the short C4 form as docs/architecture.md.


Document Type to Template

Requirements and Design:

TypeTemplateDefault output
SRSrequirements-srs.mddocs/srs.md
PRDrequirements-prd.mddocs/prd.md
SDD (arc42)DESIGN_DOC.mdDESIGN_DOC.md
Architecture (C4 short)architecture.mddocs/architecture.md
OpenAPIapi-openapi.yamlopenapi.yaml

User Documentation:

TypeTemplate
User Manualuser-manual.md
How-To Guidehowto-guide.md
Getting Startedgetting-started.md

Developer and Operations:

TypeTemplate
Developer Tutorialdeveloper-tutorial.md
Runbookrunbook.md

Framework Detection (Brownfield)

FrameworkDetectionMapping
Spring Bootpom.xml, @SpringBootApplicationspring-boot-mapping.yaml
FastAPIrequirements.txt, from fastapi importfastapi-mapping.yaml

Process: Glob for detection files to Grep for patterns to Load mapping to Follow brownfield workflow


On-Demand Resources

Load only what is needed for the current task.

Workflows

  • Workflow TOC - Navigation index
  • design-workflow.md
  • greenfield-workflow.md
  • brownfield-workflow.md
  • audit-workflow.md
  • convert-workflow.md
  • diagram-workflow.md
  • user-docs-workflow.md
  • tutorial-workflow.md
  • runbook-workflow.md

Reference Guides

  • comprehensive-guide.md - Navigation to all 27 reference guides
  • 11-voice-and-style.md - STE100 vs Google style, hard bans
  • 04-diagrams-selection.md - Mermaid first, PlantUML leftover types, Salt UI wireframes
  • 03-design-arc42.md - The twelve arc42 sections

Examples

  • Examples TOC - Navigation to all examples
  • DESIGN: ecommerce-sdd.md, architecture-doc.md, ui-wireframes.md
  • Brownfield SDD: spring-boot-sdd.md
  • This skill's own SDD: DESIGN_DOC.md

Skill Integration

SkillInvocation Trigger
ste100Default voice pack. Procedures, runbooks, architecture docs, walkthroughs, requirements
google-docs-styleUser names Google style. Mutually exclusive with ste100
design-doc-mermaidDefault diagrams: C4, flowchart, sequence, class, ER, state, component views. GitHub wiki renders the fence.
plantumlUI wireframes (Salt), use case, timing, ArchiMate, nwdiag, WBS. Always PNG or SVG
docxRequest includes Word format
pdfRequest includes PDF format

When WikiTicket SDD asks for an architecture doc, a code walkthrough, or a requirements doc, use this skill for prose and wireframes, design-doc-mermaid for every GitHub-safe diagram, and plantuml only for leftover types.

GitHub wiki: embed Mermaid. Upload PlantUML images with the page. Confluence: render Mermaid and PlantUML to PNG or SVG and upload both.


Error Handling

ErrorResponse
Cannot detect frameworkAsk: "Is this Spring Boot, FastAPI, or another framework?"
Missing templateUse closest match, inform user
Skill not availableOffer markdown-only alternative
Ambiguous requestAsk: "Would you prefer SRS (formal), PRD (agile), or DESIGN_DOC.md (arc42)?"
Both voice packs namedAsk which pack to use. Do not mix
User-facing UI with no SaltAdd one PlantUML Salt wireframe per screen. Do not use a Mermaid flowchart as a stand-in

End of SKILL.md (v3.3.0)

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.