feat: add companion skills for business-analyst, implementation-planner, and implementation-executor agents

README.md

@@ -10,4 +10,5 @@ Individual projects opt into recipes by copying or referencing them.
 | Category | Recipe | Description |
 |----------|--------|-------------|
 | Automated Code Review | [automated-code-review/](automated-code-review/) | Automated code review patterns |
-| Claude Agents | [claude/agents/implementation-planner/](claude/agents/implementation-planner/) | Claude Code agent that creates 4-hour task breakdown implementation plans from feature requirements and posts them to GitHub issues |
+| Claude Agents | [claude/agents/](claude/agents/) | Claude Code agents for requirement refinement, implementation planning, and plan execution |
+| Claude Skills | [claude/skills/](claude/skills/) | Companion skills that guarantee correct agent invocation and show live task progress in the terminal |

claude/README.md

@@ -1,6 +1,6 @@
-# Claude Agents
+# Claude Agents & Skills
 
-This directory contains reusable, templatized Claude Code agents that can be set up in any project.
+This directory contains reusable, templatized Claude Code agents and skills that can be set up in any project.
 
 ## Available Agents
 
@@ -10,39 +10,73 @@ This directory contains reusable, templatized Claude Code agents that can be set
 | [implementation-executor](agents/implementation-executor/) | Takes an existing implementation plan from a GitHub issue and executes it — implementing each task sequentially, committing after each, pushing, and opening a PR. |
 | [business-analyst](agents/business-analyst/) | Refines raw or ambiguous requests into clear, business-aligned, non-technical requirement documents with explicit scope and acceptance criteria. |
 
-## Setting Up Agents in Your Project
+## Available Skills
+
+Skills are companion wrappers for the agents above. Each skill guarantees its agent is always invoked (never bypassed), and creates a live task checklist in the terminal so you can see progress step by step.
+
+| Skill | Wraps Agent | Description |
+|-------|-------------|-------------|
+| [cc-business-analyst](skills/cc-business-analyst/) | `business-analyst` | Shows live progress and guarantees the business-analyst agent is always triggered for requirement refinement. |
+| [cc-implementation-planner](skills/cc-implementation-planner/) | `implementation-planner` | Shows live progress and guarantees the implementation-planner agent is always triggered for technical planning. |
+| [cc-implementation-executor](skills/cc-implementation-executor/) | `implementation-executor` | Shows live progress and guarantees the implementation-executor agent is always triggered for plan execution. |
+
+> **Recommended:** Install both the agent and its companion skill together. The skill ensures the agent is always used correctly.
+
+## Setting Up Agents & Skills in Your Project
 
 > **Important:** Run the prompt below from your project's root directory so that Claude can access and review your project structure, tech stack, and conventions to automatically fill in placeholders.
 
 ### Steps
 
 1. Open Claude Code in your project directory.
 2. Copy and paste the prompt below.
-3. Claude will review your codebase, set up the agent files, and ask you about anything it can't infer on its own.
+3. Claude will review your codebase, set up the agent and skill files, and ask you about anything it can't infer on its own.
 
 ### Prompt
 
 ```
-I want to set up Claude Code agents from the engineering-recipes repo into this project.
+I want to set up Claude Code agents and skills from the engineering-recipes repo into this project.
 
-Source repo: https://github.com/ColoredCow/engineering-recipes (browse the `claude/agents/` directory for all available agents and their README).
+Source repo: https://github.com/ColoredCow/engineering-recipes (browse the `claude/agents/` directory for all available agents and their READMEs, and `claude/skills/` for all available skills).
 
-For each agent found there:
+For each agent in `claude/agents/`:
 
 1. Read the agent's template file and its README (which contains the placeholder reference and example values).
 2. Copy the agent template to `.claude/agents/<agent-name>.md` in this project.
 3. Replace all `{{PLACEHOLDER}}` values with project-specific values by:
    a. First, explore this project's codebase — look at the directory structure, config files, package.json/requirements.txt, existing patterns, test setup, and conventions to infer as many placeholder values as possible.
    b. For any placeholder you cannot confidently determine from the codebase, ask me before proceeding. Present what you've inferred so far and ask only about the ones you're unsure of.
 4. If the agent template has optional sections that don't apply to this project (e.g., Multi-Repository Context for a single-repo project), remove them.
-5. Register all set-up agents in this project's CLAUDE.md under a "Custom Agents" section. Create CLAUDE.md if it doesn't exist. Do NOT mention how to invoke them (no Task tool, no Skill tool, no slash commands) — Claude Code handles invocation automatically based on the agent's description frontmatter. Example format (markdown):
+
+For each skill in `claude/skills/`:
+
+5. Copy the entire skill directory to `.claude/skills/<skill-name>/` in this project (skills have no placeholders — copy as-is).
+
+Then:
+
+6. Register all set-up agents and skills in this project's CLAUDE.md. Create CLAUDE.md if it doesn't exist. Do NOT mention how to manually invoke agents or skills — Claude Code handles invocation automatically based on their description frontmatter.
+
+   For agents, add a "Custom Agents" section. Example format:
+
    ## Custom Agents
    Custom agents are defined in `.claude/agents/`. They are automatically invoked based on your request.
 
    | Agent | When to Use |
    |-------|-------------|
-   | implementation-planner | When the user asks for an implementation plan, technical breakdown, or task planning for a feature or issue. |
-
+   | `business-analyst` | When the user shares rough requirements and needs them refined into clear, business-readable, testable requirement docs without technical implementation details. |
+   | `implementation-planner` | When the user asks for an implementation plan, technical breakdown, or task planning for a feature or issue. |
+   | `implementation-executor` | When the user wants to execute an existing implementation plan — reads the plan from a GitHub issue, implements each task sequentially, commits, pushes, and opens a PR. |
+
+   For skills, add a "Custom Skills" section. Example format:
+
+   ## Custom Skills
+   Custom skills are defined in `.claude/skills/`. They wrap agents to guarantee correct invocation and show live task progress.
+
+   | Skill | Purpose |
+   |-------|---------|
+   | `cc-business-analyst` | Triggers the business-analyst agent with task tracking |
+   | `cc-implementation-planner` | Triggers the implementation-planner agent with task tracking |
+   | `cc-implementation-executor` | Triggers the implementation-executor agent with task tracking |
 
 After setup, show me a summary of what was configured and any values you'd recommend I review or adjust.
 ```

