---

name: skill-writer description: "INVOKE when: creating new skills, editing SKILL.md files, modifying .claude/ content. NEVER edit .claude/ directly - this skill shows the arsenal-first workflow."

skill-writer Skill

🎯 Purpose

This skill explains how to create and edit Claude Code skills in the arsenal repository.

Use this skill when:

• Creating a new skill
• Editing existing skill documentation
• Understanding the skill development workflow
• Setting up skill metadata and structure

---

Core Principle: Arsenal-First Development

ALL skill code and documentation lives in ./arsenal/dot-claude/

The .claude/ directory in the project root is a COPY, not the source of truth.

arsenal/
  dot-claude/              ← Source of truth (edit here)
    skills/
      getting-started/
        SKILL.md
      test-writer/
        SKILL.md
      your-new-skill/      ← Create new skills here
        SKILL.md

.claude/                   ← Copy (created by install.sh)
  skills/                  ← DO NOT edit directly!
    getting-started/
    test-writer/
    your-new-skill/

Workflow:

1. Edit files in arsenal/dot-claude/skills/
2. Run ./arsenal/install.sh to sync changes to .claude/
3. Test the skill
4. Commit changes to arsenal (git add, git commit)

---

Step 1: Understand Skill Structure

Minimal Skill Structure

Every skill MUST have:

arsenal/dot-claude/skills/SKILL_NAME/
  SKILL.md              ← Main skill documentation (REQUIRED)

Optional Components

Skills MAY have:

arsenal/dot-claude/skills/SKILL_NAME/
  SKILL.md              ← Main documentation (REQUIRED)
  scripts/              ← Shell scripts, Python scripts, etc.
    run_something.sh
    helper.py
  node_modules/         ← Auto-installed if package.json exists
  package.json          ← Node.js dependencies (optional)
  PRESSURE_TESTS.md     ← Tests to verify skill compliance (optional)
  README.md             ← Additional documentation (optional)
  .env.example          ← Environment template (optional)

Skill Metadata

The SKILL.md should start with frontmatter metadata:

---
name: skill-name
description: Brief one-line description shown in skill list
---

# skill-name Skill

## Purpose
...

Important: The name field is used in the skill registry and should match the directory name.

---

Step 2: Plan Your Skill

Before creating a skill, answer these questions:

Question 1: What problem does this skill solve?

• What task will users perform?
• What common mistakes does this prevent?
• Why is a skill needed instead of just documentation?

Question 2: When should this skill be used?

• What triggers should activate this skill?
• Is it mandatory or optional?
• Should it be proactively suggested?

Question 3: What tools/commands does it need?

• Shell scripts?
• Python scripts?
• Node.js dependencies?
• External CLI tools?
• Environment variables?

Question 4: How will you test compliance?

• What are the success criteria?
• What are common violations?
• Do you need pressure tests?

---

Step 3: Create the Skill Directory

# Create the skill directory in arsenal
mkdir -p arsenal/dot-claude/skills/YOUR_SKILL_NAME

# Create the main SKILL.md file
touch arsenal/dot-claude/skills/YOUR_SKILL_NAME/SKILL.md

Naming conventions:

• Use lowercase with hyphens: test-writer, git-reader, skill-writer
• Be specific and action-oriented: update-langfuse-staging-server-prompt not just langfuse
• Avoid generic names: prefer playwright-tester over browser

---

Step 4: Write the SKILL.md

Template Structure

---
name: your-skill-name
description: One-line description (appears in skill lists)
---

# your-skill-name Skill

## 🎯 Purpose

Explain what this skill does and why it exists.

**Use this skill when:**
- Trigger condition 1
- Trigger condition 2
- Trigger condition 3

---

## Step 1: [First Major Step]

Clear, actionable instructions.

### Substep 1.1: [Specific Action]

