GitHub stars
15

Install

/plugin install technical-writer@sjungling-plugins

Run it inside Claude Code after adding the marketplace with /plugin marketplace add sjungling/sjungling-claude-plugins.

Contents

Discovered from source

Skills 3

Obsidian Vault Manager

Prerequisites

Before performing vault operations:

  1. Verify obsidian CLI is installed:

    obsidian --version
    

    The CLI is the native obsidian binary that ships with the Obsidian desktop app — not a separate npm package.

  2. List available vaults:

    obsidian vaults
    
  3. Get vault path:

    obsidian vault "<name>" info=path
    

Overview

Use obsidian for vault operations that touch links or structure. For iCloud-synced vaults (path contains Mobile Documents — check with obsidian vault "<name>" info=path), the Write tool is not reliable: iCloud paths are TCC-protected, so direct filesystem writes can be blocked even with the sandbox disabled — only the Obsidian app (via the CLI) is guaranteed to land. For creating a note with substantial content (multi-line, frontmatter, code blocks), use scripts/write-markdown-to-vault.js in this skill — it chunks large payloads under the CLI's ~10KB IPC ceiling, filters banner noise, retries transient errors, and verifies the write by reading the note back. Run it unsandboxed (the CLI hangs under the command sandbox). For vaults on ordinary filesystem paths (not iCloud), the Write tool works directly and is simpler for one-off notes.

Quick Reference

TaskCommandNotes
List vaultsobsidian vaultsAlways run first
Vault infoobsidian vault "<name>"Name, path, file count
Vault pathobsidian vault "<name>" info=pathPath only, good for scripting
List foldersobsidian "vault=<name>" foldersQuote vault name if it has spaces
Read noteobsidian "vault=<name>" read "<note name>"Reads by name (fuzzy)
Create note (large/iCloud)node ${CLAUDE_PLUGIN_ROOT}/skills/obsidian-vault-manager/scripts/write-markdown-to-vault.js --vault <name> --path <path> --input <file>Chunked, retried, verified — run unsandboxed
Create note (small, non-iCloud)obsidian "vault=<name>" create path="folder/name.md" content="$CONTENT"Use printf to build $CONTENT for multi-line
Overwrite noteobsidian "vault=<name>" create path="..." content="$CONTENT" overwrite
Append to noteobsidian "vault=<name>" append path="<path>" content="<text>"
Move noteobsidian "vault=<name>" move path="old.md" newpath="new.md"Auto-updates all links
Search contentobsidian "vault=<name>" search query="<term>" [path=<folder>] [format=json]
Daily noteobsidian "vault=<name>" dailyCreate/open today's note
Active/default vaultobsidian vaultNo name → the vault currently open
Append to daily noteobsidian "vault=<name>" daily:append content="<text>"Active vault; needs Daily Notes plugin

See also:

Core Workflows

Step 1 — Find the Vault

# List vaults to confirm the name
obsidian vaults

# Get full info (name, path, file count)
obsidian vault "<name>"

# Get just the path (useful for scripting)
VAULT_PATH=$(obsidian vault "<name>" info=path)

Step 2 — Explore Structure

# List folders
obsidian "vault=<name>" folders

# Search for existing notes
obsidian "vault=<name>" search query="<topic>" path=<folder> format=json

Step 3 — Create Notes with Rich Content

Use printf to build the content variable — this correctly handles newlines and multi-line content including frontmatter:

CONTENT=$(printf '---\ntags:\n  - til\nindex: "[[Today I learned]]"\n---\n## Heading\n\nContent here.')
obsidian "vault=<name>" create path="til/2026-04-27 My Note.md" content="$CONTENT"

Look at an existing note first to match local formatting conventions (tag names, frontmatter fields, index backlinks, etc.):

obsidian "vault=<name>" read "<existing note name>"

Moving/Reorganizing Notes

# ✅ CORRECT: Auto-updates all links
obsidian "vault=<name>" move path="Random Notes/Design.md" newpath="Projects/Design.md"

