Skills

Skills

Thatch installs SKILL.md files that give the agent task-specific workflows. All skill content lives in artifacts/skills/*.md and is loaded by src/skills.ts and installed to a host-specific directory. See mcp-parity.md for which skills each host gets.

Naming convention

All plugin skills use the thatch- prefix. This brands them as part of the thatch plugin and makes them easy to identify in the skills directory. The cleanupStaleSkills function uses this prefix as its namespace: any thatch-* directory not in the current install set is deleted on install.

Skill file format

Each skill is a single SKILL.md with YAML frontmatter:

---
name: thatch-fact-extractor
description: Extract durable project facts ... Use when ...
---

<role and instructions>

• name must match the directory name (<skillsDir>/<name>/SKILL.md).
• description drives when the agent loads the skill (opencode, Claude Code, and Cursor all auto-discover skills and use the description for relevance).

The skills

Shared — installed everywhere; no sub-agents required:

Skill	Role
thatch-fact-extractor	Turn buffered tool interactions into thatch_memory_remember calls.
thatch-dedup-classifier	Classify and resolve find_duplicates pairs/clusters.
thatch-project-primer	Investigate a new project and write foundational memories.
thatch-review-pedantic	Mechanical correctness: spelling, naming, doc accuracy, specs, stale artifacts.
thatch-review-acceptance	Behavioral/product review: UX, behavioral delta, integration effects.
thatch-review-state-flow	Data flow and contracts: module boundaries, implicit FSMs, error propagation.
thatch-review-economy	Design simplicity and maintainability: is the complexity earned? Evaluates both the overall change design (forest) and individual touch points (trees) for unnecessary complexity, redundancy, and simpler available alternatives.
thatch-review-no-slop	AI writing anti-patterns: change narration, fourth-wall breaks, em dashes, filler.
thatch-review-breadcrumbs	Comment narrative: do comments form a coherent outline of behavior?
thatch-review-mark-and-sweep	Mechanical change completeness: whole-repo sweep for stragglers after renames, flag removals, API substitutions.
thatch-review-highlights	Positive finding detection: notably clever solutions, cleanup done along the way, documentation that helps. Medium-high bar against generic praise.
thatch-review-technique	Technique lens: teaching-grade notes on unseen helpers/internal packages, companion techniques, house patterns, test-craft, API-shape principles, next-reader discoverability. Informational only, verified citations, never blocking.
thatch-review-synthesizer	Verify specialist findings against code, dedupe, classify, calibrate severity. Starts the final report with a workflow-change preface, then cross-references findings against prior review comments when a follow-up round register is provided.
thatch-review-context	Gather project/feature context (PR descriptions, git archaeology, ticket references, linked docs/tickets followed from the change, memory) before fan-out. Prevents false positives about intentionally deferred work, and checks whether main moved past the merge-base touching the same paths (staleness signal for the synthesizer). Also fetches prior review comments on a connected PR/MR for follow-up-round detection and builds a register with preliminary addressed-check status per comment.
thatch-code-archaeology	Investigate an existing feature, debug an unfamiliar area, or begin a new ticket. Explores the code base from multiple angles (data model, state flow, git history, sibling features, skeletons) before proposing changes. The research skill; pair with thatch-coding-workflow.
thatch-review-followup	Alternate entrypoint for follow-up review rounds. Verifies whether the author's responses and code changes since your last review round adequately addressed your prior findings, offers to reply on resolved items, then optionally re-runs the full structured review.
thatch-change-walkthrough	Explain a change to the user as a teaching walkthrough: resolve the delta, research each affected workflow at the merge-base, teach current behavior, then overlay the modifications with file:line citations and analogies.
thatch-code-walkthrough	Explain a feature, module, or workflow to the user as a teaching walkthrough: identify the code area (optionally from a branch or PR), research how it works, teach it with file:line citations and analogies, list the key files.
thatch-session-reflection	End-of-session memory recording (project, user, tools, self).
thatch-coding-workflow	Plan and execute code changes with a task-list-driven workflow. Use when implementing features, fixing bugs, or making multi-file changes.
thatch-plan-refinement	Refine a plan before implementing it: fresh-context reviewer rounds until consensus, with an optional deep-mode lens fan-out (reuse, alternatives, hidden problems, safe-to-modify, archaeology). The generic core loop.
thatch-refine	Classify the project (audience, lifecycle, surface) and refine a plan under that type's requirements. Entry point for the thatch-refine-* family; also the /thatch/refine command.
thatch-refine-team-app	Refinement deltas for multi-developer team codebases: consistency outranks cleverness, intent breadcrumbs are deliverables, pre-mortem and safe-to-modify lenses dominate.
thatch-refine-personal	Refinement deltas for solo projects with no downstream consumers: relaxed coordination, cleverness and experimentation welcome, premise verification stays honest.
thatch-refine-shared-lib	Refinement deltas for changes touching a library's API surface: flexible on input, strict on output, keep special cases out of the API, never foreclose caller options, docs are a deliverable.
thatch-refine-spike	Refinement deltas for throwaway prototypes: skip the loop, verify only the premises the experiment's conclusion depends on, state the question and the time box.
thatch-refine-infra	Refinement deltas for CI, Terraform, and k8s changes: blast radius across pipelines and environments, rollback plan and staged verification are mandatory, pattern-following is near-absolute.
thatch-refine-oss-contribution	Refinement deltas for PRs to repos you do not maintain: the maintainer's design authority governs, minimal diff, upstream discussion gates significant design work.
thatch-pr-description	Draft PR descriptions with SYNOPSIS / PURPOSE / DESCRIPTION / WALK-THROUGH / NOTES, project-context research, clarity checks, and bold+italic emphasis for scanning.
thatch-ticket-description	Draft ticket/issue descriptions with clear sections, project-context research, clarity checks, and bold+italic emphasis for scanning.
thatch-split-overlarge-pr	Split already-completed work from an overlarge PR into human-reviewable, release-safe PRs targeting main.
thatch-review-response	Author-side review response: triage findings, fix bugs one by one, reply on each thread, post a top-level summary comment.
thatch-memory-verify	Fact-check a single memory against the current codebase and correct stale claims. Uses git archaeology to preserve historical context when changes were intentional.
thatch-knowledge-export	Compile everything thatch knows about a topic into a curated markdown file for knowledge transfer. Searches across stores, curates out personal noise, fact-checks code-related memories via thatch-memory-verify.
thatch-clear-writing	Prose rules for any human-facing text not covered by a dedicated writing skill: PR and ticket comments, documentation, plans, reports, and chat replies. Clarity over compression; dedicated skills win when loaded.

opencode-only — the coordinator needs sub-agent support:

Skill	Role
thatch-code-review	Resolve review target (incl. VCS detection and connected PR/MR lookup for follow-up round detection), gather project context, research affected workflows, estimate complexity, partition, dispatch the review specialists in parallel, synthesize with a workflow-change preface and prior-comment cross-reference.

REVIEW_COMMON

The seven problem-finding review specialists share a framework interpolated via ${REVIEW_COMMON} (the eighth specialist, highlights, finds positive things and uses its own structure):

• Static analysis only — no running tests/linters/compilers.
• Scope gathering — resolve the git range, git diff --stat, read changed files in full for context.
• Runtime model — CLI/long-lived server/library/batch — this determines which bug classes are realistic.
• Reachability gate — every finding must describe a concrete normal-usage trigger; "the code allows this" is not enough.
• Intent verification — trace callers, check git history, and thatch_memory_recall for design rationale before flagging a behavior as a bug.
• Project context awareness — if a context brief is provided (from the coordinator or from loading thatch-review-context), use it to avoid false positives about intentionally deferred work.
• Workflow context awareness — if a workflow guide is provided (from the coordinator or from loading thatch-code-archaeology), use it to understand the purpose and evolution of the code, distinguishing intentional behavior and long-standing design decisions from new issues.
• TODO ($ticket) markers — recognize TODO ($TICKET-ID): ... as legitimate breadcrumbs for deferred work, not stale artifacts. Flag only if the referenced ticket is closed or merged.
• Output format — [SEVERITY] [CATEGORY] file:line with finding, evidence (quoted), trigger, reachability, source of truth, producer chain, provenance.
• Wording — findings are prose for humans, not shorthand: one idea per sentence, no method names as verbs, one sentence per hop for producer chains.

The synthesizer reuses the same verification rigor but has its own structure (it does not interpolate REVIEW_COMMON).

The two arrays

const SHARED_SKILLS: SkillDef[] = [ /* all shared skills above */ ];
const OPENCODE_ONLY_SKILLS: SkillDef[] = [ /* code-review coordinator */ ];

