chore(claude): add Claude Code skills for docs2#9
Draft
samgutentag wants to merge 4 commits into
Draft
Conversation
Adds Claude Code configuration for the Mintlify-based docs site:
- 1 subagent: doc-researcher (Sonnet 4.6, reads Linear/PRs/docs)
- 6 skills: outline-docs, write-docs, review-docs, draft-docs,
verify-docs-pr, docs-review
- drafts/TEMPLATE.md as scaffold for new draft notes
- settings.json with curated shared permissions (settings.local.json
gitignored for per-machine overrides)
- README.md documenting each skill, agent, and the gutils relationship
Skills are ported from trunk-io/docs and ~/Developer/gutils/claude-code
with Mintlify adaptations:
- Filenames .md -> .mdx for content references
- summary.md (Docusaurus nav) -> docs.json (Mintlify nav)
- .gitbook.yaml redirect audit -> docs.json redirects audit
- GitBook {% hint %} blocks -> Mintlify <Note>/<Info>/<Tip>/<Warning>
- GitBook [page](path.md "mention") -> standard MDX [page](/path)
- trunk-io/docs repo refs -> trunk-io/docs2 (verify-docs-pr,
write-docs/OVERLAP-CHECK.md, write-docs/README.md)
- draft-docs writes directly to .claude/drafts/ (no copy step)
- Removed historical verify-docs-pr/PLAN.md (executed migration plan)
- Fixed duplicate Question block in outline-docs Phase 1
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…/docs-review -> docs-research)
Removes:
- skills/draft-docs/ — write-docs already accepts raw trunk2 refs
- skills/review-docs/ — drop pre-PR local-diff review (rely on
trunk check + PR review instead)
- skills/docs-review/ — fold into the new docs-research skill
- skills/verify-docs-pr/
DESIGN.md — historical migration artifact
Adds:
- skills/docs-research/ — upstream audit skill that runs before
/outline-docs or /write-docs. Identifies
gaps in existing coverage, recommends
placement for new content, prevents
duplicated effort.
Updates:
- .claude/README.md — new mental model (research / write / verify),
skill reference rewritten, drafts section
clarified as optional batch scaffolding
- .claude/settings.json — Skill() permissions match new skill set
- skills/outline-docs/SKILL.md — post-checklist no longer references
/review-docs; points to trunk check
and normal PR review flow
Final skill set: docs-research, outline-docs, write-docs, verify-docs-pr,
plus the doc-researcher subagent.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The OVERLAP-CHECK Phase 0 in write-docs only checked GitHub for existing/conflicting docs PRs. Adds Step 3: search Linear for an existing planning ticket using the same Trunk Engineering team ID the DevRel scanner uses, ask the user before duplicating. Closes the gap surfaced by mapping the daily DevRel scanner against the consolidated docs2 skill set: scheduled automation already dedups against Linear in its own pipeline, but a manual /write-docs invocation could still file a duplicate ticket. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Reflects the OVERLAP-CHECK Phase 0 addition from commit 4302521. Phase 5 also mentions linking the existing ticket from Phase 0 rather than always creating a new one. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds
.claude/to docs2 — Claude Code configuration for the new Mintlify docs site. Ported fromtrunk-io/docs(Docusaurus) with Mintlify adaptations, then consolidated for clarity.Final skill set: 4 skills + 1 agent.
/docs-research/outline-docs.mdxpage from scratch/write-docs/verify-docs-prPlus the
doc-researchersubagent (Sonnet 4.6) for read-only context fetching.Mental model: research → write → verify.
What's in this PR
Two commits:
cad58f0— initial scaffold (+2,332lines). Copied 6 skills + 1 agent fromtrunk-io/docs/.claude/andgutils/claude-code/skills/trunk/, applied Mintlify adaptations:.md→.mdxfor content refssummary.md→docs.jsonfor nav.gitbook.yamlredirect audit →docs.jsonredirect audit{% hint %}→ Mintlify<Note>/<Info>/<Tip>/<Warning>/<Check>[page](path.md "mention")→ standard MDX[page](/path)trunk-io/docsrepo refs →trunk-io/docs224838bc— consolidation (+160 / -880net). After review, the original 6-skill set had naming overlap (review-docsvs.docs-review) and redundancy (draft-docsvs.write-docsdirect refs). Consolidated:draft-docs—write-docsalready accepts raw trunk2 refsreview-docs— replaced bytrunk check+ normal PR reviewdocs-review→docs-research— refocused on upstream audits (gaps, placement, dedup) instead of post-hoc quality checksFiles added
.claude/agents/doc-researcher.md— read-only research subagent.claude/skills/{docs-research,outline-docs,write-docs,verify-docs-pr}/.claude/drafts/TEMPLATE.md— scaffold for optional batch-mode drafts.claude/settings.json— curated shared permissions baseline.claude/.gitignore— excludessettings.local.jsonandtmp/.claude/README.md— agents/skills/drafts explainer + skill referenceTest plan
/docs-research,/outline-docs,/write-docs,/verify-docs-pr)/docs-research "merge queue health"— confirm it readsdocs.json, returns a structured report with existing coverage, gaps, and placement suggestions/outline-docswith a fake feature — confirm it scaffolds an.mdx(not.md) file and updatesdocs.jsonnav/write-docs <trunk2-PR-number>end-to-end on a small feature — confirm it produces a draft PR againsttrunk-io/docs2(nottrunk-io/docs)/verify-docs-pr <pr-number>on this PR or a future one — confirm it queriestrunk-io/docs2and posts a verdict commentdoc-researcheragent is discoverable via the Agent tool and returns the expected research-brief shape🤖 Generated with Claude Code