# ❌ WRONG: Breaks all links to this note
mv "vault/Random Notes/Design.md" "vault/Projects/Design.md"

Common Mistakes

MistakeWhy WrongFix
Using obsidian-cliThat's a different npm package — the tool is obsidianUse obsidian
Using --flags syntaxThe CLI uses key=value positional args, not --flagsUse key=value format
create with \n in double-quoted stringEscapes get stripped, content truncatedUse printf to build a $CONTENT variable
Using Write on an iCloud vault pathTCC can silently block the write even with the sandbox disabledUse scripts/write-markdown-to-vault.js instead
Content over ~10KB in one create/append callSilent broken pipe (exit 0, nothing written) or a NativeImage errorUse scripts/write-markdown-to-vault.js — it chunks automatically
Using mv to move notesBreaks all [[wiki-links]] to that noteUse obsidian move
Not checking existing note formatEach vault has different tagging/frontmatter conventionsRead an existing note first
Using absolute paths in wiki-linksBreaks when vault movesUse vault-relative paths

When to Use Standard Tools

  • Bulk content editing: Use Edit after reading with obsidian read
  • Complex search patterns: Use Grep directly on the vault path (use obsidian vault "<name>" info=path to get it)

Always preserve:

  • Frontmatter (YAML between ---)
  • Obsidian link syntax [[Note]]
  • Tag syntax #tag-name
  • Markdown structure

Success Criteria

Vault operations succeed when:

  • All [[wiki-links]] remain valid after moves
  • Notes created in correct vault location with full content intact
  • Formatting matches existing notes in the same folder
  • No broken links or orphaned notes

PDF Book Generation

Overview

Converts a directory of ordered markdown chapters into a single, styled PDF book with table of contents, page numbers, and resolved inter-chapter links.

Core principle: The markdown files are the source of truth. The PDF is a derived artifact -- never edit the PDF directly.

When to Use

Automatically activates when:

  • A request to generate a PDF from markdown chapters is made
  • A technical-overview or similar multi-chapter doc set is ready for export
  • A printable or shareable version of documentation is needed

Prerequisites

Three tools must be installed before generation can proceed:

ToolInstall commandPurpose
pandocbrew install pandocMarkdown to HTML conversion
weasyprintuv tool install weasyprintHTML to PDF rendering
pangobrew install pangoText layout (weasyprint dependency)

Before running the script, verify availability:

command -v pandoc >/dev/null 2>&1 || echo "Missing: pandoc (brew install pandoc)"
command -v weasyprint >/dev/null 2>&1 || echo "Missing: weasyprint (uv tool install weasyprint)"

If either tool is missing, install it and retry. The script itself checks for dependencies and exits with a clear error message.

How It Works

The generation pipeline has four stages:

  1. Collect -- Gather markdown files in order: README.md first, then 00-*.md through 99-*.md, then appendix-*.md
  2. Convert -- Pandoc stitches all files into a single HTML document with a generated table of contents
  3. Fix links -- Inter-chapter .md links (e.g., [architecture](01-architecture.md)) are rewritten to internal #anchor links so they work within the single document
  4. Render -- Weasyprint converts the styled HTML to PDF with print-optimized CSS

Usage

Run the generation script using $CLAUDE_PLUGIN_ROOT:

${CLAUDE_PLUGIN_ROOT}/skills/pdf-generation/scripts/generate-pdf.sh <input-dir> [output.pdf]
  • input-dir -- Directory containing the ordered markdown chapters
  • output.pdf -- Optional output path (defaults to <input-dir>/technical-overview.pdf)

Handling Missing CLAUDE_PLUGIN_ROOT

If $CLAUDE_PLUGIN_ROOT is not set (e.g., running outside a plugin context), locate the script manually:

