name: skill-workshop description: > Analyze Codex CLI session history to discover skill candidates. Finds repeating explanations, tool chains, and workaround patterns across project sessions. Use when user wants to find what should become a skill, mine session history, or extract tribal knowledge. allowed-tools: Bash, Read, Write, Grep, Glob model: gpt-5.1-codex-mini

Skill Workshop

Mine project session history for repeating patterns and propose new skills.

Overview

This skill works in two phases:

1. Extract & Analyze — delegate to the session-analyzer subagent which parses session files and identifies pattern candidates
2. Present & Generate — read the analysis results, present candidates to the user, and generate SKILL.md drafts for approved candidates

Step 1: Determine target project

Use $ARGUMENTS as the project path. If empty, use the current working directory.

PROJECT_PATH="${ARGUMENTS:-$(pwd)}"
echo "Target project: $PROJECT_PATH"

Verify sessions exist by checking known session directories for the active tool:

PROJECT_PATH="${ARGUMENTS:-$(pwd)}"
FOUND=0

ENCODED=$(echo "$PROJECT_PATH" | sed 's|^/||; s|/|-|g')
for PREFIX in "-${ENCODED}" "${ENCODED}"; do
  DIR="$HOME/.claude/projects/${PREFIX}"
  if [ -d "$DIR" ]; then
    COUNT=$(ls "$DIR"/*.jsonl 2>/dev/null | grep -v '/agent-' | wc -l | tr -d ' ')
    echo "Claude Code: $COUNT session files in $DIR"
    FOUND=1
    break
  fi
done

if [ "$FOUND" -eq 0 ]; then
  for DIR in "$HOME/.codex/sessions" "$HOME/.codex"; do
    if [ -d "$DIR" ] && ls "$DIR"/*.jsonl 2>/dev/null | head -1 >/dev/null; then
      COUNT=$(ls "$DIR"/*.jsonl 2>/dev/null | wc -l | tr -d ' ')
      echo "Codex CLI: $COUNT session files in $DIR"
      FOUND=1
      break
    fi
  done
fi

echo "FOUND=$FOUND"

If no sessions found, inform the user:

• Check if the path is correct
• For Claude Code: sessions are deleted after 30 days by default. Suggest: "cleanupPeriodDays": 100000 in ~/.claude/settings.json
• For Codex CLI: check that ~/.codex/ exists and contains .jsonl files

If sessions found, report the counts and proceed.

Step 2: Delegate extraction to session-analyzer

Clean previous temporary files:

rm -f /tmp/sw-*.jsonl /tmp/sw-*.json /tmp/sw-*.txt

Delegate the extraction and analysis work to the session-analyzer subagent. Tell it the project path and the detected session directory. It will:

• Parse all JSONL session files via bash extraction
• Identify repeated explanations, tool chain patterns, and workaround patterns
• Score and rank candidates
• Write results to /tmp/skill-workshop-results.json

Wait for the subagent to complete.

Step 3: Read and present results

Read /tmp/skill-workshop-results.json. Present to the user:

Header:

• Project path
• Sessions analyzed (count and date range)
• Extraction stats (messages, tool calls, errors found)

Candidates table:

For each candidate (sorted by rank):

### #{rank}: {suggested_name}
Type: {signal_type} → proposed skill: {proposed_skill_type}
Score: {score} | Found in {frequency} sessions

{description}

Evidence:
- Session {id}: "{example}"
- Session {id}: "{example}"

Would create: {draft_content_hint}

After listing all candidates, ask: "Which candidates should I develop into skill drafts? (numbers, 'all', or 'none')"

Step 4: Generate SKILL.md drafts

For each approved candidate, generate a proper SKILL.md following these practices:

Skill authoring rules

1. Frontmatter:

   • name: kebab-case, match the suggested_name
   • description: CRITICAL field — the host tool uses this to decide when to load the skill. Format: "What it does. Use when [trigger conditions]." Write in third person. Max 200 characters. Include trigger words.

2. Body structure:

   • Start with a 1-2 sentence purpose statement
   • Use imperative language ("Run...", "Check...", not "You should...")
   • Include concrete examples from the evidence
   • Keep under 500 lines total

3. By skill type:

   knowledge (from repeated_explanation):

   • State the facts/rules directly
   • Include the exact terminology, values, configs the user kept repeating
   • Add a "Common mistakes" section listing what the assistant gets wrong

   workflow (from tool_chain):

   • Step-by-step procedure
   • Include the tool sequence as explicit steps
   • Add validation checkpoints between steps

   gotcha (from workaround):

   • Lead with the error pattern (what goes wrong)
   • Then the fix (what to do instead)
   • Make it a concise "DO this, NOT that" format
   • If possible, include a validation command

4. Write to: the active tool's skill directory. Use .claude/skills/{name}/SKILL.md for Claude Code or .codex/skills/{name}/SKILL.md for Codex CLI. Create the directory if needed.

5. DO NOT auto-enable. Tell the user to review and test.

Example gotcha skill

---
name: pip-break-system-packages
description: >
  Prevents pip externally-managed-environment errors on this system.
  Use when installing Python packages with pip.
---

# pip install configuration

On this system, always use the `--break-system-packages` flag with pip.

## The problem
Bare `pip install <package>` fails with:
`error: externally-managed-environment`

## The fix
Always run:
```bash
pip install <package> --break-system-packages

This applies to ALL pip install commands including:

• pip install -r requirements.txt --break-system-packages
• pip install -e . --break-system-packages
• pip install --upgrade <package> --break-system-packages

### Example knowledge skill

```markdown
---
name: milvus-collection-config
description: >
  Milvus connection details and collection schema for this project.
  Use when working with vector database, embeddings, or Milvus queries.
---

# Milvus Configuration

## Connection
- Host: localhost
- Port: 19530
- No authentication required in dev

## Collection: expert_tax_chunks
- Fields: id (int64, primary), text (varchar), vector (float_vector, dim=1024), metadata (json)
- Index: IVF_FLAT on vector field, nlist=128
- Metric: COSINE

## Common queries
[... concrete examples from evidence ...]

Step 5: Summary

After generating drafts, report:

• How many skills created, where
• Remind user to review each SKILL.md
• Suggest testing with a prompt that should trigger the skill in the active tool
• Note: newly created skills may need a session restart or tool-specific context refresh to be discovered