playbooks

home / skills / toilahuongg / shopify-agents-kit / docs-out

docs-out skill

/.claude/skills/docs-out

This skill helps you generate, update, or refactor internal project documentation with clarity and accuracy.

npx playbooks add skill toilahuongg/shopify-agents-kit --skill docs-out

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
1.6 KB
---
name: docs-out
description: Activates the Technical Writer to generate, update, or refactor internal project documentation. Use when creating READMEs, ADRs, or technical guides.
argument-hint: "[file, directory, or topic to document]"
---

# Generate Documentation

Create or update internal technical documentation.

1. **Scope and Strategy**
   - Identify the target for documentation (Specific file, directory, component, or decision).
   - Determine the appropriate artifact type:
     - **README.md**: For directories, components, or project root.
     - **ADR**: For architectural decisions (Architecture Decision Record).
     - **Guide**: For "How-to" or conceptual explanations.
   - Confirm the placement of the documentation (e.g., co-located with code or in a `docs/` folder).

2. **Analysis and Context**
   - Read the relevant source code to ensure technical accuracy.
   - Identify key concepts, architectural patterns, and "gotchas".
   - Review existing related documentation to ensure consistency and avoid duplication.

3. **Draft Documentation**
   - Generate the documentation content using the **Technical Writer** persona.
   - **Focus**:
     - Explain the *Why* and *Structure*, not just the *How*.
     - Use active voice and clear, concise English.
     - Include accurate code snippets with language tags.
     - Use diagrams (Mermaid) if complex relationships exist.

4. **Verification**
   - Validation:
     - Are all commands copy-pasteable and working?
     - Do relative links point to valid files?
     - Is the tone consistent with internal developer documentation?

Overview

This skill activates a Technical Writer persona to generate, update, or refactor internal project documentation such as READMEs, ADRs, and technical guides. It focuses on producing clear, actionable docs that explain intent, structure, and usage for engineers. Use it to create co-located docs or populate a centralized docs/ folder with consistent tone and accuracy.

How this skill works

It inspects the target files, directories, or code components and reads relevant source code to extract key concepts and patterns. It determines the appropriate artifact type (README, ADR, Guide), drafts content with code snippets or Mermaid diagrams when needed, and verifies commands, links, and tone. The output is a ready-to-use document tailored to the chosen placement and audience.

When to use it

  • Creating a new README for a repository, package, or component.
  • Documenting an architectural decision as an ADR.
  • Refactoring or standardizing existing documentation for consistency.
  • Writing a how-to guide or conceptual explanation for a feature.
  • Adding missing usage examples or runnable snippets.

Best practices

  • Start by defining the documentation target and intended audience before drafting.
  • Read the relevant source files to confirm technical details and examples.
  • Prefer ‘Why’ and system structure first, then concise ‘How’ steps and copy-pasteable commands.
  • Include language-tagged code snippets and validate they run locally or in CI.
  • Use Mermaid diagrams for non-trivial relationships and keep visuals minimal and labeled.

Example use cases

  • Generate a README for a new microservice with setup, run, and troubleshooting sections.
  • Write an ADR documenting a technology choice (e.g., message broker selection) with context and consequences.
  • Refactor a scattered docs/ folder into a consistent layout with index and cross-links.
  • Produce a developer guide explaining authentication flows with sequence diagram and sample requests.
  • Update component README to include accurate import paths, props, and examples.

FAQ

Can this skill edit existing files in place?

Yes. It can update or refactor existing documentation; specify the target file or directory and the desired changes.

Will code snippets be validated?

The skill verifies that commands and snippets are copy-pasteable and checks relative links, but you should run integration checks or CI to fully validate runtime behavior.