installSkills(skillsDir, skills?) defaults to SHARED_SKILLS. The opencode plugin passes [...SHARED_SKILLS, ...OPENCODE_ONLY_SKILLS]; thatch setup --claude and --cursor pass only the shared set.

Install mechanics

• Location: $XDG_CONFIG_HOME/opencode/skills (opencode); scope-dependent for MCP hosts — the repo's .claude/skills/ or .cursor/skills/ for project-local thatch setup, the host config dirs ($CLAUDE_CONFIG_DIR/skills, ~/.cursor/skills) for --global.
• Trigger: opencode installs at plugin init; Claude Code/Cursor install via thatch setup.
• Drift detection: installSkills only writes when the on-disk content differs from the definition. This is how skill improvements ship with new versions without users manually deleting files.
• Stale cleanup: before installing, installSkills removes stale skill directories. Any thatch-* directory not in the current install set is deleted (the thatch- prefix is our namespace). Non-prefixed directories are never touched: the v0.1.27 rename migration (pr-description, ticket-description, split-overlarge-pr) cleaned up old installs only through a version window that closed with v0.1.35, after which those names are fair game for third parties and the cleanup no longer runs. Users upgrading from before v0.1.27 delete the old directories manually.
• Idempotent: re-running init or setup overwrites drifted content but leaves unrelated (non-thatch-*) skill files alone.

Adding a skill

1. Write artifacts/skills/thatch-<name>.md with YAML frontmatter. If it's a problem-finding review specialist, include ${REVIEW_COMMON} (interpolated from artifacts/skills/common.md). The highlights specialist does not use REVIEW_COMMON — it finds positive things, not problems, so the problem-finding framework does not apply.
2. Add the skill name to the names array in loadSharedSkills() (or loadOpencodeOnlySkills() if sub-agents are needed). The loader in src/skills.ts reads .md files at init.
3. If the skill name appears in a tool's workflow (e.g. thatch-fact-extractor), update src/prompts.ts.
4. Run mise run check — tests verify counts; installSkills picks up new files on next init.

Memory review skills in practice

• Quick single lens: load any specialist directly and point it at a branch.
• Full review on opencode: load thatch-code-review — it gathers project context, researches affected workflows, dispatches all review specialists in parallel (with both the context brief and workflow guide injected into each briefing), then synthesizes a report that starts with the workflow changes before findings.
• Full review on Claude Code/Cursor: run each specialist in sequence, then run thatch-review-synthesizer to verify and aggregate.
• Follow-up round (re-review): load thatch-review-followup when the author has responded or pushed changes after your initial review. It verifies whether your prior findings were adequately addressed, offers to reply on resolved items, then optionally hands off to thatch-code-review for a fresh round.
• Author-side review response: load thatch-review-response when responding to review comments on your own PR. It triages findings, collapses comments sharing a root cause, fixes bugs one by one with the user, drafts per-thread replies, and posts a top-level summary comment. Works on all hosts (no sub-agents required).

The coordinator is the only skill that can't be used without sub-agents; that's why it lives in OPENCODE_ONLY_SKILLS.