claude/skills/cc-business-analyst/README.md

@@ -0,0 +1,40 @@
+# cc-business-analyst Skill
+
+A Claude Code skill that ensures the `business-analyst` agent is always invoked for requirement refinement, and surfaces live task progress in the terminal as the agent works.
+
+## What It Does
+
+- Creates a task checklist before the agent runs so the user can see every step
+- Guarantees the `business-analyst` agent is triggered — never attempts the work inline
+- Updates task status (in_progress → completed) as each step finishes
+
+## Steps Tracked
+
+1. Read raw request and restate intent in plain language
+2. Identify ambiguities, missing decisions, and conflicting statements
+3. Refine into structured requirement document
+4. Validate acceptance criteria are specific and verifiable
+5. Flag truly blocking open questions
+
+## Setup
+
+### 1. Copy the skill directory
+
+```bash
+cp -r cc-business-analyst/ <your-project>/.claude/skills/cc-business-analyst/
+```
+
+### 2. Ensure the `business-analyst` agent is installed
+
+This skill is a wrapper — it requires the `business-analyst` agent to be set up in `.claude/agents/business-analyst.md`. See [`../../../claude/agents/business-analyst/`](../../agents/business-analyst/README.md) for agent setup instructions.
+
+## Usage
+
+Once installed, the skill auto-triggers when you ask Claude Code to work on requirements:
+
+```
+> Refine these rough notes into a proper requirement doc
+> Clean up this feature request and make the acceptance criteria testable
+> I need a BA pass on this before we plan the implementation
+> Convert this client call transcript into structured requirements
+```

claude/skills/cc-business-analyst/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: cc-business-analyst
+description: Use when the user wants to refine rough, ambiguous, or unstructured feature requests into clear, business-aligned requirement documents — including requests like "refine this requirement", "clean up this feature request", "make this testable", "convert these notes to requirements", "I need a BA pass on this", or whenever stakeholders need a structured, verifiable requirement doc before technical planning.
+---
+
+# cc-business-analyst
+
+Invokes the `business-analyst` agent to refine raw requirements into a structured, stakeholder-ready document. Never attempt requirement refinement inline — the agent must always be invoked, no exceptions.
+
+## Before Invoking the Agent
+
+Call `TaskCreate` for each of the following steps:
+
+1. Read raw request and restate intent in plain language
+2. Identify ambiguities, missing decisions, and conflicting statements
+3. Refine into structured requirement document (purpose, scope, functional requirements, business rules, acceptance criteria)
+4. Validate acceptance criteria are specific and verifiable
+5. Flag truly blocking open questions
+
+Then call `TaskUpdate` to mark task 1 `in_progress`.
+
+## Invoke the Agent
+
+```
+Agent(
+  subagent_type="business-analyst",
+  prompt="<full user message with all context>"
+)
+```
+
+**The agent must always be invoked. Never do the work inline.**
+
+## After the Agent Completes
+
+Call `TaskUpdate` on each task in sequence — mark `in_progress` then `completed` — based on what the agent reported completing.

claude/skills/cc-implementation-executor/README.md