```bash
# Command example
command --flag value

Expected output:

Show what success looks like

---

Step 2: [Second Major Step]

Continue with clear steps...

---

Common Violations

Document what NOT to do:

• ❌ BANNED: Specific anti-pattern to avoid
• ❌ CRITICAL: Another violation with explanation
• ✅ CORRECT: Show the right way

---

Troubleshooting

Problem: Common error message Cause: Why this happens Solution: How to fix it

---

Success Criteria

You've completed this skill when:

• Criterion 1
• Criterion 2
• Criterion 3

### Writing Guidelines

**DO:**
- ✅ Use clear, imperative language ("Run this command", "Check the output")
- ✅ Provide copy-pasteable commands
- ✅ Show expected output
- ✅ Include troubleshooting sections
- ✅ Use emojis for visual hierarchy (🎯 🚨 ✅ ❌)
- ✅ Mark mandatory vs optional steps clearly
- ✅ Provide examples of when to use the skill

**DON'T:**
- ❌ Be vague or hand-wavy ("configure appropriately")
- ❌ Assume knowledge ("as you know...")
- ❌ Skip error cases
- ❌ Forget edge cases
- ❌ Make skills too long (split into multiple skills if needed)

---

## Step 5: Add Supporting Files (Optional)

### Shell Scripts

If your skill needs automation:

```bash
# Create scripts directory
mkdir -p arsenal/dot-claude/skills/YOUR_SKILL_NAME/scripts

# Create script
cat > arsenal/dot-claude/skills/YOUR_SKILL_NAME/scripts/run_task.sh << 'EOF'
#!/bin/bash
set -e

echo "Running task..."
# Your commands here
EOF

# Make executable
chmod +x arsenal/dot-claude/skills/YOUR_SKILL_NAME/scripts/run_task.sh

Python Scripts

cat > arsenal/dot-claude/skills/YOUR_SKILL_NAME/scripts/helper.py << 'EOF'
#!/usr/bin/env python3
"""Helper script for YOUR_SKILL_NAME skill."""
import sys

def main():
    print("Helper running...")
    # Your code here

if __name__ == "__main__":
    main()
EOF

chmod +x arsenal/dot-claude/skills/YOUR_SKILL_NAME/scripts/helper.py

Node.js Dependencies

If your skill needs Node packages:

cd arsenal/dot-claude/skills/YOUR_SKILL_NAME

# Create package.json
cat > package.json << 'EOF'
{
  "name": "your-skill-name",
  "version": "1.0.0",
  "private": true,
  "dependencies": {
    "some-package": "^1.0.0"
  }
}
EOF

# Install dependencies (install.sh will do this automatically)
npm install

Note: The install script automatically runs npm install for any skill with a package.json.

---

Step 6: Test Your Skill

Manual Testing

# 1. Sync to .claude directory
./arsenal/install.sh

# 2. Verify it appears in skill list
ls .claude/skills/

# 3. Read the skill as Claude would
cat .claude/skills/YOUR_SKILL_NAME/SKILL.md

# 4. Test any scripts
.claude/skills/YOUR_SKILL_NAME/scripts/run_task.sh

# 5. Start a new Claude Code session and use the skill
# The skill should be available via the Skill tool

Automated Testing (Optional)

Create pressure tests to verify compliance:

cat > arsenal/dot-claude/skills/YOUR_SKILL_NAME/PRESSURE_TESTS.md << 'EOF'
# Pressure Tests for YOUR_SKILL_NAME

## Test 1: [Scenario Name]

**Setup:**
- Condition 1
- Condition 2

**Expected Behavior:**
- Agent should do X
- Agent should NOT do Y

**Violation:**
- If agent does Z, test fails

---

## Test 2: [Another Scenario]

...
EOF

---

Step 7: Document in CLAUDE.md

After creating your skill, add it to the skill registry in arsenal/system-prompts/CLAUDE.md:

### your-skill-name
**Description of what it does**

When to use: [Trigger conditions]
Where: `.claude/skills/your-skill-name/SKILL.md`

**Example queries where you MUST run your-skill-name:** "Example 1" • "Example 2" • "Example 3"

**YOU MUST:**
- Step 1
- Step 2
- Step 3

**Violations:**
- ❌ Anti-pattern 1
- ❌ Anti-pattern 2

Then sync to project root:

./arsenal/install.sh

---

Step 8: Commit to Arsenal

Skills are part of the arsenal repository, so commit them properly:

# Stage your changes
git add arsenal/dot-claude/skills/YOUR_SKILL_NAME/
git add arsenal/system-prompts/CLAUDE.md  # If you updated it

# Commit with descriptive message
git commit -m "Add YOUR_SKILL_NAME skill for [purpose]

- Provides [key benefit 1]
- Prevents [common mistake]
- Includes [scripts/automation/etc]"

# Push to arsenal (if it's a separate repo)
cd arsenal
git push
cd ..

---

Editing Existing Skills

Workflow

# 1. Edit the skill in arsenal (source of truth)
vim arsenal/dot-claude/skills/EXISTING_SKILL/SKILL.md

# 2. Sync changes to .claude
./arsenal/install.sh

