pilot-shell (Claude Skill) — Use Cases, Install & Live Demo

Why use it

Key features

Plan → spec → implement → verify pipeline as the default loop
Quality gates: lint, type, test, doc presence, all enforced
Project knowledge file maintained automatically
Acceptance-criteria-first; tests written before code
Hooks into Claude Code workflow without forcing a new tool

Live Demo

What it looks like in practice

ready

Install

Pick your client

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "pilot-shell-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/maxritter/pilot-shell",
        "~/.claude/skills/pilot-shell"
      ],
      "_inferred": true
    }
  }
}

Open Claude Desktop → Settings → Developer → Edit Config. Restart after saving.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "pilot-shell-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/maxritter/pilot-shell",
        "~/.claude/skills/pilot-shell"
      ],
      "_inferred": true
    }
  }
}

Cursor uses the same mcpServers schema as Claude Desktop. Project config wins over global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "pilot-shell-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/maxritter/pilot-shell",
        "~/.claude/skills/pilot-shell"
      ],
      "_inferred": true
    }
  }
}

Click the MCP Servers icon in the Cline sidebar, then "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "pilot-shell-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/maxritter/pilot-shell",
        "~/.claude/skills/pilot-shell"
      ],
      "_inferred": true
    }
  }
}

Same shape as Claude Desktop. Restart Windsurf to pick up changes.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "pilot-shell-skill",
      "command": "git",
      "args": [
        "clone",
        "https://github.com/maxritter/pilot-shell",
        "~/.claude/skills/pilot-shell"
      ]
    }
  ]
}

Continue uses an array of server objects rather than a map.

~/.config/zed/settings.json

{
  "context_servers": {
    "pilot-shell-skill": {
      "command": {
        "path": "git",
        "args": [
          "clone",
          "https://github.com/maxritter/pilot-shell",
          "~/.claude/skills/pilot-shell"
        ]
      }
    }
  }
}

Add to context_servers. Zed hot-reloads on save.

claude mcp add pilot-shell-skill -- git clone https://github.com/maxritter/pilot-shell ~/.claude/skills/pilot-shell

One-liner. Verify with claude mcp list. Remove with claude mcp remove.

Use Cases

Real-world ways to use pilot-shell

Ship a feature with spec-first discipline

👤 Devs tired of half-baked AI-written features ⏱ ~90 min intermediate

When to use: Vague feature request from PM; you want it shipped right, not fast.

Prerequisites

Skill installed — git clone https://github.com/maxritter/pilot-shell ~/.claude/skills/pilot-shell

Flow

Plan

Use pilot-shell. Plan the feature 'export usage CSV per workspace per month'. List unknowns + risks.✓ Copied

→ Plan with explicit unknowns; you fill gaps before next step
Spec

From the plan, write a spec with acceptance criteria + non-goals + edge cases.✓ Copied

→ Spec saved to /specs/<feature>.md
Implement

Implement against the spec. Tests first, then code. Stop at any unmet criterion.✓ Copied

→ Tests + impl; failing tests visible until impl passes
Verify gates

Run all gates: lint, type, tests, docs. Block PR if any red.✓ Copied

→ Gate report; only green = merge candidate

Outcome: Features that ship spec-complete, with tests and docs.

Pitfalls

Spec dragged out into a planning marathon — Time-box spec phase to 30 min; ship the smallest spec that locks acceptance

Combine with: filesystem

Stop opening PRs that fail CI on the first run

👤 Devs whose PRs frequently bounce on lint/type errors ⏱ ~30 min intermediate

When to use: You opened 3 PRs this week; all failed CI on basics.

Flow

Wire gates

Use pilot-shell. Configure quality gates to mirror our CI: eslint, tsc, vitest, prettier.✓ Copied

→ .pilot.config.json with gates listed
Block on red

Set policy: don't open PR until all gates green locally.✓ Copied

→ Policy applied
Measure

After 2 weeks, compare CI first-run pass rate before/after.✓ Copied

→ Pass rate up

Outcome: PRs that pass CI first try; less churn for reviewers.

Pitfalls

Local gates differ from CI subtly (Node version) — Pin local Node version with .nvmrc; mirror CI's exact commands

Combine with: github

Preserve project-knowledge as the team grows

👤 Project owners onboarding new collaborators ⏱ ~30 min beginner

When to use: You're handing off / sharing the project; want decisions and invariants captured.

Flow

Seed the knowledge file

Use pilot-shell. Initialize project knowledge with: architecture, key invariants, decisions log.✓ Copied

→ /.pilot/knowledge.md created with sections
Capture as you go

Whenever a decision is made (chose Postgres over MySQL), record with date + reason.✓ Copied

→ Decisions accumulate; new collaborators can read history
Use in onboarding

When a new collaborator starts, point Claude Code to this file as primary context.✓ Copied

→ Faster ramp; less 'why is it this way'

Outcome: Knowledge survives team changes.

Pitfalls

Knowledge file becomes a journal of trivia — Keep it terse: invariants, decisions, gotchas. Not a daily log

Combinations

Pair with other MCPs for X10 leverage

pilot-shell-skill + github

PR template auto-filled from spec; CI validates gates

When opening a PR, populate the body from the spec markdown; CI checks gates match.✓ Copied

pilot-shell-skill + filesystem

Specs and knowledge committed to repo

Persist /specs/ and /.pilot/knowledge.md in repo for review history.✓ Copied

Tools

What this MCP exposes

Tool	Inputs	When to call
plan	feature_description	Step 1 of any new feature
spec	plan_id	After plan unknowns resolved
implement	spec_id	After spec approved
run_gates	scope?	Pre-PR; CI mirror
knowledge_update	decision_or_invariant	Capture project-level decision

Cost & Limits

What this costs to run

API quota: None — local
Tokens per call: Spec docs ~500–2000 tokens; knowledge file caps ~3000 to stay manageable
Monetary: Free
Tip: Cap knowledge.md at ~3000 tokens; consolidate older entries periodically

Security

Permissions, secrets, blast radius

Minimum scopes: filesystem-write

Credential storage: None

Data egress: None

Specs may describe sensitive product details — gitignore /specs/ if private

Troubleshooting

Common errors and fixes

Gates pass locally but fail in CI

Pin Node version, OS-specific deps; mirror CI command exactly

Verify: Diff local vs CI command output

Implement step skips test-first

Set policy strict_tdd=true in .pilot.config; tool will refuse to write impl before tests

Spec phase drags

Use --time-box 30m; force decisions on unknowns instead of perfect specs

Knowledge file too long

Run knowledge_consolidate; archives old entries to /.pilot/archive/

Alternatives

pilot-shell vs others

Alternative	When to use it instead	Tradeoff
spec-workflow-mcp	You want this as an MCP server with cross-tool reach (not a Claude Code skill)	More setup; more flexible deploy
Plain CLAUDE.md + manual TDD	Solo project, you don't need automation	Discipline-dependent; fewer guardrails

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills