Claude Code Skills Collection

Custom skills and agents for Claude Code that enhance codebase research, context management, and implementation planning workflows.

New to this workflow? See the Workflow Overview for a step-by-step guide.

Installing? This repo ships as the devflow Claude Code plugin — see Installation and Plugin Distribution.

Built on Claude Code Task Tools

This skill collection uses Claude Code's native Task tools for progress tracking.

Progress tracking is handled entirely through Claude Code's built-in Task system:

Benefits:

• Persistent - Tasks survive session restarts
• Cross-session - Share progress across multiple terminals
• Dependency tracking - Blocked tasks visible, execute in order
• No file pollution - Progress tracked in memory, not plan files

Plans remain pure specification documents. See Progress Tracking for details.

Claude Code 2.1.x Feature Alignment

This collection uses modern Claude Code skill features (v2.1.16+):

Never add context: fork to an interactive skill. A forked skill runs in a subagent with no access to the conversation history, and since Claude Code v2.1.218 it is backgrounded by default — so a skill that asks the user questions and waits for answers (brainstorm) simply never reaches the user. agent: Explore compounds it: that agent type is read-only, so the skill cannot write its output document either. tests/test-interactive-skills.sh guards this.

Argument Substitution

Skills support the new argument syntax:

• $0, $1, $2 - Positional arguments
• $ARGUMENTS - All arguments
• ${CLAUDE_SESSION_ID} - Session tracking

Example: /implement-plan docs/plans/my-feature.md passes the path as $0.

Implementation Workflow

The core workflow for implementing features follows this hierarchy:

                              ┌─────────────────┐
                              │   brainstorm    │
                              │   (ideation)    │
                              └────────┬────────┘
                                       │
                           ┌───────────┴───────────┐
                           ▼                       ▼
                  ┌─────────────────┐   ┌──────────────────┐
                  │      adr        │   │   user-story     │
                  │  (decisions)    │   │ (requirements)   │
                  └────────┬────────┘   └──────────┬───────┘
                           └────────────┬──────────┘
                                       │
                                       ▼
                              ┌─────────────────┐
                              │  create-plan    │
                              │ (spec → phases) │
                              └────────┬────────┘
                                       │
                                       ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│                              implement-plan                                   │
│                           (orchestrates all phases)                           │
│                                                                               │
│   ┌─────────────┐    ┌─────────────┐    ┌─────────────┐                      │
│   │   Phase 1   │───▶│   Phase 2   │───▶│   Phase N   │───▶ Complete        │
│   └──────┬──────┘    └──────┬──────┘    └──────┬──────┘                      │
│          │                  │                  │                              │
│          ▼                  ▼                  ▼                              │
│   ┌─────────────────────────────────────────────────────────────────────┐    │
│   │                    implement-phase (per phase)                       │    │
│   │  ┌────────────────────────────────────────────────────────────┐     │    │
│   │  │ Step 1: Implementation (subagents) [TDD mode: tests first] │     │    │
│   │  │ Step 2: verification-loop (6-phase exit conditions) ─────┐│     │    │
│   │  │ Step 3: Integration Testing (API/UI via Playwright)      ││     │    │
│   │  │ Step 4: code-review ─────────────────────────────────────┼┼──┐  │    │
│   │  │         ├─► security-review (optional OWASP audit) ──────┼┼──┼─┐│    │
│   │  │ Step 5: ADR Compliance ──────────────────────────────────┼┼──┼─┼┤    │
│   │  │ Step 6: Plan Sync                                        ││  │ ││    │
│   │  │ Step 7: Prompt Archival                                  ││  │ ││    │
│   │  │ Step 8: Completion Report                                ││  │ ││    │
│   │  └──────────────────────────────────────────────────────────┼┼──┼─┼┘    │
│   └─────────────────────────────────────────────────────────────┼┼──┼─┼─────┘
│                                                                 ││  │ │      │
│         ┌───────────────────────────────────────────────────────┘│  │ │      │
│         │              ┌─────────────────────────────────────────┘  │ │      │
│         │              │              ┌──────────────────────────────┘ │      │
│         │              │              │              ┌─────────────────┘      │
│         ▼              ▼              ▼              ▼                        │
│   ┌───────────┐  ┌───────────┐  ┌───────────┐  ┌─────────────────┐           │
│   │verification│  │code-review│  │security-  │  │      adr        │           │
│   │   -loop   │  │           │  │  review   │  │                 │           │
│   └───────────┘  └───────────┘  └───────────┘  └─────────────────┘           │
│    (default)                      (optional)                                  │
└───────────────────────────────────────────────────────────────────────────────┘
                                       │
                                       ▼
                              ┌─────────────────┐
                              │   e2e-testing   │
                              │  (validation)   │
                              └────────┬────────┘
                                       │
                                       ▼
                        ┌──────────────────────────┐
                        │   continuous-learning    │
                        │ (extract session patterns)│
                        └──────────────────────────┘

Workflow Stages

Skills

Skills are invoked via the Skill tool or /skill-name shorthand.

Planning & Implementation

Quality & Documentation

Research & Context

Learning & Optimization

Development

Media & Content

Pipeline (Issue → Merge)

Overview page: open skills/ship-issue/pipeline.html in a browser for a one-page tour — the skill, its five agents, and the full stage-flow diagram with model-tier colour-coding (self-contained, no dependencies).

Agents

Agents are specialized subagents launched with the Agent tool. When the collection is installed as a plugin they are named devflow:<agent>.

ship-issue pipeline agents

Each agent pins its model in frontmatter — the tier is part of the contract, never switched mid-task (prompt caches are model-scoped; ADR-0007). A fix cycle is always a fresh task on the same tier, never a resumed task on a different model.

Installation

This repository is distributed exclusively as a Claude Code plugin named devflow, published through a marketplace named mhylle. Inside Claude Code:

/plugin marketplace add mhylle/claude-skills-collection
/plugin install devflow@mhylle

Then /reload-plugins (or restart) if the install summary asks for it.

Plugin skills are namespaced, so every skill is invoked as /devflow:<skill>:

/devflow:brainstorm
/devflow:create-plan
/devflow:implement-plan

Nothing is copied into ~/.claude/ — the plugin lives in Claude Code's plugin cache, carries a version, and updates in place:

/plugin marketplace update mhylle

To remove it: /plugin uninstall devflow.

See Plugin Distribution for the manifest layout, versioning, publishing, and local development.

Migrating from the old install script

Earlier versions shipped an install.sh that copied skills, agents, and hooks into ~/.claude/. It is gone (ADR-0011).

Those copies do not disappear on their own, and plugin skills do not override same-named personal skills — so until you remove them you will have both /brainstorm and /devflow:brainstorm pointing at two copies that drift apart, with Claude free to auto-invoke either. Remove the copies once, after installing the plugin:

# from a checkout of this repo
for s in $(ls skills); do rm -rf "$HOME/.claude/skills/$s"; done
for a in agents/*.md; do rm -f "$HOME/.claude/agents/$(basename "$a")"; done

~/.claude/hooks.json is your own user configuration, not a copy of this repo's file. The old script overwrote it (leaving hooks.json.backup); the plugin no longer touches it. Review it by hand and delete only the entries you recognise from this collection.

What the Plugin Ships

Skills, agents, and these hooks — all discovered automatically from the plugin's default component locations (skills/, agents/, hooks/hooks.json).

Hooks (automatic behaviors):

/devflow:strategic-compact is invoked on demand rather than by a hook — see ADR-0011.

HUD (function hooks, hooks/register.tsx): a progress band above the prompt and a /hud pane for TaskTracker phases (sub-tasks, acceptance criteria, booked time, running agents, the last build or test result), plus an orchestrator guard that refuses main-thread file edits while a phase lead runs, an in-flight reminder while agents work, a heartbeat while agents run, and alarms for failed or missing test projects. See the devflow HUD guide.

CLAUDE.md Integration

Enforce the skill workflow in your projects using the init script:

# Initialize a project with workflow enforcement
./init-workflow.sh ~/projects/myapp           # Standard level (recommended)
./init-workflow.sh ~/projects/myapp minimal   # Lightweight reminder
./init-workflow.sh ~/projects/myapp strict    # Full enforcement

# Or from within your project
cd ~/projects/myapp && /path/to/init-workflow.sh .

This script:

• Creates docs/plans/, docs/brainstorms/, docs/user-stories/, docs/adr/, logs/ directories
• Appends workflow rules to existing CLAUDE.md (non-destructive)
• Creates new CLAUDE.md from template if none exists
• Backs up existing CLAUDE.md before modifying

Enforcement levels:

Resources:

• CLAUDE.md Snippets - All modular snippets for manual customization
• Enforcement Rules - Complete rule reference
• CLAUDE.md Template - Full project template

Ready to start? Check out the Workflow Overview for a complete guide.

Usage Examples

Full Implementation Workflow

# 1. Brainstorm the idea
/brainstorm
> "I want to add user authentication to the app"

# 2. Define requirements (parallel with ADRs)
/user-story docs/brainstorms/2026-02-17-user-auth.md
> Creates docs/user-stories/EPIC-01-user-auth.md + INDEX.md

# 3. Create a plan
/create-plan
> Creates docs/plans/auth-implementation.md

# 4. Implement the plan
/implement-plan docs/plans/auth-implementation.md
> Executes phases with quality gates

# 5. Run E2E tests
/e2e-testing run

Quick Code Review

/code-review
> Review the changes in src/auth/

Adversarial Review (Before Merge)

/adversarial-reviewer --diff main...HEAD
> Spawns Saboteur, New Hire, and Security Auditor subagents in parallel.
> Each must find at least one issue. Findings caught by 2+ personas are
> promoted one severity level. Produces BLOCK / CONCERNS / CLEAN verdict.

Use this when /code-review came back clean too easily, or before merging PRs with no human reviewer. The subagent isolation is what breaks the self-review trap — each persona reviews with no knowledge of prior conclusions.

Adversarial Codebase Audit (Inherited / Unfamiliar Repo)

/adversarial-reviewer --codebase
/adversarial-reviewer --codebase src/api
> Maps the codebase (structure, entry points, churn, tests), then each
> persona strategically deep-reads 5-10 files chosen by its own lens —
> Saboteur picks churning/stateful files, New Hire picks entry-point and
> knowledge-silo files, Security Auditor picks trust boundaries. Produces
> HIGH-RISK / MEDIUM-RISK / LOW-RISK verdict plus a "most-concerning area"
> summary.

Use this for onboarding audits, inherited-repo assessments, and periodic tech-debt checks. Findings are strategic-depth, not exhaustive — intentionally, because exhaustive whole-repo review from three personas isn't feasible.

Comprehensive Codebase Audit (Long-Running, Full Coverage)

/codebase-audit
/codebase-audit src/                 # scope to subtree
/codebase-audit --resume             # pick up from crash / previous session
/codebase-audit --only api           # re-review just one partition
> Maps repo → proposes partition plan → STOPS for user approval →
> sequentially runs /adversarial-reviewer --codebase on each partition →
> synthesizes systemic findings → produces docs/audits/.../REPORT.md with
> risk register, architectural themes, and a remediation roadmap.

This is a multi-step orchestrator that delegates each partition review to the adversarial-reviewer skill. Expect 200K-500K tokens and 30-60 minutes for a typical ~500-file repo. Resumable — losing your session mid-audit doesn't lose the work. Pair with /code-quality-audit for the quantitative complement (coverage, complexity, cycles, mutation).

Document a Decision

/adr
> Document the decision to use JWT instead of sessions

Quality Gates (implement-phase)

Each phase passes through these gates:

┌─────────────────────────────────────────────────────────────────┐
│                       PHASE PIPELINE                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌────────────────────┐                                         │
│  │ 1. Implementation   │ ─── Subagents write code               │
│  │    [TDD optional]   │     (tests first if tdd_mode: true)    │
│  └─────────┬──────────┘                                         │
│            │ PASS                                                │
│            ▼                                                     │
│  ┌────────────────────┐                                         │
│  │ 2. verification-loop│ ─── 6-phase exit conditions (default)  │
│  │    Build,Type,Lint, │     Build → Type → Lint → Test →       │
│  │    Test,Security,   │     Security → Diff                    │
│  │    Diff             │                                         │
│  └─────────┬──────────┘                                         │
│            │ ALL 6 PASS                                          │
│            ▼                                                     │
│  ┌────────────────────┐                                         │
│  │ 3. Integration Test │ ─── Claude tests via API/Playwright    │
│  └─────────┬──────────┘                                         │
│            │ PASS                                                │
│            ▼                                                     │
│  ┌────────────────────┐     ┌───────────────────┐               │
│  │ 4. Code Review      │────▶│ security-review   │ (optional)   │
│  │    SRP, Patterns    │     │ OWASP audit       │               │
│  └─────────┬──────────┘     └───────────────────┘               │
│            │ PASS                                                │
│            ▼                                                     │
│  ┌────────────────────┐                                         │
│  │ 5. ADR Compliance   │ ─── Follow & document decisions        │
│  └─────────┬──────────┘                                         │
│            │ PASS                                                │
│            ▼                                                     │
│  ┌────────────────────┐                                         │
│  │ 6. Plan Sync        │ ─── Verify work items completed        │
│  └─────────┬──────────┘                                         │
│            │ PASS                                                │
│            ▼                                                     │
│  ┌────────────────────┐                                         │
│  │ 7. Prompt Archive   │ ─── Move prompt to completed/          │
│  └─────────┬──────────┘                                         │
│            │ PASS                                                │
│            ▼                                                     │
│  ┌────────────────────┐                                         │
│  │ 8. Complete         │ ─── Report to orchestrator             │
│  └────────────────────┘                                         │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Mandatory Exit Conditions (non-negotiable):

• verification-loop must PASS (all 6 phases: Build, Type, Lint, Test, Security, Diff)
• Code review must return PASS — every recommendation is fixed; only informational NOTEs may remain
• All recommendations must be fixed - recommendations are blocking, not optional
• ADR compliance must PASS

Optional steps can be enabled via plan metadata:

• security_review: true - Adds OWASP security audit step after code review
• tdd_mode: true - Enforces RED → GREEN → REFACTOR cycle with 80% coverage

Prompt Integration

The prompt-generator skill creates phase prompts that are automatically discovered:

prompt-generator → docs/prompts/phase-N-name.md
                          ↓
implement-plan discovers prompts automatically
                          ↓
implement-phase uses prompt for orchestration
                          ↓
On completion → docs/prompts/completed/

Orchestrator Pattern

Critical: implement-plan and implement-phase are ORCHESTRATORS. They never write code directly.

implement-plan (ORCHESTRATOR)
    │   ⛔ NEVER writes code
    │   ⛔ NEVER uses Write/Edit tools
    │
    └── implement-phase (ORCHESTRATOR)
            │   ⛔ NEVER writes code
            │
            └── Subagents (DO the work)
                    ✅ Write code
                    ✅ Create files
                    ✅ Run tests

Subagents must be concise - return only STATUS, FILES, ERRORS. Large outputs go to disk.

Code Review: Clean Baseline Principle

Every phase must end clean. Therefore:

• All errors at review time were introduced by this phase
• All errors are blocking - no exceptions
• Inherited codebase errors = our job to fix

Directory Structure

claude-skills-collection/
├── .claude-plugin/                 # NEW: plugin packaging (see documentation/03-plugin-distribution.md)
│   ├── plugin.json                 #   plugin manifest — name `devflow`, namespaces every skill
│   └── marketplace.json            #   marketplace catalog — name `mhylle`, source "./"
├── skills/
│   ├── adr/
│   ├── adversarial-reviewer/      # NEW: Hostile-persona subagent review (Saboteur/New Hire/Security)
│   ├── agent-creator/
│   ├── brainstorm/
│   ├── code-quality-audit/       # NEW: Metrics gate (coverage, complexity, size, deps, mutation)
│   ├── code-review/
│   ├── codebase-audit/            # NEW: Long-running full-codebase audit orchestrator
│   ├── codebase-research/
│   ├── context-saver/
│   ├── continuous-learning/      # NEW: Pattern extraction
│   ├── create-plan/
│   ├── e2e-testing/
│   ├── eval-harness/             # NEW: Formal evaluation framework
│   ├── implement-phase/
│   ├── implement-plan/
│   ├── iterate-plan/
│   ├── prompt-generator/
│   ├── security-review/          # NEW: OWASP security audit
│   ├── strategic-compact/        # NEW: Smart compaction suggestions
│   ├── skill-visualizer/         # NEW: Interactive HTML visualizations
│   ├── user-story/               # Hierarchical user stories with Given/When/Then
│   ├── tt-create-build-loop/     # NEW: Writes an unattended TaskTracker build loop (template, lessons, token tooling)
│   ├── workflow-guide/           # NEW: Recommends workflow mode
│   ├── ship-issue/               # NEW: Issue→merge pipeline (SKILL.md, references/, scripts/dashboard.py)
│   └── verification-loop/        # 6-phase verification
├── agents/
│   ├── browser-verification-agent.md  # NEW: UI testing
│   ├── implementer.md                 # role agent: code + tests (sonnet)
│   ├── mechanic.md                    # role agent: checks, report-only (haiku)
│   ├── reviewer.md                    # role agent: code/security review (opus)
│   ├── codebase-analyzer.md
│   ├── codebase-locator.md
│   ├── codebase-pattern-finder.md
│   ├── docs-analyzer.md
│   ├── docs-locator.md
│   ├── issue-planner.md               # NEW: ship-issue planner (Fable 5)
│   ├── merge-gate-reviewer.md         # NEW: ship-issue merge-gate review (Fable 5)
│   ├── tdd-implementer.md             # NEW: ship-issue implementer (Opus 4.8)
│   ├── staging-e2e-verifier.md        # NEW: ship-issue staging E2E (Sonnet 4.6)
│   ├── staging-log-verifier.md        # NEW: ship-issue staging logs (Sonnet 4.6)
│   └── web-search-researcher.md
├── hooks/
│   └── hooks.json                  # plugin default hooks location
├── documentation/
│   ├── 01-workflow-overview.md
│   ├── 02-detailed-workflow.md
│   └── 03-plugin-distribution.md   # NEW: packaging, publishing, versioning
├── tests/
├── docs/
│   ├── decisions/                # ADRs
│   └── plans/                    # Implementation plans
├── LICENSE                         # NEW: MIT
└── README.md

Design Principles

1. Orchestration over Implementation: Skills coordinate, subagents execute - never write code directly
2. Quality Gates: Every phase must pass ALL verification steps before proceeding
3. Clean Baseline: Every phase ends clean; all errors are blocking, no exceptions
4. Context Preservation: Subagents return concise responses; large outputs go to disk
5. Extensibility: Pipeline steps can be added without core changes
6. Parallel Execution: Independent tasks run concurrently via background subagents
7. Precise References: All analysis includes file:line references
8. Task-Based Progress: Progress tracked via Claude Code Task tools, not file modifications

Progress Tracking with Task Tools

This skill collection uses Claude Code's native Task tools for all progress tracking. This replaces the traditional approach of modifying plan file checkboxes.

Why Task Tools?