craft

This skill should be used when a command's --refine flag is set, or the user asks to "refine my prompt", "optimize this prompt", "make this request sharper" — rewrites a vague natural-language request into a specific, well-structured prompt using project context, shows before/after, and confirms before the caller proceeds. Replaces the deprecated /craft:refine command.

This skill should be used when the user asks to "release", "create a release", "ship it", "publish a new version", "bump version and release", "cut a release", or mentions releasing to GitHub/npm/PyPI. Orchestrates the full release pipeline from pre-flight checks through GitHub release creation.

ADHD-friendly session and task workflow for craft users — captures context at session end, restores it at session start, picks the next task, breaks through blockers, holds focus on one task, reviews a craft spec, or refines a vague craft prompt. Use when wrapping up or resuming a coding session, when deciding what to work on next (also "what's next", "pick a task for me", "give me something to do"), when stuck or in decision paralysis, when focusing on a single craft task, or when reviewing/refining a craft spec or prompt. The full intent-to-operation map is in the "When to Use" table below.

This skill should be used when the user asks to "init a repo", "set up git", "manage branches", "switch branch", "create a worktree", "list worktrees", "clean merged branches", "sync with remote", "git activity", "git recap", "protect main", "apply branch protection", "bypass protection", "undo a commit", "fix a git mistake", or mentions git lifecycle, worktrees, branch protection, GitHub-side baseline protection, safety rails, or learning git workflows. Covers craft's full git lifecycle — repo init, branch and worktree management, remote sync, status/recap, local and GitHub-side branch protection, and the learning/safety reference docs.

This skill should be used when the user asks "what's my friction", "session insights", "friction report", "what patterns am I hitting", "analyze my sessions", "generate insights report", "aggregate facets", or "show CLAUDE.md suggestions". Aggregates session facet history into a friction/goals report. Formerly bundled with the brainstorm skill (ideation); split out because the two operations share no input or output. Directory name kept as brainstorm-insights for path stability — tests and references/insights.md reference it.

This skill should be used when the user asks to "release multiple formulas", "batch Homebrew update", "coordinate formula releases", "formula dependencies", or needs to manage releases across multiple Homebrew formulas with dependency ordering.

This skill should be used when the user asks to "audit guard", "guard friction", "tune guard", "guard false positives", "fix guard blocking", or mentions branch guard configuration issues. Analyzes branch-guard.sh rules; proposes JSON branch-policy config changes for policy-level false positives, and flags detection-logic bugs (which the flat config schema cannot fix) as needing a code PR instead.

This skill should be used when the user asks to "generate an ORCHESTRATE file", "turn a spec into a plan", "scaffold a feature breakdown", "scaffold a sprint backlog", "plan a sprint" (when a committed backlog/artifact is wanted, not just strategy advice), "generate roadmap artifacts", "create an implementation plan from SPEC", or needs to produce concrete planning artifacts (ORCHESTRATE-*.md, feature breakdowns with task estimates, sprint backlogs, milestone roadmaps). Differs from `project-planner` (high-level strategy/advice) by producing committed, actionable artifacts tied to specs and worktrees.

