Brewcode:Skills

skills Skill

Skill Management: List, improve, create skills with activation optimization.

<instructions>

Parse Arguments

Extract mode and target from $ARGUMENTS:

Smart Detection: If first argument is NOT a mode keyword (list, up, create), treat entire input as target for up mode.

Examples:

• /brewcode:skills or list → list
• /brewcode:skills up commit → up, target=commit
• /brewcode:skills create "semantic code search" → create, target=prompt
• /brewcode:skills commit → up, target=commit (shorthand)
• /brewcode:skills ~/.claude/skills/ → up, target=folder (shorthand)

---

Mode: list

EXECUTE using Bash tool:

bash "${CLAUDE_SKILL_DIR}/scripts/list-skills.sh" && echo "✅ list" || echo "❌ list FAILED"

STOP if ❌ — verify skill base directory is resolved and scripts exist.

---

Mode: create / up (Unified Flow)

Both create and up follow Phases 0-6. Differences noted per phase.

Description Budget (DEFAULT)

Frontmatter description: <= 120 chars (optimal ~100), single line. What + when + 3-5 distinct triggers (comma-list). No filler, no <example> blocks. Some registries truncate long descriptions and dilute trigger matching. EN only unless user explicitly asks.

Prerequisite (up only): Resolve Target

EXECUTE using Bash tool:

TARGET="$ARGUMENTS"
if [[ "$TARGET" == up\ * ]] || [[ "$TARGET" == "up" ]]; then
  TARGET="${TARGET#up }"; TARGET="${TARGET#up}"
fi
TARGET="$(echo "$TARGET" | xargs)"
if [[ -z "$TARGET" ]]; then
  echo "❌ No target. Usage: /brewcode:skills up <name|path|folder>"; exit 1
fi
if [[ -d "$TARGET" ]]; then
  echo "TYPE: folder"; echo "PATH: $TARGET"
  find "$TARGET" -name "SKILL.md" -type f 2>/dev/null | head -20
elif [[ -f "$TARGET" ]]; then
  echo "TYPE: file"; echo "PATH: $TARGET"
elif [[ -f "$TARGET/SKILL.md" ]]; then
  echo "TYPE: skill-dir"; echo "PATH: $TARGET/SKILL.md"
else
  echo "TYPE: name"; echo "NAME: $TARGET"
  for loc in ~/.claude/skills .claude/skills; do
    [[ -f "$loc/$TARGET/SKILL.md" ]] && echo "FOUND: $loc/$TARGET/SKILL.md"
  done
fi

STOP if ❌ — target must resolve to at least one SKILL.md.

Phase 0: Discovery

Spawn 2-3 Explore agents in parallel (single message).

create mode — spawn in ONE message: 1. Explore: Research skill patterns in $BC_PLUGIN_ROOT/skills/ and ~/.claude/skills/ — structure, naming, frontmatter, references, scripts. 2. Explore: Analyze target project structure for {TOPIC} — code, APIs, configs, tooling. 3. (Optional) general-purpose: Web research for {TOPIC} — best practices, similar tools. Use WebSearch/WebFetch.

up mode — spawn in ONE message: 1. Explore: Analyze skill at {SKILL_PATH} — SKILL.md, references/, scripts/, tests/, README.md. Report quality and gaps. 2. Explore: Compare {SKILL_PATH} against patterns in $BC_PLUGIN_ROOT/skills/. Output improvement recommendations.

Phase 1: User Interaction

Step 1: Check Conversation History (create only) Check if current conversation already contains workflow to capture. If yes: extract tools, steps, corrections, I/O formats for Phase 2.

Step 2: Determine Input Type (create only)

Step 3: Invocation Type (AskUserQuestion)

header: "Invocation"
question: "Who will invoke this skill?"
options:
  - label: "User only (slash command)"
    description: "disable-model-invocation: true, simple description"
  - label: "LLM auto-detect"
    description: "Full trigger keyword optimization"
  - label: "Both (default)"
    description: "User slash command + LLM auto-detection"