# 3. Test the changes
cat .claude/skills/EXISTING_SKILL/SKILL.md

# 4. Commit to arsenal
git add arsenal/dot-claude/skills/EXISTING_SKILL/
git commit -m "Update EXISTING_SKILL: [what changed]"

Common Edits

Adding a new step:

• Insert it in the SKILL.md with clear numbering
• Update any "Success Criteria" checklists
• Test that the new step works

Fixing a command:

• Update the command in SKILL.md
• Test it works as expected
• Document in commit message what was broken and how you fixed it

Adding examples:

• Add to "Example queries" section
• Show both good and bad patterns
• Link to real code if relevant

---

Best Practices

Make Skills Mandatory, Not Optional

Good:

**YOU MUST use this skill when:**
- Writing any test code
- BEFORE writing `def test_*`

Bad:

**You might want to consider using this skill if:**
- You feel like it

Provide Clear Success Criteria

Good:

## Success Criteria

You've completed this skill when:
- [ ] All tests in `just test-all-mocked` pass
- [ ] Output shows "✓ 42 passed"
- [ ] No error messages in output

Bad:

You're done when things work.

Show Expected Output

Good:

Run the command:
```bash
just test-unit

Expected output:

============================= test session starts ==============================
collected 42 items

tests/unit/test_foo.py ..................                            [ 42%]
tests/unit/test_bar.py ........................                       [100%]

============================== 42 passed in 2.31s ===============================

**Bad:**
```markdown
Run `just test-unit` and check if it works.

Document Common Violations

Every skill should have a "Violations" or "Common Mistakes" section:

## Common Violations

- ❌ **BANNED:** Running tests without `just ruff` first
  - **Why:** Formatting errors cause test failures
  - **Fix:** Always run `just ruff` before testing

- ❌ **CRITICAL:** Saying "all tests pass" without running parallel suite
  - **Why:** Misleads user about code quality
  - **Fix:** Run `.claude/skills/test-runner/scripts/run_tests_parallel.sh`

---

Anti-Patterns to Avoid

Anti-Pattern 1: Editing .claude Directly

WRONG:

# ❌ DON'T DO THIS
vim .claude/skills/test-writer/SKILL.md
git add .claude/

RIGHT:

# ✅ DO THIS
vim arsenal/dot-claude/skills/test-writer/SKILL.md
./arsenal/install.sh
git add arsenal/

Why: .claude/ is a copy created by install.sh. Changes will be overwritten.

Anti-Pattern 2: Creating Skills in Project Root

WRONG:

# ❌ DON'T DO THIS
mkdir .claude/skills/my-new-skill

RIGHT:

# ✅ DO THIS
mkdir arsenal/dot-claude/skills/my-new-skill
./arsenal/install.sh

Anti-Pattern 3: Vague Trigger Conditions

WRONG:

Use this skill when you need to test stuff.

RIGHT:

Use this skill when:
- ✅ User asks "write tests for X"
- ✅ You're creating a new `test_*.py` file
- ✅ You're about to write `def test_*`
- ✅ User says "add test coverage"

Anti-Pattern 4: Missing Automation

If users run the same commands repeatedly, create a script:

WRONG:

1. Run `cd api && just lint-and-fix`
2. Run `cd api && just test-all-mocked`
3. Check all outputs for failures

RIGHT:

1. Run the automated script:
```bash
.claude/skills/test-runner/scripts/run_tests_parallel.sh

2. Check the log files for results:

cat test-results/*.log

---

## Skill Lifecycle

### Development Cycle

1. Identify need ↓
2. Create skill in arsenal/dot-claude/skills/ ↓
3. Run ./arsenal/install.sh ↓
4. Test skill manually ↓
5. Refine based on testing ↓
6. Add to CLAUDE.md skill registry ↓
7. Run ./arsenal/install.sh again ↓
8. Commit to arsenal

### Update Cycle

1. Edit skill in arsenal/dot-claude/skills/ ↓
2. Run ./arsenal/install.sh ↓
3. Test changes ↓
4. Commit to arsenal

---

## Environment Configuration

Some skills need environment variables. Handle them properly:

### Create .env.example in Skill Directory

```bash
cat > arsenal/dot-claude/skills/YOUR_SKILL_NAME/.env.example << 'EOF'
# Environment variables for YOUR_SKILL_NAME skill
API_KEY=your-api-key-here
API_ENDPOINT=https://api.example.com
EOF

Document in SKILL.md

## Setup

### Environment Variables

Create a `.env` file in the skill directory:

```bash
cp .claude/skills/YOUR_SKILL_NAME/.env.example .claude/skills/YOUR_SKILL_NAME/.env

Edit .env and add your credentials:

API_KEY=sk-your-real-key
API_ENDPOINT=https://api.example.com

Security: Never commit real API keys to git!

### Load Environment in Scripts

```bash
#!/bin/bash
set -e

# Load environment variables
SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
if [ -f "$SKILL_DIR/.env" ]; then
    set -a
    source "$SKILL_DIR/.env"
    set +a
fi

# Your script logic here

---

Self-Improvement Loop: Learning from Experience

Core Principle: Skills should evolve based on real-world usage. You can improve yourself by reading, thinking, and writing down what you learned.

When to Improve Skills

Improve a skill when you observe:

1. Repeated violations - You or other agents keep making the same mistake
2. New edge cases - A scenario the skill doesn't cover
3. Unclear instructions - You had to guess or ask for clarification
4. Missing automation - You ran the same commands manually multiple times
5. User confusion - User asks "why did you do X?" and the skill doesn't explain it

The Self-Improvement Workflow

1. Observe a pattern or problem
   ↓
2. Read the relevant skill
   ↓
3. Think about what's missing or unclear
   ↓
4. Write down the improvement
   ↓
5. Test the improved skill
   ↓
6. Commit the improvement to arsenal

Pattern 1: Learning from Violations

When you catch yourself (or observe another agent) violating a skill:

# 1. Document what happened
# Create a file or note describing the violation
cat > /tmp/violation_note.md << 'EOF'
## Violation Observed
- **Skill:** test-writer
- **What happened:** Started writing tests without reading the skill
- **Why:** User said "write tests" and I jumped straight to code
- **Consequence:** Wrote brittle tests with hardcoded outputs
EOF

# 2. Read the skill to understand what should have happened
cat .claude/skills/test-writer/SKILL.md

# 3. Think: What would have prevented this?
# - Clearer trigger conditions?
# - Stronger "BANNED" language?
# - More examples of when to use?

# 4. Improve the skill in arsenal
vim arsenal/dot-claude/skills/test-writer/SKILL.md
# Add: "❌ BANNED: Writing tests without reading test-writer skill first"
# Add: More trigger examples

# 5. Sync and test
./arsenal/install.sh
cat .claude/skills/test-writer/SKILL.md | grep -A 5 "BANNED"

# 6. Commit
git add arsenal/dot-claude/skills/test-writer/SKILL.md
git commit -m "Strengthen test-writer: add explicit trigger for 'write tests' query"

Pattern 2: Extracting Lessons from Past Conversations

When you notice recurring patterns or learn something new:

## Example: Learning from a Debug Session

**Observation:**
User asked "Why didn't this intervention fire?" I read code and explained the logic,
but was wrong. The actual reason (found later in Langfuse traces) was different.

**Lesson:**
Production debugging requires actual data, not code reading.

**Action:**
1. Read langfuse-prompt-and-trace-debugger skill
2. Identify gap: No guidance on "when code reading is insufficient"
3. Add pressure test: "Production Debugging Without Data"
4. Add to skill: "Code shows what SHOULD happen. Traces show what DID happen."

Implementation:

# Edit the skill in arsenal
vim arsenal/dot-claude/skills/langfuse-prompt-and-trace-debugger/SKILL.md

# Add new section
cat >> arsenal/dot-claude/skills/langfuse-prompt-and-trace-debugger/SKILL.md << 'EOF'

## When Code Reading Is Insufficient

❌ **WRONG:** "Let me read the intervention logic to explain why it didn't fire..."
✅ **RIGHT:** "Let me fetch the actual trace to see what happened in production..."

**Why:**
- Code shows intent (what should happen)
- Traces show reality (what did happen)
- Reality often differs due to: null values, timing, errors, config mismatches
EOF

# Sync and commit
./arsenal/install.sh
git add arsenal/dot-claude/skills/langfuse-prompt-and-trace-debugger/
git commit -m "Add guidance: code vs traces for production debugging"

Pattern 3: Creating New Skills from Discovered Patterns

When you notice you're doing the same task repeatedly without a skill:

## Example: Repeated Database Migration Pattern

**Observation:**
Over 5 conversations, you ran similar commands:
1. Check current migration: `alembic current`
2. Generate migration: `alembic revision --autogenerate -m "..."`
3. Review migration: `cat alembic/versions/XXXX_*.py`
4. Apply migration: `alembic upgrade head`
5. Verify: `alembic current`

