Add write-docs skill for Claude Code documentation workflows#455
Add write-docs skill for Claude Code documentation workflows#455samgutentag wants to merge 16 commits intomainfrom
Conversation
Set up three subagents for accelerating Trunk docs workflows: - doc-writer (Opus): full documentation drafting with structured outputs - doc-researcher (Sonnet): context gathering from Linear and existing docs - changelog-writer (Sonnet): focused changelog/release note entries Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Add branch-manager agent for git branch, PR, and Linear ticket lifecycle - Update agents README with branch-manager in the available agents table - Add Local Development section to repo README with GitBook preview workflow Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Add notes-processor agent for end-to-end pipeline: notes file in, branch/PR/Linear ticket out - Add .claude/drafts/ directory with template for Slack pastes and engineer notes - Update agents README with new workflow documentation - Add .gitignore rules to keep personal drafts out of git Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Explainers enhance existing docs with examples and scenarios based on customer questions, with guidelines to keep workflow guides clean. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Agents now produce a .sources.md file alongside each notes file, listing every Linear ticket, GitHub PR, existing doc, code snippet, and external reference used as input. Provides a human-readable audit trail for accuracy checks and cross-referencing. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Add review report generation (Phase 6) to notes-processor agent - Add Slack link extraction and attachment to Linear tickets - Add automatic search and linking of related engineering tickets - Enrich PR bodies with Slack context and related ticket references - Add Slack Links field to notes template - Create session report at .claude/reports/2026-02-17-docs-backlog.md - Replace Claude Squad references with sequential workflow docs - Add "What the Agent Does" section to README explaining all 6 phases Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Agents now extract and attach all URLs from notes files — Slack, Slite, Loom, Google Docs, Notion, and any other context links. All are attached to Linear tickets and referenced in PR bodies. Template field renamed from "Slack Links" to "Context Links". Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Changelog entries now staged to .claude/staging/changelog/ for DatoCMS upload - Review reports output as HTML (open in browser with clickable links and checkboxes) - Remove old markdown report format - Add .claude/staging/ and .claude/reports/*.html to .gitignore - Update notes-processor with Phase 5.5 (changelog) and updated Phase 6 (HTML report) - Broaden template "Slack Links" to "Context Links" (Slack, Slite, Loom, etc.) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Move all agent outputs to .claude/tmp/ (report.html, changelogs/, slack/, sources/) - Add Phase 5.6: Slack post generation for internal team notification - Remove console text summary output format - Require clickable Linear links in all sources files - Simplify .gitignore to single .claude/tmp/ entry - Clean up old staging/, reports/, and drafts/*.sources.md locations Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Ensure GitHub PRs and Linear tickets cross-reference each other by requiring a Linear ticket ID prefix in PR titles and clickable Linear URLs in PR bodies. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Visual diagrams showing the 8-phase notes-processor pipeline flow and how the 5 agents collaborate with external services. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Remove the 6 separate agent files (.claude/agents/) and replace with a consolidated write-docs skill (.claude/skills/write-docs/) that handles the full notes-to-PR workflow including duplicate detection, research, drafting, branching, Linear updates, and staged outputs. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
|
✨ Submitted to Merge by github-actions[bot]. It will be added to the merge queue once all branch protection rules pass and there are no merge conflicts with the target branch. See more details here. |
|
Claude finished @samgutentag's task in 1m 30s —— View job Review Complete
Overall the PR is well-structured and clearly written. Found 3 minor issues (all non-blocking), with inline suggestions attached:
No blocking issues. The |
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
.claude/drafts/TEMPLATE.md
Outdated
|
|
||
| <!-- Brief description of the product change, if you know it. | ||
| If you only have context below, leave this blank | ||
| and the agents will figure it out. --> |
There was a problem hiding this comment.
This comment still refers to "agents" but this PR replaces the agent-based approach with a single skill. Should be updated for consistency:
| and the agents will figure it out. --> | |
| and the skill will figure it out. --> |
.claude/skills/write-docs/README.md
Outdated
|
|
||
| style A fill:#4a9eff,color:#fff | ||
| style STOP fill:#ff6b6b,color:#fff | ||
| style K fill:#51cf66,color:#fff |
There was a problem hiding this comment.
The style STOP directive references a node named STOP that doesn't exist in the diagram — the actual nodes are STOP1 and STOP2. This means the red styling won't render. Should be two separate style lines:
| style K fill:#51cf66,color:#fff | |
| style STOP1 fill:#ff6b6b,color:#fff | |
| style STOP2 fill:#ff6b6b,color:#fff |
.claude/skills/write-docs/SKILL.md
Outdated
|
|
||
| ### Phase 7: Clean Up | ||
|
|
||
| 19. Return to the original branch and restore any stashed changes. |
There was a problem hiding this comment.
Step numbering skips 18 — Phase 6 ends at step 17, and Phase 7 starts at step 19. Should be renumbered:
| 19. Return to the original branch and restore any stashed changes. | |
| 18. Return to the original branch and restore any stashed changes. |
|
/trunk merge |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
…k/Slite MCP Apply best practices from Claude skill authoring guide: - Split SKILL.md into main file + OVERLAP-CHECK.md and OUTPUTS.md reference files for progressive disclosure (Claude loads them only when reaching the relevant phase) - Trim SKILL.md from 210 to ~130 lines by removing what Claude already knows - Add progress checklist for tracking workflow phases - Add table of contents for navigability - Expand Phase 2 research to include Slite (PRDs, specs) and Slack (#team-flaky-tests, #team-merge-queue) as additional context sources - Merge DEMO.md into skill README.md as the single human-facing reference - Rename "agents" to "skills" in drafts template Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
|
Claude finished @samgutentag's task in 2m 9s —— View job Review Complete
The previous 3 issues from the prior review are all resolved in the latest commit — the TEMPLATE.md "agents" wording, the Mermaid
Inline suggestions attached for all four. |
|
|
||
| ### Phase 3: Draft Documentation | ||
|
|
||
| 8. Write or edit documentation: |
There was a problem hiding this comment.
Step numbering is off here — Phase 2 ends at step 8. **Gap analysis** (line 77) and Phase 2.5 uses step 9. (line 81), so Phase 3 should start at step 10. not 8.. This causes all subsequent phases to also be numbered 2 behind.
| 8. Write or edit documentation: | |
| 10. Write or edit documentation: |
| .DS_Store | ||
| /.idea/workspace.xml | ||
|
|
||
| # Agent drafts (notes files are personal, template is committed) |
There was a problem hiding this comment.
Comment still says "Agent drafts" but this PR replaces agents with a skill. Minor inconsistency:
| # Agent drafts (notes files are personal, template is committed) | |
| # Skill drafts (notes files are personal, template is committed) |
| .claude/drafts/*.md | ||
| !.claude/drafts/TEMPLATE.md | ||
|
|
||
| # Agent outputs (local working files, all under tmp/) |
There was a problem hiding this comment.
Same — "Agent outputs" → "Skill outputs" for consistency:
| # Agent outputs (local working files, all under tmp/) | |
| # Skill outputs (local working files, all under tmp/) |
| - [ ] No existing `.claude/tmp/indefinite-monitor-muting/` directory | ||
| - [ ] Claude Code starts cleanly and recognizes the skill | ||
| - [ ] MCP servers are responding (Linear, GitBook, Slack, Slite) | ||
| - [ ] Terminal font size is readable from the back of the room |
There was a problem hiding this comment.
The dry run checklist lists "GitBook" as an MCP server to verify, but GitBook is the publishing platform — not an MCP server. The actual MCP servers listed in Prerequisites are claude.ai Slack, claude.ai Trunk Slite, claude.ai trunk docs, and claude.ai Linear. Suggest aligning the checklist with that list:
| - [ ] Terminal font size is readable from the back of the room | |
| - [ ] MCP servers are responding (Linear, trunk docs, Slack, Slite) |
|
/trunk merge |
…cs skill Phase 2 research now mandates that actual source code and PR diffs are the authoritative source — planning docs (Slite specs, PRDs, Slack threads) provide context but code wins on conflicts. Sources audit file must include code-confirmed details, a code-vs-planning-docs diff table, and open questions. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 participant
Summary
Replaces the previous agent-based approach (6 separate agent files) with a single consolidated
write-docsskill that handles the full notes-to-PR documentation workflow.• Skill:
.claude/skills/write-docs/— processes raw notes, Slack threads, and engineer context into polished docs changes with full project tracking• Pipeline: Parse notes → duplicate check → research (Linear + Slite + Slack + docs + code) → sources audit trail → draft docs → branch/PR/Linear → Slack post → HTML review report
• Drafts template:
.claude/drafts/TEMPLATE.mdfor standardized input formatMCP integrations
The skill uses four MCP servers during Phase 2 research:
#team-merge-queue,#team-flaky-tests, and other channels for product discussion, changelogs, and context threadsCode-is-law principle
Planning docs (Slite specs, PRDs, Slack discussions) provide valuable context but frequently diverge from what actually ships. The skill now enforces:
mainoverride planning docs when they conflictThis was validated by running the prometheus-metrics-endpoint draft through research, which found 6 discrepancies between the Slite spec and actual code (missing metric, different queue depth definition, unimplemented features).
Key conventions
<git-username>/<kebab-case-topic>[TRUNK-XXXXX] Short descriptive title.claude/tmp/(gitignored)Validated with 8 documentation PRs
Test plan
/write-docs <draft-file>🤖 Generated with Claude Code