# Fallback: find the script in the plugin installation directory
SCRIPT_PATH=$(find ~/.claude/plugins -path "*/pdf-generation/scripts/generate-pdf.sh" 2>/dev/null | head -1)
if [ -z "$SCRIPT_PATH" ]; then
  echo "Error: generate-pdf.sh not found. Ensure the technical-writer plugin is installed."
  exit 1
fi
"$SCRIPT_PATH" <input-dir> [output.pdf]

Expected Directory Structure

The input directory must contain ordered markdown files following this naming convention:

docs/technical-overview/
├── README.md              # Title page and introduction (always first)
├── 00-getting-started.md  # Numbered chapters in sequence
├── 01-architecture.md
├── 02-data-model.md
├── 03-api-reference.md
├── 04-deployment.md
├── appendix-a-glossary.md # Appendices after numbered chapters
└── appendix-b-faq.md

Expected output:

docs/technical-overview/
├── ... (source files unchanged)
└── technical-overview.pdf  # Generated PDF (default output location)

The PDF includes:

  • A title derived from the first # heading in README.md (or the directory name as fallback)
  • A generated table of contents with depth 2 (h1 and h2 headings)
  • Page numbers centered at the bottom of each page
  • Chapter breaks (each h1 starts on a new page)
  • Resolved inter-chapter links as internal anchors

Inter-Document Linking Requirements