**Pattern Recognition:**
This is a repeated workflow that could be a skill.

**Action:**
Create database-migration-runner skill.

Implementation:

# 1. Create skill directory
mkdir -p arsenal/dot-claude/skills/database-migration-runner

# 2. Create SKILL.md
cat > arsenal/dot-claude/skills/database-migration-runner/SKILL.md << 'EOF'
---
name: database-migration-runner
description: Safe workflow for generating and applying Alembic database migrations
---

# database-migration-runner Skill

## Purpose
Provides a safe, tested workflow for database schema changes.

## When to Use
- User asks to "create migration" or "update database schema"
- Models in `api/src/models/` have changed
- New tables or columns needed

## Workflow

### Step 1: Check Current State
```bash
cd api
alembic current

Step 2: Generate Migration

alembic revision --autogenerate -m "Description of changes"

Step 3: Review Generated Migration

# Find the newest migration file
ls -t alembic/versions/ | head -1
cat alembic/versions/XXXX_*.py

# Check for:
- Correct table/column changes
- No accidental drops
- Proper indexes

Step 4: Apply Migration

alembic upgrade head

Step 5: Verify

alembic current  # Should show new migration

Violations

• ❌ Applying migrations without reviewing
• ❌ Not checking current state first
• ❌ Assuming autogenerate is always correct EOF

3. Create automation script

mkdir -p arsenal/dot-claude/skills/database-migration-runner/scripts cat > arsenal/dot-claude/skills/database-migration-runner/scripts/safe_migrate.sh << 'EOF' #!/bin/bash set -e

echo "Step 1: Current state" alembic current

echo -e "\nStep 2: Generating migration" alembic revision --autogenerate -m "$1"

LATEST=$(ls -t alembic/versions/*.py | head -1) echo -e "\nStep 3: Review generated migration" echo "File: $LATEST" cat "$LATEST"

read -p "Apply this migration? [y/N]: " -n 1 -r echo if [[ $REPLY =~ ^[Yy]$ ]]; then echo -e "\nStep 4: Applying migration" alembic upgrade head

echo -e "\nStep 5: Verification"
alembic current
echo "✓ Migration applied successfully"

else echo "Migration not applied. Review and apply manually." fi EOF chmod +x arsenal/dot-claude/skills/database-migration-runner/scripts/safe_migrate.sh

4. Sync to .claude

./arsenal/install.sh

5. Update CLAUDE.md skill registry

vim arsenal/system-prompts/CLAUDE.md

Add database-migration-runner to skill list

6. Commit

git add arsenal/dot-claude/skills/database-migration-runner/ git add arsenal/system-prompts/CLAUDE.md git commit -m "Add database-migration-runner skill from repeated pattern"

### Pattern 4: Mining Past Conversations

**When user provides conversation history or logs:**

```bash
# User says: "Here are my last 50 Claude conversations. Find patterns we should codify."