@@ -0,0 +1,41 @@
+# cc-implementation-executor Skill
+
+A Claude Code skill that ensures the `implementation-executor` agent is always invoked for plan execution, and surfaces live task progress in the terminal as the agent works.
+
+## What It Does
+
+- Creates a task checklist before the agent runs so the user can see every step
+- Guarantees the `implementation-executor` agent is triggered — never attempts the work inline
+- Updates task status (in_progress → completed) as each step finishes
+
+## Steps Tracked
+
+1. Fetch and parse the implementation plan from the GitHub issue
+2. Set up feature branch
+3. Implement each task sequentially with commits
+4. Push branch to remote
+5. Create pull request
+6. Assign PR and verify CI checks
+
+## Setup
+
+### 1. Copy the skill directory
+
+```bash
+cp -r cc-implementation-executor/ <your-project>/.claude/skills/cc-implementation-executor/
+```
+
+### 2. Ensure the `implementation-executor` agent is installed
+
+This skill is a wrapper — it requires the `implementation-executor` agent to be set up in `.claude/agents/implementation-executor.md`. See [`../../../claude/agents/implementation-executor/`](../../agents/implementation-executor/README.md) for agent setup instructions.
+
+## Usage
+
+Once installed, the skill auto-triggers when you ask Claude Code to execute a plan:
+
+```
+> Execute the implementation plan on issue #584
+> Implement the plan we just created
+> Start coding the plan from this comment: <github-comment-url>
+> We've planned the feature, now let's build it
+```

claude/skills/cc-implementation-executor/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: cc-implementation-executor
+description: Use when the user wants to execute an existing implementation plan — including "execute the plan on issue #X", "implement the plan", "start coding the plan", "we've planned it, now build it", or when an implementation plan already exists on a GitHub issue and needs to be turned into committed code with a pull request.
+---
+
+# cc-implementation-executor
+
+Invokes the `implementation-executor` agent to execute an existing plan and open a pull request. Never implement code inline — the agent must always be invoked, no exceptions.
+
+## Before Invoking the Agent
+
+Call `TaskCreate` for each of the following steps:
+
+1. Fetch and parse the implementation plan from the GitHub issue
+2. Set up feature branch
+3. Implement each task sequentially with commits
+4. Push branch to remote
+5. Create pull request
+6. Assign PR and verify CI checks
+
+Then call `TaskUpdate` to mark task 1 `in_progress`.
+
+## Invoke the Agent
+
+```
+Agent(
+  subagent_type="implementation-executor",
+  prompt="<full user message with all context>"
+)
+```
+
+**The agent must always be invoked. Never do the work inline.**
+
+## After the Agent Completes
+
+Call `TaskUpdate` on each task in sequence — mark `in_progress` then `completed` — based on what the agent reported completing.

claude/skills/cc-implementation-planner/README.md

@@ -0,0 +1,39 @@
+# cc-implementation-planner Skill
+
+A Claude Code skill that ensures the `implementation-planner` agent is always invoked for technical planning, and surfaces live task progress in the terminal as the agent works.
+
+## What It Does
+
+- Creates a task checklist before the agent runs so the user can see every step
+- Guarantees the `implementation-planner` agent is triggered — never attempts the work inline
+- Updates task status (in_progress → completed) as each step finishes
+
+## Steps Tracked
+
+1. Determine GitHub issue ID (ask user if not provided)
+2. Explore codebase to understand context, patterns, and architecture
+3. Create phased implementation plan with 4-hour task breakdowns
+4. Post plan as a comment on the GitHub issue
+
+## Setup
+
+### 1. Copy the skill directory
+
+```bash
+cp -r cc-implementation-planner/ <your-project>/.claude/skills/cc-implementation-planner/
+```
+
+### 2. Ensure the `implementation-planner` agent is installed
+
+This skill is a wrapper — it requires the `implementation-planner` agent to be set up in `.claude/agents/implementation-planner.md`. See [`../../../claude/agents/implementation-planner/`](../../agents/implementation-planner/README.md) for agent setup instructions.
+
+## Usage
+
+Once installed, the skill auto-triggers when you ask Claude Code to plan a feature:
+
+```
+> Plan the implementation for adding a notification system
+> Create a technical breakdown for issue #42
+> Break down this feature into tasks: [paste requirements]
+> How should I implement this? [paste requirements]
+```

claude/skills/cc-implementation-planner/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: cc-implementation-planner
+description: Use when the user wants an implementation plan, technical breakdown, or task planning for a feature — including "plan this feature", "create a technical breakdown", "break this into tasks", "how should I implement this", or when requirements need to be translated into actionable, 4-hour development tasks to be posted on a GitHub issue.
+---
+
+# cc-implementation-planner
+
+Invokes the `implementation-planner` agent to produce a phased, 4-hour task breakdown plan and post it to a GitHub issue. Never attempt planning inline — the agent must always be invoked, no exceptions.
+
+## Before Invoking the Agent
+
+Call `TaskCreate` for each of the following steps:
+
+1. Determine GitHub issue ID (ask user if not provided)
+2. Explore codebase to understand context, patterns, and architecture
+3. Create phased implementation plan with 4-hour task breakdowns
+4. Post plan as a comment on the GitHub issue
+
+Then call `TaskUpdate` to mark task 1 `in_progress`.
+
+## Invoke the Agent
+
+```
+Agent(
+  subagent_type="implementation-planner",
+  prompt="<full user message with all context>"
+)
+```
+
+**The agent must always be invoked. Never do the work inline.**
+
+## After the Agent Completes
+
+Call `TaskUpdate` on each task in sequence — mark `in_progress` then `completed` — based on what the agent reported completing.