For the PDF to have working internal links, the source markdown must follow these rules:

  • Use relative links between chapters: [architecture overview](01-architecture.md)
  • Section links with anchors work too: [the store layer](03-data-layer.md#store)
  • Every chapter should have exactly one # heading -- this is used to resolve link targets
  • The script warns about any .md links it cannot resolve

Common linking mistakes:

MistakeFix
Absolute paths (/docs/01-arch.md)Use relative paths (01-arch.md)
Missing # heading in chapterAdd exactly one h1 heading per chapter
Link to file not in input directoryEnsure all linked files are in the same directory

Styling and Customization

The script embeds a print-optimized CSS stylesheet with sensible defaults:

  • Page size: US Letter with 1-inch top/bottom margins
  • Fonts: System font stack (Apple system fonts, Segoe UI, Helvetica, Arial)
  • Code blocks: Light gray background with monospace font at 9pt
  • Tables: Bordered with alternating row colors
  • Chapter breaks: Each h1 heading starts on a new page

For detailed CSS customization options (fonts, colors, page sizes, themes), see ./references/css-customization.md.

Troubleshooting

SymptomCauseFix
"Error: 'pandoc' is not installed"Missing dependencybrew install pandoc
"Error: 'weasyprint' is not installed"Missing dependencyuv tool install weasyprint && brew install pango
Warning about unresolved .md linksChapter heading does not match filename patternEnsure each chapter has a # heading and the link target filename is correct
PDF renders but fonts look wrongMissing system fontsweasyprint uses system fonts; install desired fonts via Font Book
Empty PDF or no chapters foundFiles not matching naming conventionVerify files follow README.md, 00-*.md through 99-*.md, appendix-*.md pattern
CLAUDE_PLUGIN_ROOT is emptyRunning outside plugin contextUse the fallback script discovery method described above
Long code blocks overflow marginsDefault CSS handles thisVerify overflow-wrap: break-word and white-space: pre-wrap in CSS

Additional Resources

  • ./references/css-customization.md -- Detailed CSS customization options for fonts, page sizes, colors, and themes
  • ./scripts/generate-pdf.sh -- The generation script (inspect for advanced modification)

Technical Documentation Expert

Overview

Expert guidance for creating clear, comprehensive, and user-friendly technical documentation following industry best practices and structured content models.

Core principle: Write for the audience with clarity, accessibility, and actionable content using standardized documentation patterns.

When to Use

Automatically activates when:

  • Working with .md files in docs/ directories
  • Creating or editing README files
  • Editing documentation files or markup
  • Discussing documentation structure, information architecture, or style guides
  • Creating API documentation with examples and parameter tables
  • Writing user guides, tutorials, or quickstarts
  • Drafting release notes or change logs
  • Structuring specifications or technical proposals

Style reference: For detailed formatting rules, consult ./references/style-guide.md.

When NOT to Use

Do not apply this skill for:

  • Creative writing or marketing copy
  • Code implementation (documentation only)
  • Project management documentation
  • Internal team chat or informal notes
  • Academic papers or research documentation

Core Expertise Areas

Content Types

  1. Conceptual -- Explains what something is and why it matters ("About..." articles)
  2. Referential -- Detailed reference information (API docs, syntax guides, parameter tables)
  3. Procedural -- Step-by-step task completion with numbered lists and gerund titles
  4. Troubleshooting -- Error resolution, known issues, and debugging guidance
  5. Quickstart -- Essential setup in 5 minutes / 600 words maximum
  6. Tutorial -- End-to-end workflow with real-world examples and conversational tone
  7. Release Notes -- Version changes categorized by type (Features, Fixes, Breaking Changes)

Documentation Structure

Standard Article Elements:

  • Titles: Sentence case, gerund for procedures, character limits by level
  • Intros: 1-2 sentences explaining content
  • Prerequisites and permissions when applicable
  • Clear next steps

Information Architecture:

  • Hierarchical structure with maximum 4 navigation levels
  • Content ordering: Conceptual -> Referential -> Procedural -> Troubleshooting

Style Guide Principles

Apply formatting and style rules from the comprehensive style guide:

  • Language: Clear, simple, active voice, sentence case. Avoid jargon without definition. Prefer short sentences (under 25 words). Eliminate filler words ("just", "simply", "basically").
  • Technical formatting: Code in backticks, UI elements in bold, placeholders in ALL-CAPS with descriptive names (e.g., YOUR_API_KEY).
  • Structure: Numbered lists for procedures (sequential steps), bullets for non-sequential information. Limit list items to 7 or fewer when possible.
  • Links: Descriptive text that tells the reader where the link leads. Never use "click here" or bare URLs in prose.
  • Alerts: Use Note, Tip, Important, Warning, Caution sparingly. Reserve Warning and Caution for data loss or security risks.
  • Code examples: Include runnable examples with expected output. Annotate non-obvious lines with inline comments. Verify all examples compile and run against the documented version.

Procedural Content Ordering

Follow standard procedural sequence: Enabling -> Using -> Managing -> Disabling -> Destructive

Within individual steps: Optional info -> Reason -> Location -> Action

Writing Procedures

When writing step-by-step procedures:

  1. Start each step with an action verb (imperative form)
  2. Include only one action per step
  3. Provide expected results after each significant step
  4. Add screenshots or output examples for complex steps
  5. Keep the total number of steps under 10 when possible; break longer procedures into sub-procedures
  6. Place optional steps clearly marked with "Optionally" at the start
  7. Include a "Before starting" or "Prerequisites" section listing required tools, permissions, and knowledge

Development Workflow

1. Understand the Audience

  • Identify user expertise level (beginner, intermediate, advanced)
  • Determine user goals and tasks
  • Consider context where documentation will be consumed
  • Plan appropriate content depth and technical level
  • Match vocabulary to the audience (avoid over-simplifying for experts; avoid under-explaining for beginners)

2. Choose Content Type

Select the appropriate content type based on user intent:

User needContent typeKey characteristics
Understand a conceptConceptual"About..." title, explains what and why
Look up API or syntaxReferentialParameter tables, return types, examples
Complete a specific taskProceduralNumbered steps, gerund title, prerequisites
Fix a problemTroubleshootingSymptom-cause-fix tables, error messages
Get started quicklyQuickstartUnder 5 minutes, under 600 words
Learn end-to-endTutorialReal-world example, conversational tone
Review version changesRelease NotesCategorized by type, links to details

3. Structure Content

Standard content sequence:

  1. Title (sentence case, descriptive, within character limits)
  2. Brief intro (1-2 sentences summarizing what the reader will learn or accomplish)
  3. Prerequisites (if applicable)
  4. Permissions statement (if required)
  5. Main content (ordered appropriately by content type)
  6. Troubleshooting (embedded when helpful, or linked to dedicated troubleshooting doc)
  7. Next steps / Further reading (link to related content)

4. Apply Style Guide

Follow the comprehensive style guide for:

  • Formatting code, UI elements, and placeholders
  • Writing clear procedures with proper structure
  • Adding accessibility features (alt text for images, sufficient color contrast)
  • Ensuring proper link formatting and context
  • Using alerts appropriately and sparingly
  • Verifying content accuracy: do not invent information not in source material

5. Content Accuracy

Critical rule: Do not invent or assume information not present in source material.

  • If gaps exist, ask the user for missing information
  • Do not create placeholder or speculative content
  • Verify technical accuracy with authoritative sources
  • Include working examples whenever possible
  • Check that examples work as documented
  • Validate accessibility (alt text, heading hierarchy, structure)

6. Review and Iterate

After drafting:

  • Read through the document from the reader's perspective
  • Verify all links resolve to valid targets
  • Confirm code examples are complete and runnable
  • Check heading hierarchy (no skipped levels)
  • Ensure consistent terminology throughout
  • Validate that prerequisites actually cover what the reader needs

Communication Style

Clear and Actionable:

  • Use simple, direct language in imperative form
  • Provide specific examples and code snippets
  • Break complex topics into digestible sections
  • Include visual aids when they clarify concepts

Serve Multiple Expertise Levels:

  • Layer content from simple to complex
  • Provide quick reference sections for experienced users
  • Link to deeper explanations for beginners
  • Set expectations with prerequisites

Focus on User Goals:

  • Organize by tasks users want to accomplish
  • Use gerund titles for procedures ("Creating...", "Configuring...")
  • Include "what this covers" or "what to expect" statements
  • Provide clear next steps after each article

Documentation Anti-patterns

Avoid these common mistakes:

Anti-patternFix
Assuming reader context ("As you know...")State prerequisites explicitly
Burying critical info in long paragraphsLead with the most important information
Writing procedures without numbered stepsAlways use numbered lists for sequential tasks
Using jargon without definitionDefine terms on first use or link to glossary
Missing prerequisites sectionList what the reader needs before starting
"Click here" link textUse descriptive text that tells where the link goes
Outdated code examplesVerify all examples work with current versions
Mixing content types in one documentSeparate conceptual from procedural content
Walls of text without headingsAdd headings every 2-4 paragraphs

Success Criteria

Documentation is successful when:

  • Content is accessible to the target audience
  • Structure follows the appropriate content type
  • Examples clarify complex concepts and are verifiably correct
  • Style guide rules are consistently applied
  • Users can complete tasks using the documentation alone
  • Information architecture supports easy navigation
  • Content is accurate, up-to-date, and free of speculation
  • Heading hierarchy is correct (no skipped levels)
  • All links resolve to valid targets

Commands 3

Save the best available content from the current session into an Obsidian vault as a design note.

Parse $1 as an optional vault override and $2 as an optional topic override (both optional — see resolution rules below). $1/$2 are name/topic strings, not file paths — this command never takes an explicit source file; content is always auto-discovered from the session.

Vaults on iCloud storage cannot be written with the Write tool — ~/Library/Mobile Documents/iCloud~md~obsidian/Documents/<vault> is TCC-protected; only the Obsidian app (via the obsidian CLI) can touch it, even with the sandbox disabled. Step 5 below always writes through the CLI — never write directly to a resolved vault path with the Write tool, even for a small note. (Write is only used in this command to stage the note in a scratch temp file before handing it to the CLI script.)

Step 1: Discover content

Run the discovery script, resolved relative to the plugin root:

DISCOVERY=$(bash "${CLAUDE_PLUGIN_ROOT}/scripts/discover-spec-content.sh" 2>&1)

If it exits non-zero, check stderr for {"error": "..."} and report the error (jq not installed, not in a git repository).

Parse the JSON output:

SOURCE=$(echo "$DISCOVERY" | jq -r '.source')
PRIMARY=$(echo "$DISCOVERY" | jq -r '.primary')
SECONDARY=$(echo "$DISCOVERY" | jq -r '.secondary')
SPECS=$(echo "$DISCOVERY" | jq -r '.candidates.specs[]' 2>/dev/null)
PLANS=$(echo "$DISCOVERY" | jq -r '.candidates.plans[]' 2>/dev/null)

superpowers

If PRIMARY is non-empty, read it as $BODY.

If PRIMARY is empty, multiple candidates need disambiguation — use AskUserQuestion with the SPECS/PLANS candidates to pick the file. Read the chosen file as $BODY.

If SECONDARY is non-empty (a related plan), you may append a short "Implementation plan: <path>" reference line to the note rather than inlining the whole plan.

claude-plan

PRIMARY already points to the plan file. Read it as $BODY.

summary

No spec/plan files found. Write a markdown summary of the current conversation covering:

  • Problem — what prompted the session
  • Decisions & rationale — key choices made and why (this is the part worth keeping; skip anything derivable from re-reading the code)
  • Approach — architecture/implementation shape agreed on
  • Open questions — anything unresolved

Use this as $BODY.

Step 2: Resolve the vault

obsidian vaults
  • If $1 was given, validate it: obsidian vault "$1". If that errors, report the failure (name typo — show the list from obsidian vaults) and stop.
  • If $1 was omitted and there is exactly one vault, use it silently.
  • If $1 was omitted and there are multiple vaults, use AskUserQuestion to pick one.

Step 3: Resolve topic → folder + tag conventions

obsidian "vault=$VAULT" folders
  • If $2 was given, case-insensitively match it against the folder list (e.g. topic fraudfront matches folder FraudFront). Use the matching folder.
  • If $2 was given but nothing matches, use AskUserQuestion: create a new top-level folder named after the topic, or pick an existing folder instead.
  • If $2 was omitted, infer a topic guess from the current repo/project name (e.g. git rev-parse --show-toplevel basename, or the project name in CLAUDE.md) and propose it via AskUserQuestion alongside "pick a different existing folder" and "type a topic".

Once the folder is resolved, learn its formatting conventions rather than inventing your own:

# List existing note filenames in the folder (folders command doesn't list files — use find on the vault path)
VAULT_PATH=$(obsidian vault "$VAULT" info=path)
ls "$VAULT_PATH/$FOLDER" 2>/dev/null

If notes exist, obsidian "vault=$VAULT" read "<one existing note>" and match its frontmatter shape (tag names, whether it uses date/status fields, filename separator style — e.g. em dash + " Design" suffix). If the folder is empty, default to: tags = [<topic-slug>, design] plus any specific keyword tag drawn from the note's own title, frontmatter fields tags/date/status: draft.

Step 4: Build the note

  • Title: the first # (H1) heading in $BODY, or the first non-empty non-frontmatter line if there's no H1.
  • Filename: match the existing folder's naming convention from Step 3; if none observed, use <Title>.md.
  • Frontmatter: the tags/fields resolved in Step 3, date: <today, YYYY-MM-DD>, status: draft.
  • Body: $BODY as-is below the frontmatter (don't re-summarize or truncate — the write script in Step 5 chunks automatically, so there's no size limit to work around here, unlike posting to GitHub).

Stage it with the Write tool at a scratch path (mktemp "${TMPDIR:-/tmp}/obsidian-note-XXXXXX.md") — not in the vault.

Step 5: Write through the CLI

Check whether a note already exists at the target path first:

obsidian "vault=$VAULT" read "path=$FOLDER/$FILENAME"

If it returns real content (not a "not found" error), use AskUserQuestion: overwrite, save under a new dated variant (append — <date> to the filename), or abort.

Then write via the dedicated script — this MUST run unsandboxed (the obsidian CLI connects to the running app over a local socket that the command sandbox blocks and hangs on):

node "${CLAUDE_PLUGIN_ROOT}/skills/obsidian-vault-manager/scripts/write-markdown-to-vault.js" \
  --vault "$VAULT" \
  --path "$FOLDER/$FILENAME" \
  --input "$NOTE_FILE" \
  --overwrite   # only if Step 5's collision check confirmed overwrite

The script chunks large notes automatically, retries transient CLI errors, and verifies the write by reading the note back — treat a non-zero exit as a real failure, not a warning. It also warns (on stderr) if the source content contains literal \n/\t two-character sequences (e.g. a code sample describing escape sequences) — the obsidian CLI cannot distinguish these from real newline/tab escapes and will silently convert them, which is a CLI limitation, not something this command can fix. If that warning fires, mention it in your report so the user knows to spot-check that section of the note.

Step 6: Report

Report to the user:

  • Vault name and note path
  • Tags applied
  • Whether this created a new note or overwrote an existing one
  • Any \n/\t literal-escape warning from Step 5

Create or update a comprehensive technical manual for this project. The output directory is $ARGUMENTS (default: docs/technical-overview if no path given).

Before writing any content, invoke the technical-writer skill to load the full technical writing style guide. All chapters must follow those conventions — in particular: sentence case for all headings (never title case), descriptive link text (never "click here"), and the standard content structure rules.

Writing style

Write like Beej's Guide to Network Programming — colloquial, approachable, educational. The reader is a competent programmer but may not be an expert in this project's language or frameworks. Explain concepts as you go. Use code examples but keep them concise. Avoid dry reference-manual tone.

Good: "So what's actually happening when you call beginTask()? Think of it like a relay race — the navigation state hands the baton to the store, which sets up the worktree, and then signals the view to pick it up."

Bad: "The beginTask() method initiates task execution by delegating to the repository store."

Process

1. Understand the project

Read CLAUDE.md, README, and key entry points to understand the architecture, frameworks, and major concepts. Identify:

  • The main frameworks/packages/libraries the project has built (not third-party deps)
  • Core workflows and data flows
  • Key concepts a new developer needs to understand
  • The language and platform conventions in use

2. Plan the chapters

Create a table of contents with individual chapters. Always include:

  • 00-introduction.md — What is this project? Who is it for? How to read this guide.
  • One chapter per major framework/package/library the project has built
  • One chapter per major workflow or concept (e.g., task execution, navigation, data persistence)
  • appendix-glossary.md — Key terms and their definitions

Write the table of contents to {output-dir}/README.md first.

3. Write chapters in parallel using teammates

Launch one Agent (subagent_type: "general-purpose", model: "sonnet") per chapter. Each agent should:

  • Read the actual source files for every type, method, and data flow they will reference — do not infer type names or signatures from CLAUDE.md alone. If writing about navigation, read the navigation source files directly.
  • Read any existing version of their chapter file (to update rather than rewrite from scratch)
  • Write or update their chapter file in {output-dir}/
  • Follow the writing style guidelines above
  • Include real code snippets from the project (not invented examples)
  • Explain the "why" not just the "what"
  • Target 1,000–1,500 words for complex topics (architecture, data flow, task lifecycle); 500–800 words for focused utility chapters

Give each agent the full context: project name, language, the table of contents for cross-referencing, and the style guidelines.

4. Technical accuracy review

Launch a single Agent (subagent_type: "general-purpose", model: "opus") to act as a technical editor. It should:

  • Read every chapter written in {output-dir}/
  • For each type name, method signature, enum case, or data flow described, verify it against the actual source files
  • Make targeted in-place edits to fix any invented identifiers, wrong signatures, or misrepresented flows — do NOT rewrite for style, patch facts only
  • Append a brief <!-- accuracy-review: ... --> comment at the bottom of any file it corrects, summarising what changed

5. Review and link

After all chapters are written and reviewed, read through the output directory and:

  • Ensure cross-references between chapters are correct and use relative markdown links
  • Verify the README table of contents matches actual files
  • Check that code examples reference real files/lines in the project

7. Generate PDF

Invoke the pdf-generation skill and run the generation script to produce a PDF book from the completed chapters. This gives the user a single shareable/printable artifact.

Important rules

  • If chapters already exist, UPDATE them rather than rewriting from scratch. Preserve good content, fix outdated content.
  • Use filenames like 01-architecture.md, 02-navigation.md, etc. for ordering.
  • Each chapter should stand alone — a reader should be able to jump to any chapter.
  • Include a "What you'll learn" section at the top of each chapter.
  • End each chapter with "Where to go next" pointing to related chapters.
  • Do NOT invent code examples. Pull real snippets from the actual source files.
  • Create the output directory if it doesn't exist.
  • Inter-document linking must be complete. Every cross-reference between chapters must use relative markdown links (e.g., [architecture overview](01-architecture.md) or [the store layer](03-data-layer.md#store)). The final set of markdown files should be self-contained so they can be collated and converted to a single PDF without broken links.

Launch the walkthrough agent to generate a comprehensive code walkthrough with context isolation.

Pass the following context to the agent:

  • Plugin root: ${CLAUDE_PLUGIN_ROOT}
  • Target path: $ARGUMENTS (or the current working directory if none provided)
  • Working directory: the current project root

When the agent completes, report its summary to the user including the output file path and what was covered.

Agents 3

Deprecated: This agent is superseded by the obsidian-vault-manager skill, which activates automatically. Use the skill instead.

You must use the obsidian-vault-manager skill.

Deprecated: This agent is superseded by the technical-writer skill, which activates automatically. Use the skill instead.

You must use the technical-writer skill.

Generate a comprehensive code walkthrough for the source at the provided path (or the current working directory if no path is given). The dispatching command will provide the target path and plugin root.

Walkthrough Structure

Produce a walkthrough that follows this structure:

  1. Introduction -- Brief overview of what the codebase does, its purpose, and key technologies
  2. Entry point -- Identify and explain the main entry point (e.g., main.swift, index.ts, app.py)
  3. Module flow -- Walk through each major module or component in logical order, explaining how data and control flow between them
  4. Key concepts -- Highlight important design patterns, architecture decisions, or non-obvious implementation details
  5. Configuration and dependencies -- Explain build configuration, dependency management, and environment setup
  6. Summary -- Recap the overall architecture and suggest where a new contributor should start

Workflow

  1. Read the source at the given path to understand the codebase structure
  2. Plan a linear walkthrough that explains how the code works in a logical reading order
  3. Check if showboat is available: command -v showboat >/dev/null 2>&1 || uvx showboat --help 2>/dev/null
  4. If showboat is available:
    • Create a walkthrough.md file in the repo root
    • Use showboat note for commentary and narrative
    • Use showboat exec with sed, grep, cat, or similar tools to include relevant code snippets
  5. If showboat is NOT available:
    • Write the walkthrough directly to walkthrough.md using the Write tool
    • Include code snippets using standard markdown fenced code blocks
    • Read relevant source files and extract key sections inline

Output Quality Criteria

  • Every code snippet must have surrounding context explaining what it does and why
  • Avoid dumping entire files; extract the relevant 5-30 lines that illustrate the point
  • Use consistent heading levels (h2 for major sections, h3 for subsections)
  • Include file paths in code block headers so the reader knows where to find the source
  • The walkthrough should be understandable to someone unfamiliar with the codebase

Report Summary

Provide a concise summary including:

  • Path to the generated walkthrough file
  • Number of sections/modules covered
  • Whether showboat or plain markdown was used

Sponsors

Details

Marketplace
sjungling/sjungling-claude-plugins
Source
plugins/technical-writer
Category
Community

More from sjungling/sjungling-claude-plugins

All 15