# 1. Analyze for repeated questions
grep -h "^user:" conversations/*.md | sort | uniq -c | sort -rn | head -20

# 2. Analyze for repeated commands
grep -h "```bash" conversations/*.md | sed 's/```bash//' | sort | uniq -c | sort -rn

# 3. Identify skill gaps
# Look for:
# - Questions you answered multiple times (→ skill or documentation)
# - Commands run repeatedly (→ automation script)
# - Mistakes made multiple times (→ stronger BANNED section)
# - Edge cases not covered (→ add to existing skill)

# 4. Extract top 5 lessons
cat > /tmp/lessons_learned.md << 'EOF'
## Lessons from Past 50 Conversations

1. **Repeatedly forgot to run install.sh after editing arsenal**
   → Add to skill-writer: explicit reminder in workflow

2. **Multiple times: edited .claude/ directly when urgent**
   → Add pressure test: "Direct Edit Temptation"

3. **Often guessed at Langfuse schemas instead of fetching**
   → Strengthen langfuse skill: make fetching mandatory

4. **Several times: said "tests pass" without running full suite**
   → Already covered in test-runner, but needs emphasis

5. **Pattern: database migrations done manually 10+ times**
   → Create database-migration-runner skill
EOF

# 5. Implement top improvements
# Process each lesson using the patterns above

Pattern 5: Iterative Skill Improvement

Skills should evolve through multiple iterations:

## Example: test-writer Skill Evolution

### Version 1 (Initial)
- Basic structure: "Follow these steps when writing tests"
- Problem: Agents still wrote brittle tests

### Version 2 (After violations observed)
- Added: "❌ BANNED: Hardcoding library outputs"
- Added: Examples of brittle vs robust tests
- Result: Fewer brittle tests, but fixture misuse increased

### Version 3 (After fixture problems)
- Added: "Fixture Decision Tree: When to use vs when to inline"
- Added: Factory pattern examples
- Result: Better fixtures, but still testing library behavior

### Version 4 (After contract confusion)
- Added: "The Golden Rule: What business requirement does this test protect?"
- Added: Contract vs implementation testing examples
- Result: Tests now focus on contracts

### Version 5 (After modification issues)
- Added: "TEST CONTRACT CHANGED:" mandatory format
- Added: Guidance on code broke vs contract changed
- Result: Test modifications are now explicit and justified

Implementation of iterative improvement:

# After each violation or learning, update the skill
vim arsenal/dot-claude/skills/test-writer/SKILL.md
# Add learned lesson to appropriate section

./arsenal/install.sh

# Document what changed
git add arsenal/dot-claude/skills/test-writer/SKILL.md
git commit -m "test-writer v5: add TEST CONTRACT CHANGED format

Observed agents modifying test assertions to make broken code pass.
Added mandatory format that forces explicit justification.
Prevents the #1 cardinal sin: weakening tests to hide bugs."

Success Metrics for Self-Improvement

You're successfully self-improving when:

1. Violations decrease - Same mistake isn't repeated across conversations
2. Skills get more specific - Vague "be careful" becomes specific "❌ BANNED: X"
3. Automation increases - Manual commands become scripts
4. Coverage expands - Edge cases get documented after you encounter them
5. Clarity improves - Users ask fewer clarifying questions about what to do

Anti-Patterns in Self-Improvement

❌ DON'T:

• Add improvements to .claude/ (use arsenal)
• Make skills longer without making them clearer
• Add every edge case (focus on common patterns)
• Improve based on one incident (wait for patterns)
• Skip testing improved skills

✅ DO:

• Edit arsenal, sync with install.sh
• Make skills more specific and actionable
• Focus on violations that repeat 3+ times
• Extract generalizable lessons from specific incidents
• Test improved skills on realistic scenarios

---

Success Criteria

You've mastered skill development when:

• You understand that arsenal/dot-claude is the source of truth
• You know how to create a new skill directory
• You can write a clear SKILL.md with steps and examples
• You know when to add scripts vs inline commands
• You run ./arsenal/install.sh after every change
• You test skills before committing
• You document skills in CLAUDE.md
• You commit changes to arsenal, not .claude

---

Quick Reference

# Create new skill
mkdir -p arsenal/dot-claude/skills/SKILL_NAME
vim arsenal/dot-claude/skills/SKILL_NAME/SKILL.md

# Edit existing skill
vim arsenal/dot-claude/skills/EXISTING_SKILL/SKILL.md

# Sync to .claude
./arsenal/install.sh

# Test skill
cat .claude/skills/SKILL_NAME/SKILL.md
ls .claude/skills/

# Commit to arsenal
git add arsenal/dot-claude/skills/SKILL_NAME/
git commit -m "Add/Update SKILL_NAME skill"

---

Related Skills

• getting-started: Learn how to discover and use skills
• test-writer: Example of a well-structured mandatory skill
• test-runner: Example of a skill with automation scripts

---

Troubleshooting

Skill doesn't appear after install.sh

Cause: Skill directory or SKILL.md missing Solution:

# Check skill exists in arsenal
ls arsenal/dot-claude/skills/YOUR_SKILL_NAME/

# Check SKILL.md exists
ls arsenal/dot-claude/skills/YOUR_SKILL_NAME/SKILL.md

# Re-run install
./arsenal/install.sh

# Verify in .claude
ls .claude/skills/YOUR_SKILL_NAME/

Changes not appearing in .claude

Cause: Edited .claude directly instead of arsenal Solution:

# Discard .claude changes (it's a copy)
rm -rf .claude/skills/YOUR_SKILL_NAME

# Re-run install to restore from arsenal
./arsenal/install.sh

npm install fails during install.sh

Cause: Invalid package.json or missing npm Solution:

# Check package.json syntax
cat arsenal/dot-claude/skills/YOUR_SKILL_NAME/package.json | jq .

# Install dependencies manually
cd arsenal/dot-claude/skills/YOUR_SKILL_NAME
npm install

# Re-run install.sh
cd /path/to/project
./arsenal/install.sh