Save as INVOCATION_TYPE.

Step 4: Mode Switcher Detection (create only)

Keywords: "mode", "toggle", "switch", "persistent", "from now on", "always do", "session behavior"

If detected — AskUserQuestion: "Create as Mode Switcher skill?" (Yes/No). If Yes: set IS_MODE_SWITCHER=true, then ask scope (Project/Global/Session) via AskUserQuestion, save as MODE_SCOPE.

Validate BC_PLUGIN_DATA: EXECUTE using Bash tool:

if [ -n "$BC_PLUGIN_DATA" ]; then echo "✅ BC_PLUGIN_DATA=$BC_PLUGIN_DATA"; else echo "❌ BC_PLUGIN_DATA not set"; fi

STOP if ❌ — BC_PLUGIN_DATA required for Mode Switcher.

Step 5: Testing Depth (AskUserQuestion)

header: "Testing Depth"
question: "How thoroughly should the skill be tested?"
options:
  - label: "Quick (default)" — validate-skill.sh + 3-5 test prompts
  - label: "Standard" — + unit tests + simple review (1 reviewer + verification)
  - label: "Deep" — + quorum review (3 reviewers, threshold 2) + E2E tests

Save as TESTING_DEPTH.

Step 6: Review Type (AskUserQuestion, only if Standard or Deep)

header: "Review Type"
question: "What review approach?"
options:
  - label: "Simple (default for Standard)" — 1 reviewer + 1 verification agent
  - label: "Quorum (default for Deep)" — 3 reviewers parallel, threshold 2/3, DoubleCheck

Save as REVIEW_TYPE.

Step 7: Plan Confirmation (AskUserQuestion)

Output plan summary: Action (Create/Improve), skill path/name, files to create/modify, references used, testing approach, review type.

header: "Plan Confirmation"
question: "Proceed with this plan?"
options: [Proceed, Adjust ("Let me change something"), Cancel]

If Adjust — ask what to change, update, re-confirm. If Cancel — stop.

Phase 2: Create/Improve (skill-creator agent)

Task(subagent_type="brewcode:skill-creator", model="opus", prompt=" {ACTION} skill based on research and user preferences. Action: {create|improve} Topic/Skill: {TOPIC or SKILL_PATH} Invocation type: {INVOCATION_TYPE}

Discovery Results

{EXPLORE_RESULTS}

Requirements

• Follow skill-creator best practices
• Generate unit tests for scripts/ (Step 5.7)
• Generate README.md (Step 5.8)
• Invocation type pre-filled: {INVOCATION_TYPE} — skip asking

")

Mode Switcher additions (if IS_MODE_SWITCHER=true) — append:

• Single skill with argument parsing: on [mode-name], off, status
• State in $BC_PLUGIN_DATA/modes.json — structure: .global, .projects["$PWD"], .sessions["$SESSION_ID"]
• Scope: {MODE_SCOPE}, resolution priority: session > project > global
• disable-model-invocation: true, mode instructions in references/
• Bash MUST validate: if [ -z "$BC_PLUGIN_DATA" ]; then echo "❌"; exit 1; fi

After creation (if Mode Switcher): AskUserQuestion — create mode file in brewcode/modes/? If yes: spawn brewcode:hook-creator.

Folder target (multiple skills): spawn parallel agents in ONE message, one per SKILL.md found.

Phase 3: Validate (automatic)

Skill-creator Steps 5-5.8 run automatically (validate, unit tests, README). No orchestrator action needed.

Phase 4: Review

Skip if `TESTING_DEPTH` is Quick.

Read review prompt: ${CLAUDE_SKILL_DIR}/references/review-prompt.md

Simple Review (`REVIEW_TYPE` = Simple):

1. Task(subagent_type="brewcode:reviewer", model="opus", prompt="Review skill quality at: {SKILL_PATH}\n\n{REVIEW_PROMPT_CONTENT}") 2. If findings: Task(subagent_type="brewcode:reviewer", model="sonnet", prompt="Verify these review findings against actual code...\n\n{REVIEWER_FINDINGS}") 3. Confirmed findings: Task(subagent_type="brewcode:skill-creator", model="opus", prompt="Fix verified issues in skill at: {SKILL_PATH}\n\n{CONFIRMED_FINDINGS}")

Quorum Review (`REVIEW_TYPE` = Quorum):

1. Three in parallel (ONE message): Task(subagent_type="brewcode:reviewer", model="opus", prompt="Review skill quality at: {SKILL_PATH}\n\n{REVIEW_PROMPT_CONTENT}") Task(subagent_type="brewcode:reviewer", model="opus", prompt="Review skill quality at: {SKILL_PATH}\n\n{REVIEW_PROMPT_CONTENT}") Task(subagent_type="brewcode:reviewer", model="opus", prompt="Review skill quality at: {SKILL_PATH}\n\n{REVIEW_PROMPT_CONTENT}") 2. Quorum: same file + +-5 lines + same category = threshold 2/3 agree. 3. Task(subagent_type="brewcode:reviewer", model="opus", prompt="DoubleCheck: verify quorum findings against code.\n\n{QUORUM_FINDINGS}") 4. Confirmed: Task(subagent_type="brewcode:skill-creator", model="opus", prompt="Fix verified issues...\n\n{CONFIRMED_FINDINGS}")

Collect findings: After Phase 4 completes, compile all confirmed findings (source, severity, issue, fix applied, verified status) into a structured list. Pass to Phase 6 for summary.

Phase 5: E2E Testing (Optional)

Only if `TESTING_DEPTH` is Deep. Otherwise skip.

1. Read: ${CLAUDE_SKILL_DIR}/references/e2e-template.md 2. Create test scenarios in {SKILL_DIR}/tests/ — 1 per mode (happy path) + 1 edge case per mode. 3. Execute each scenario:

EXECUTE using Bash tool:

TMPDIR=$(mktemp -d)
mkdir -p "$TMPDIR/.claude/skills"
cp -r "{SKILL_DIR}" "$TMPDIR/.claude/skills/"
cd "$TMPDIR" && timeout 120 claude -p "{PROMPT}" 2>&1 | tee "$TMPDIR/output.log"
{ASSERTION_COMMANDS}
rm -rf "$TMPDIR"

4. Iteration: scenario failure = fix (max 2 retries). Small skill issues = fix + re-run. Major issues = back to Phase 2.

Phase 6: Summary

Read: ${CLAUDE_SKILL_DIR}/references/summary-template.md

Fill: action, path, invocation type, testing depth, review type, completed phases checklist, problems found/fixed (Phase 4), test results (Phase 3 + 5), suggestions, skipped phases with reasons.

Output filled summary to user.

</instructions>

---

Output Format

For list mode only. For create/up modes, Phase 6 summary replaces this section.

# skills [list]

## Detection

| Field | Value |
|-------|-------|
| Arguments | `$ARGUMENTS` |
| Mode | `list` |
| Target | `none` |

## Skills Summary

| Location | Count | Skills |
|----------|-------|--------|
| Global (~/.claude/skills/) | N | skill1, skill2 |
| Project (.claude/skills/) | N | skill3 |
| Plugins | N | plugin:skill1 |

## Next Steps

- [recommendations based on results]

Skills

Manage Claude Code skills -- list installed skills, improve existing ones via the skill-creator agent, or create new skills from a prompt or spec file with research-driven generation.

Quick Start

/brewcode:skills

Lists all available skills across global, project, and plugin locations.

Modes

Examples

Good Usage

# List everything installed
/brewcode:skills list

# Improve a skill by name (searches global and project locations)
/brewcode:skills up commit

# Shorthand -- same as above, "up" is implied
/brewcode:skills commit

# Improve a skill by explicit path
/brewcode:skills up ~/.claude/skills/commit/SKILL.md

# Shorthand with path
/brewcode:skills brewcode/skills/setup

# Improve all skills in a folder (parallel agents)
/brewcode:skills ~/.claude/skills/

# Create a brand new skill from a prompt
/brewcode:skills create "semantic code search"

# Create a skill from a spec file
/brewcode:skills create ./my-skill-spec.md

Common Mistakes

Output

Depends on mode:

• list -- a summary table of all skills grouped by location (global ~/.claude/skills/, project .claude/skills/, plugins).
• up -- the skill-creator agent rewrites the target SKILL.md with optimized description, trigger keywords, imperative voice, and best practices. For folders, multiple agents run in parallel.
• create -- a new skill directory containing SKILL.md and README.md, placed in .claude/skills/ (project) or ~/.claude/skills/ (global). Before creation you are asked whether the skill should be user-invocable, LLM auto-detected, or both.

Mode Switcher

The create mode can generate Mode Switcher skills — special skills that toggle persistent behavioral modes for the entire Claude Code session.

What is a Mode Switcher?

A mode switcher is a skill that changes how Claude behaves for the rest of the session. For example, "manager mode" makes Claude delegate all tasks via agents, "researcher mode" makes Claude prioritize depth and source verification.

How it works

/brewcode:skills create "toggle research mode"
                    ↓
         Step 2.5 detects "mode/toggle" keywords
                    ↓
         Asks: "Create as a Mode Switcher skill?"
                    ↓  Yes
         skill-creator uses Mode Switcher pattern
                    ↓
    Creates skill with on/off/status arguments
                    ↓
    Skill writes state → hooks inject instructions

Flow

Skill writes {"mode":"research"} → $CLAUDE_PLUGIN_DATA/modes.json
                    ↓
  forced-eval.mjs   → injects [MODE: research] into every user prompt
  session-start.mjs → injects mode into session context (survives compact)
  pre-task.mjs      → injects mode into every sub-agent prompt

Example

# Create a mode switcher skill
/brewcode:skills create "toggle deep research mode that prioritizes source verification"

# The created skill will support:
/my-mode on research    # activate mode
/my-mode off            # deactivate
/my-mode status         # show current mode

Creating a mode manually

1. Create mode instructions file: brewcode/modes/{name}.md (plain text) 2. Activate:

   MODES="$BC_PLUGIN_DATA/modes.json"
   [ ! -f "$MODES" ] && echo '{}' > "$MODES"
   jq --arg m "research" --arg p "$PWD" --arg t "$(date -u +%Y-%m-%dT%H:%M:%S.000Z)" \
     '.projects[$p] = {mode: $m, activatedAt: $t}' "$MODES" > "$MODES.tmp" && mv "$MODES.tmp" "$MODES"

3. Deactivate:

   MODES="$BC_PLUGIN_DATA/modes.json"
   jq --arg p "$PWD" 'del(.projects[$p])' "$MODES" > "$MODES.tmp" && mv "$MODES.tmp" "$MODES"

Legacy fallback: .claude/tasks/cfg/brewcode.state.json (flat mode field) is still supported but deprecated.

Hooks pick up the change automatically — no code modifications needed.

Tips

• Use the shorthand form (/brewcode:skills commit) for quick improvements -- no need to type up explicitly.
• Point at a folder (/brewcode:skills ~/.claude/skills/) to batch-improve every skill inside it. Each skill gets its own parallel agent.
• The create mode checks conversation history first. If the current conversation already contains a workflow worth capturing, it extracts context directly and skips web research.
• After creating a skill, you are offered an optional eval step that runs three test prompts to verify the skill activates correctly.

Documentation

Full docs: skills

E2E Test Scenario Template

Template for skill E2E tests executed via claude -p from bash.

---

Scenario Structure

# E2E: {SKILL_NAME} -- {MODE} -- {VARIANT}

## Setup
- Skill path: {SKILL_PATH}
- Mode: {MODE} (e.g., create, up, list)
- Variant: happy-path | edge-case | error-handling

## Prompt
> The exact prompt to send to claude -p

## Expected Behavior
- [ ] Skill triggers (slash command recognized)
- [ ] Expected files created/modified
- [ ] Expected output contains key phrases
- [ ] No errors in stderr

## Assertions
| # | Check | Command | Expected |
|---|-------|---------|----------|
| 1 | File exists | `test -f path` | exit 0 |
| 2 | Content match | `grep -q "pattern" file` | exit 0 |
| 3 | Line count | `wc -l < file` | 10..500 |
| 4 | No errors | `! grep -qi "error" output.log` | exit 0 |

---

Execution Methods

Method A -- Isolated (preferred for CI):

TMP=$(mktemp -d)
mkdir -p "$TMP/.claude/skills"
cp -r "$SKILL_PATH" "$TMP/.claude/skills/"
cd "$TMP" && timeout 120 claude -p "{prompt}" 2>&1 | tee "$TMP/output.log"
EXIT_CODE=$?
# run assertions against $TMP/output.log and generated files
rm -rf "$TMP"

Method B -- In-session (installed plugin):

timeout 120 claude -p '/brewcode:skills create name="my-skill"' 2>&1 | tee output.log

Capture and timeout:

timeout 120 claude -p "..." 2>&1 | tee output.log
echo "EXIT: $?"

---

Assertion Patterns

File exists:

test -f "$FILE" && echo "PASS" || echo "FAIL: $FILE not found"

Content contains pattern:

grep -q "$PATTERN" "$FILE" && echo "PASS" || echo "FAIL: pattern '$PATTERN' not in $FILE"

Line count in range:

lines=$(wc -l < "$FILE")
[ "$lines" -ge 10 ] && [ "$lines" -le 500 ] && echo "PASS" || echo "FAIL: $lines lines (expected 10..500)"

YAML frontmatter present:

head -1 "$FILE" | grep -q "^---" && echo "PASS" || echo "FAIL: no YAML frontmatter"

No errors in output:

! grep -qi "error\|fail\|exception" output.log && echo "PASS" || echo "FAIL: errors found in output"

Exit code check:

[ "$EXIT_CODE" -eq 0 ] && echo "PASS" || echo "FAIL: exit code $EXIT_CODE"

Aggregate result:

RESULTS="$TMP/results.txt"
# ... each assertion appends PASS/FAIL to $RESULTS ...
FAILS=$(grep -c "FAIL" "$RESULTS")
echo "Total: $(wc -l < "$RESULTS") | Failed: $FAILS"
[ "$FAILS" -eq 0 ] && echo "E2E PASSED" || echo "E2E FAILED"

---

Iteration Rules

README Template for Claude Code Skills

Instructions for skill-creator agent:

- Replace all {PLACEHOLDERS} with actual values from the skill being documented

- Remove sections that don't apply (e.g., Modes for single-mode skills, Arguments if none)

- Keep README under 100 lines

- Use actual examples from the skill, not generic ones

- Files section: only list directories/files that actually exist in the skill

- After generation, remove this instructions block entirely

---

Template

---
auto-sync: enabled
auto-sync-date: {TODAY}
auto-sync-type: skill
---

# {SKILL_NAME}

> {ONE_LINE_DESCRIPTION}

## Quick Start

`/{SKILL_NAME} {ARGUMENT_HINT}`

## Modes

| Mode | Usage | Description |
|------|-------|-------------|
| {MODE} | `/{SKILL_NAME} {MODE} {ARGS}` | {DESCRIPTION} |

> Omit this section if single-mode skill.

## Arguments

| Argument | Required | Description |
|----------|----------|-------------|
| {ARG} | {YES/NO} | {ARG_DESCRIPTION} |

## Examples

### {EXAMPLE_TITLE}

/{SKILL_NAME} {EXAMPLE_ARGS}

### {EXAMPLE_TITLE_2}

/{SKILL_NAME} {EXAMPLE_ARGS_2}

## Workflow

1. {STEP_1}
2. {STEP_2}
3. {STEP_3}

## Output

{DESCRIBE_WHAT_THE_SKILL_PRODUCES — files, reports, artifacts, console output}

## Files

| File | Purpose |
|------|---------|
| SKILL.md | Main skill definition |
| references/ | {REFERENCE_DESC} |
| scripts/ | {SCRIPTS_DESC} |
| tests/ | {TESTS_DESC} |

Skill Quality Review

You are reviewing a skill for structural correctness, activation quality, and security.

Skill path: {SKILL_PATH}

Read the entire skill directory: SKILL.md, references/, scripts/, tests/, README.md.

---

Review Checklist

---

Severity Definitions

---

Output Format

Report ALL findings in this exact format:

## Review: {SKILL_NAME}

### Summary

| Metric | Value |
|--------|-------|
| Total findings | N |
| Critical | N |
| Major | N |
| Minor | N |
| Nit | N |
| Verdict | PASS / PASS WITH ISSUES / FAIL |

Verdict rules: FAIL if any critical. PASS WITH ISSUES if any major. PASS otherwise.

### Findings

| # | Category | Severity | File | Line | Issue | Suggestion |
|---|----------|----------|------|------|-------|------------|
| 1 | Description | major | SKILL.md | 3 | Missing Triggers line | Add `Triggers - keyword1, keyword2, keyword3` |
| 2 | Scripts | critical | scripts/run.sh | 12 | Hardcoded /home/user path | Use `${CLAUDE_SKILL_DIR}` instead |

---

Verification Requirement

Findings are NOT actionable until verified by a separate agent.

Each finding MUST include:

• Exact file path relative to skill directory
• Exact line number where the issue occurs
• Specific text or pattern that demonstrates the issue

The verification agent will cross-check every finding against the actual file content. Do NOT suggest fixes that you have not confirmed are applicable to the current file state.

---

Review Modes

This prompt is used in two modes by the orchestrator:

In quorum mode, each reviewer works independently. The orchestrator merges results and applies majority-rule filtering.

Summary Report Template for Skills Orchestrator (Phase 6)

Instructions for orchestrator:

- Fill all {PLACEHOLDERS} from collected data across phases

- Remove empty sections (e.g., E2E Tests if Quick mode, Review if None)

- Checkboxes reflect actual phase completion: [x] done, [ ] skipped

- Problems table only includes confirmed and verified findings

- After generation, remove this instructions block entirely

---

Template

# Skill {ACTION}: {SKILL_NAME}

| Field | Value |
|-------|-------|
| Location | {SKILL_PATH} |
| Action | {ACTION} |
| Invocation | {INVOCATION_TYPE} |
| Testing Depth | {TESTING_DEPTH} |
| Review Type | {REVIEW_TYPE} |
| Model | {MODEL} |

## What Was Done

- [{DISCOVERY}] Discovery (Explore agents)
- [{INTERACTION}] User interaction (invocation, testing depth)
- [{CREATE}] {ACTION_VERB} (skill-creator)
- [{VALIDATE}] Validation (validate-skill.sh + checklists)
- [{UNIT}] Unit Tests (scripts/)
- [{README}] README generation
- [{REVIEW}] Review ({REVIEW_TYPE})
- [{E2E}] E2E Testing

## Problems Found and Fixed

| # | Source | Severity | Issue | Fix | Verified |
|---|--------|----------|-------|-----|----------|
| {N} | {PHASE_OR_AGENT} | {HIGH/MEDIUM/LOW} | {DESCRIPTION} | {WHAT_WAS_DONE} | {YES/NO} |

## Test Results

### Unit Tests

| Script | Tests | Passed | Failed |
|--------|-------|--------|--------|
| {SCRIPT_NAME} | {TOTAL} | {PASSED} | {FAILED} |

### E2E Tests

| Scenario | Mode | Variant | Status | Assertions | Details |
|----------|------|---------|--------|------------|---------|
| {SCENARIO} | {MODE} | {VARIANT} | {PASS/FAIL} | {COUNT} | {NOTES} |

## What Could Be Improved

- {SUGGESTION_1}
- {SUGGESTION_2}

## What Was NOT Done

- {SKIPPED_ITEM} -- Reason: {WHY}