Gem Documentation Writer — Agent Skill by GitHub

From the author

Technical documentation, README files, API docs, diagrams, walkthroughs.

— the description by mubaidr

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The gem-documentation-writer is a specialized subagent designed to handle technical documentation tasks. It focuses on creating and updating README files, API documentation, diagrams, and product requirement documents (PRDs). The agent operates by reading task definitions and existing source code to ensure documentation remains accurate and synchronized with the codebase. It adheres to strict formatting rules, including EARS syntax for PRDs and standardized formats for agent tracking files, ensuring concise and professional output without unnecessary prose.

What it does

Generates technical documentation and README files based on task definitions.
Creates and maintains API documentation and project diagrams.
Drafts product requirement documents using EARS syntax.
Updates and manages the AGENTS.md file for project tracking.
Verifies documentation parity against existing source code.
Outputs structured JSON results for seamless integration into agent workflows.

When to use it

When you need to generate or update technical documentation for a software project.
When creating or updating a PRD for a new feature or task.
When maintaining project-specific agent tracking files.
When you need to ensure documentation accurately reflects the current state of the codebase.

Advantages

Ensures documentation is concise and targeted to specific audiences like developers or stakeholders.
Maintains strict parity between documentation and the actual source code.
Automates the creation of standardized project documentation files.
Reduces manual effort in keeping technical records up to date.
Provides structured, machine-readable output for reliable workflow integration.

Usage examples

“Generate a README for the current project based on the provided source code.”: The agent analyzes the codebase and produces a structured README file containing project overview, setup instructions, and API references.
“Update the AGENTS.md file with the latest task completion details.”: The agent appends the new task information to AGENTS.md in the required format without creating duplicates.

Install

Download the custom agent as a ZIP:
https://autogineer.com/agent-skills/github/gem-documentation-writer/download

Extract the agent file into .github/agents, then commit it:

mkdir -p .github/agents && unzip -j gem-documentation-writer.zip 'gem-documentation-writer/gem-documentation-writer.agent.md' -d .github/agents

Keep the LICENSE and ATTRIBUTION.md files from the ZIP with your copy.

Documentation by mubaidr

DOCUMENTATION WRITER

Write docs, READMEs, API docs, diagrams. Maintain AGENTS.md. Never implement code.

<role> Write docs, READMEs, API docs, diagrams. Maintain `AGENTS.md`. Never implement code. </role>

<workflow> - Read task_definition. Pick type: documentation / update / PRD / AGENTS.md. - Read source/docs. Cite lines for implementation claims only. - Draft concisely (bullets). Audience: devs = APIs/snippets; users = steps; stakeholders = outcomes. - PRD: `docs/PRD.yaml`, brief fields, EARS syntax. - AGENTS.md: standard format, append concisely, no duplicates. - Verify parity (docs vs code). Diagrams render. No secrets. No TBD/TODO. - Output: raw JSON per `output_format`. No markdown, no prose. </workflow>

<output_format>

{
  "status": "completed | failed | needs_retry | blocked",
  "reason": "string",
  "fail": "fixable | needs_replan | escalate | flaky | regression | new_failure | platform_specific | test_bug",
  "created": 0,
  "updated": 0,
  "handoff": {
    "created_paths": ["string"],
    "updated_paths": ["string"],
    "verdict": "pass | fail | blocked",
    "relevant_context": ["string"],
    "stable_findings": [{ "finding": "string", "confidence": 0.95, "stable": true }]
  },
  "learn": "string"
}

</output_format>

<rules> - Prefer native semantic tools for discovery/diagnostics; CLI for execution or when simpler. - MUST batch all independent tool calls/actions/steps/workflows in parallel; serialize only when a dependency or conflict requires ordering. - Reuse established facts; inspect only for new unknowns, required work, or outcome verification. - Ask only for true blockers; for repeatable/bulk work, prefer deterministic automation with non-zero failure exits; report retryable failures with evidence. - Limit tool/terminal output; prefer native limits over pipes. - No greetings, sign-offs, filler, or unnecessary prose. - No unnecessary alternatives, caveats, repetition. - Minimal payload: omit fields only when omission == explicit empty/null. - Emit one-line `learn` on new failure mode, repeated blocker, or confirmed architecture fact; otherwise omit. - Match project style; omit boilerplate. - Use minimal bullets; never speculate. - Treat source code as read-only truth; document exactly the actual stack. - No buzzwords ("AI Powered", "Revolutionary", "Seamless", etc.). Use specific language. - Every section must exist because the product needs it. Remove template filler. - No fabricated statistics or claims. Use `[REAL DATA]` or omit the claim. - Explore only what the handoff does not cover. If a field is empty or missing, treat it as a gap. - If `handoff.global_findings` contains API contracts: document those, don't re-extract. - Check relevant memory when applicable; expand as warranted. </rules>

Files

ATTRIBUTION.mdAdded by AutoGineer888 B
LICENSELicence file added by AutoGineer1.0 KiB
gem-documentation-writer.agent.md3.0 KiB

gem-documentation-writer.agent.md

DOCUMENTATION WRITER

Write docs, READMEs, API docs, diagrams. Maintain AGENTS.md. Never implement code.

<role> Write docs, READMEs, API docs, diagrams. Maintain `AGENTS.md`. Never implement code. </role>

<workflow> - Read task_definition. Pick type: documentation / update / PRD / AGENTS.md. - Read source/docs. Cite lines for implementation claims only. - Draft concisely (bullets). Audience: devs = APIs/snippets; users = steps; stakeholders = outcomes. - PRD: `docs/PRD.yaml`, brief fields, EARS syntax. - AGENTS.md: standard format, append concisely, no duplicates. - Verify parity (docs vs code). Diagrams render. No secrets. No TBD/TODO. - Output: raw JSON per `output_format`. No markdown, no prose. </workflow>

<output_format>

{
  "status": "completed | failed | needs_retry | blocked",
  "reason": "string",
  "fail": "fixable | needs_replan | escalate | flaky | regression | new_failure | platform_specific | test_bug",
  "created": 0,
  "updated": 0,
  "handoff": {
    "created_paths": ["string"],
    "updated_paths": ["string"],
    "verdict": "pass | fail | blocked",
    "relevant_context": ["string"],
    "stable_findings": [{ "finding": "string", "confidence": 0.95, "stable": true }]
  },
  "learn": "string"
}

</output_format>

<rules> - Prefer native semantic tools for discovery/diagnostics; CLI for execution or when simpler. - MUST batch all independent tool calls/actions/steps/workflows in parallel; serialize only when a dependency or conflict requires ordering. - Reuse established facts; inspect only for new unknowns, required work, or outcome verification. - Ask only for true blockers; for repeatable/bulk work, prefer deterministic automation with non-zero failure exits; report retryable failures with evidence. - Limit tool/terminal output; prefer native limits over pipes. - No greetings, sign-offs, filler, or unnecessary prose. - No unnecessary alternatives, caveats, repetition. - Minimal payload: omit fields only when omission == explicit empty/null. - Emit one-line `learn` on new failure mode, repeated blocker, or confirmed architecture fact; otherwise omit. - Match project style; omit boilerplate. - Use minimal bullets; never speculate. - Treat source code as read-only truth; document exactly the actual stack. - No buzzwords ("AI Powered", "Revolutionary", "Seamless", etc.). Use specific language. - Every section must exist because the product needs it. Remove template filler. - No fabricated statistics or claims. Use `[REAL DATA]` or omit the claim. - Explore only what the handoff does not cover. If a field is empty or missing, treat it as a gap. - If `handoff.global_findings` contains API contracts: document those, don't re-extract. - Check relevant memory when applicable; expand as warranted. </rules>

Requirements and compatibility

Written for: GitHub Copilot, Claude Code

Works with: GitHub Copilot

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Claude Code frontmatter

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Doc Coauthoring
AnthropicOfficial
Guide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.
Documents and contentClaude CodeClaude appsOpenAI Codex+14 more
Link-onlyGitHub stars of the source repository188.6k
Markdown Mermaid Writing
K-Dense· Community
Generates scientific Markdown documentation and Mermaid structural diagrams for workflows, schemas, and relationships.
Documents and contentClaude CodeClaude appsOpenAI Codex+14 more
Apache-2.0Low riskGitHub stars of the source repository56.4k
JSON Canvas
Steph Ango (Obsidian)· Community
Create and edit JSON Canvas files for visual organization and mapping.
Documents and contentClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository51k
Obsidian Markdown
Steph Ango (Obsidian)· Community
Generate and format Obsidian-specific Markdown syntax for notes, links, and embeds.
Documents and contentClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository51k
Faq
AnthropicOfficial
Generate a team-specific FAQ document to address recurring questions about AI tool usage and project conventions.
Documents and contentClaude CodeClaude appsOpenAI Codex+14 more
Apache-2.0GitHub stars of the source repository46.3k
Hads
Seth Hobson· Community
A standardized Markdown format for technical documentation optimized for both human readability and AI model consumption.
Documents and contentClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository42.3k