This skill should be used when the user asks to "audit commands", "check command frontmatter", "audit skills", "check skill standards", "validate command/skill health", or invokes `/craft:code:command-audit` or `/craft:code:skill-standards`. Shared vocabulary + reference bodies for craft's two schema-audit commands — both validate craft's own frontmatter (commands/skills/agents vs `_schema.json`, or `skills/**/SKILL.md` vs Anthropic's authoring standards) and share the same `--format`/`--fix` semantics. Not for dependency or docs-site checks — see `/craft:code:deps-audit`, `/craft:code:deps-check`, `/craft:code:docs-check` instead, which are unrelated generic cross-project tools despite living in the same `commands/code/` directory.

This skill should be used when the user asks to "sync features", "check for new Claude features", "update craft for latest Claude", "what's new in Claude Code", or wants to ensure craft is up-to-date with Claude Code/Desktop capabilities. Chains command-audit and unified release-watch into a prioritized action plan.

This skill should be used when the user asks to "check task status", "view task output", "cancel task", "kill background task", "list running tasks", "wait for task", "show task results", "stop background job", or mentions background task IDs from `/craft:orch`'s `orchestrate-dispatch` mode or other backgrounded commands. Manages the lifecycle of already-launched background tasks — status inspection, output retrieval, and cancellation.

This skill should be used when driving an approved SPEC to completion — "drive this spec to done", "run the orchestrate drive loop", "implement the spec autonomously until tests pass". Owns the reusable body behind /craft:orch:drive — parse-or-derive ORCHESTRATE phases, dispatch file-scoped subagents, and run the authoritative real verify gate.

This skill should be used when the user asks to "create CLAUDE.md", "scaffold CLAUDE.md", "sync CLAUDE.md", "update CLAUDE.md", "audit CLAUDE.md", "fix CLAUDE.md", "optimize CLAUDE.md", "edit CLAUDE.md sections", or otherwise wants to manage the CLAUDE.md lifecycle (init, sync, edit). Covers project-local and global (`~/.claude/CLAUDE.md`) files. For applying suggestions from the /insights report specifically, use the `insights-apply` skill instead.

This skill should be used when the user asks to "analyze a task", "route a command", "what craft command should I use", or describes a development task that needs routing to the appropriate craft workflow. Analyzes natural language task descriptions and maps them to optimal craft command sequences.

This skill should be used when the user asks to "plan a project", "estimate effort", or needs help with task breakdown and project management strategy — NOT for producing a committed planning artifact (feature breakdown, sprint backlog, roadmap file); see `plan-orchestrator` for that. Provides expert guidance on feature planning, estimation, and delivery management.

This skill should be used when the user asks to "brainstorm", "explore ideas", "design a feature", "draft a spec", "capture a spec", or mentions ideation, requirements gathering, spec capture, or brainstorming depth/focus modes. Generates BRAINSTORM/SPEC documents from project + conversation context. Replaces the deprecated /craft:brainstorm command. For session-facet friction or pattern analysis across past sessions, use the brainstorm-insights skill instead.

This skill should be used when the user asks to "pre-flight check", "validate before commit", "validate before PR", "validate before deploy", "is this ready to ship", "check readiness", "run pre-flight", "validate project state", or wants context-aware validation across commit/PR/release/deploy boundaries. Orchestrates universal validators (lint, tests, types, version sync, stale refs, docs, hook conflicts) and supports generating new custom validators.

This skill should be used when the user asks to "apply insights", "insights to rules", "update rules from insights", "apply suggestions", or mentions updating CLAUDE.md from insights data. Extracts suggestions from the /insights report and applies them to the global CLAUDE.md via the sync pipeline.

This skill should be used when the user asks to "publish to PyPI", "generate an install script", "curl install", "publish to Claude Code marketplace", "create marketplace.json", "PyPI trusted publishing", "private plugin", "plugin drift", "pin refresh", or needs help with non-Homebrew distribution channels (PyPI, curl-based installers, Claude Code marketplace). Covers Python package publishing, GitHub-release curl installers, Claude Code plugin marketplace listings (public and private), post-release pin-refresh, and drift detection.

Reference templates for orchestrator-v2 agent error handling, retry/backoff, circuit breaker, escalation, and execution timeline display. Load when the orchestrator hits an agent failure, needs to show a retry/timeout/escalation report, or the user asks for a `timeline` view. NOT needed for normal happy-path orchestration — only for error recovery and timeline display.

This skill should be used when executing a coded, fixed-control-flow workflow — "run the workflow engine", "execute this WORKFLOW yaml", "run the coded orchestration", decompose→cover→verify→synthesize shapes. Owns the reusable body behind /craft:orch:workflow — compile a WORKFLOW definition to a deterministic wave plan, dispatch file-scoped agents wave by wave under a run-wide semaphore, structurally gate every output, and run a first-class verify gate.

This skill should be used when the user asks to "grill", "interrogate", "stress-test a spec/plan", "adversarially review a proposal", or invokes /craft:grill. Convergent counterpart to brainstorm — interrogates a spec/plan/topic one question at a time to surface gaps, contradictions, and unresolved dependencies before implementation, then captures a durable GRILL-*.md decision ledger that feeds /craft:plan → /do. For GENERATING options (divergent ideation), use the brainstorm skill instead.

This skill should be used when the user asks to "generate tests", "create CLI tests", "add dogfooding tests", "create plugin validation tests", or needs automated and interactive test suites for a project. Generates dogfooding test suites (automated + interactive) for any project type.

This skill should be used when the user asks to "plan test strategy", "improve test coverage", "fix flaky tests", "optimize test performance", or needs guidance on testing infrastructure and quality assurance. Provides expert guidance on test strategy design, coverage analysis, and test quality improvement.

This skill should be used when the user asks to "audit my plugins", "check for plugin duplicates", "plugin collision check", "find duplicate skills across plugins", "which plugins overlap", or wants to know if an installed Claude Code plugin duplicates or shadows another plugin's commands/skills. Diffs enabled plugins' actual command/skill surface against each other and flags cross-namespace name collisions — e.g. a bare `workflow:brainstorm` skill in one plugin vs. `craft:brainstorm` in another. Read-only — reports findings, never disables or uninstalls a plugin itself. Do not confuse with guard-audit (branch-guard.sh rule tuning) or command-skill-token-efficiency (command-vs-skill placement within a single plugin) — this skill compares surfaces ACROSS installed plugins.

This skill should be used when the user asks to "save session", "resume session", "continue where I left off", "session history", or needs orchestrator session state persistence including save, load, resume, and history management.

This skill should be used when the user asks to "plan distribution", "how should I distribute this", "choose a package manager", "distribution strategy", or needs to select and prioritize distribution channels for a software project. Recommends optimal distribution channels based on project type and target audience.

This skill should be used when the user asks to "create a Homebrew formula", "fix brew audit errors", "write a formula", "Homebrew best practices", or needs help with Homebrew formula syntax, dependencies, and troubleshooting. Expert knowledge of Homebrew formula creation and maintenance.

This skill should be used when the user asks to "set up Homebrew automation", "homebrew setup", "automate formula updates", "configure Homebrew workflow", or needs end-to-end Homebrew formula automation from detection through workflow generation.

This skill should be used when the user asks to "create Homebrew release workflow", "automate formula updates with GitHub Actions", "configure tap CI", or needs GitHub Actions workflows for automated Homebrew formula updates and releases.

This skill should be used when the user is writing, editing, resizing, or reviewing a craft command (commands/**/*.md), skill (skills/**/SKILL.md), or agent (agents/*.md) file — including "add a new command for X", "this command is getting long", "should this be a skill instead", "make /craft:do leaner", "reduce token usage in this command", "audit command body size", or "is this skill too big". Also use it before finalizing any deprecated-true/replaced-by thin-shim split (the ADR-002 pattern). Checks whether content belongs in a command (invocation-specific — flags, frontmatter) versus a skill (procedure — the actual logic, which loads conditionally instead of every invocation), and runs a quantitative line-ratio check via scripts/audit-deprecated-commands.py --pair. Do not confuse with skill-standards' format/frontmatter compliance check (a different concern — that audits style rules, this audits token-cost structure) or guard-audit (tunes branch-guard rules, doesn't touch command/skill content).

Common PostToolUse/PreToolUse hook templates for quality gates. Provides ready-to-install JSON blocks for MkDocs strict mode, linting, and other automated checks, with setup instructions for each.

This skill should be used when the user asks to "detect project type", "what kind of project is this", "generate CI workflow", "set up CI", or needs to identify build tools, test frameworks, and CI requirements. Smart detection of project types, build tools, and CI requirements for automated workflow generation.

Automate changelog generation from commits, PRs, and releases following Keep a Changelog format. Use when setting up release workflows, generating release notes, or standardizing commit conventions.

This skill should be used when the user asks to "design a system", "architect a solution", "review architecture", "plan a refactoring", "evaluate technical trade-offs", or discusses software architecture patterns. Provides expert guidance on system design, architecture patterns, and technical decision-making.

This skill should be used when the user asks to "design an API", "plan database schema", "set up authentication", "design backend architecture", or discusses backend patterns and infrastructure. Provides pragmatic backend design guidance following "solid indie" principles.

This skill should be used when the user asks to "set up deployment", "configure CI/CD", "create a Dockerfile", "choose a hosting platform", or discusses deployment and infrastructure decisions. Provides pragmatic DevOps guidance for indie developers.

This skill should be used when the user asks to "design a UI", "plan component architecture", "improve accessibility", "optimize frontend performance", or discusses UI/UX patterns. Provides pragmatic frontend design guidance with ADHD-friendly patterns.

This skill should be used when the user asks to "switch mode", "use debug mode", "optimize mode", "release mode", or mentions execution modes for craft commands. Manages craft plugin execution modes (default, debug, optimize, release) for different use cases.

Write and maintain Architecture Decision Records (ADRs) following best practices for technical decision documentation. Use when documenting significant technical decisions, reviewing past architectural choices, or establishing decision processes.