Claude Code Skills

Context

This workshop explores how to create custom Claude Code skills (slash commands) to automate repetitive workflows and encode team knowledge. Skills are markdown files that extend Claude’s capabilities without requiring code changes.

Prerequisites: Claude Code installed, basic CLI familiarity

Part 1: Introduction to Claude Skills

What is a Claude Skill?

A skill is a custom extension that teaches Claude new capabilities. Skills are defined in markdown files and can be invoked:

  • Automatically by Claude when the task matches the skill’s description
  • Manually by you using /skill-name slash commands

Why Use Skills?

Problem How Skills Help
Repeating the same instructions Write once, invoke with /skill-name
Inconsistent output formats Define templates in the skill
Team knowledge in people’s heads Document workflows as reusable skills
Context window bloat Skills load only when needed
Onboarding new team members Skills encode best practices

Where Are Skills Stored?

Location Path Scope
Personal ~/.claude/skills/<skill-name>/SKILL.md All your projects
Project .claude/skills/<skill-name>/SKILL.md Current project only (check into git)

Best practice: Start with personal skills, move to project skills when the team should share them.

Part 2: Anatomy of a Skill

File Structure

~/.claude/skills/
└── my-skill/
    └── SKILL.md           # Main instructions (REQUIRED)

SKILL.md Format

---
name: my-skill
description: What this skill does and when to use it
argument-hint: [optional-arg]
disable-model-invocation: true
---

# My Skill Title

## Instructions

1. Step one
2. Step two
3. Step three

Key Frontmatter Options

Option Purpose Default
name Skill identifier (used with /name) Directory name
description When Claude should use this skill Required
argument-hint Placeholder shown in / menu None
disable-model-invocation Prevent Claude from auto-invoking false

When to Use disable-model-invocation: true

Use this for skills with side effects:

  • Creating issues or PRs
  • Deploying code
  • Modifying production systems
  • Sending notifications

Part 3: Deep Dive - The issue-message Skill

Location: ~/.claude/skills/issue-message/SKILL.md

Skill Structure Analysis

# Issue Message Generator

Generate a well-formatted issue description for the repository's
issue tracker based on user-provided text, a plan file, or a
description of a problem.

## Instructions

1. **Gather input**: The user may provide:
   - A description of a bug or feature request
   - A path to a plan file (e.g., `PLAN_*.md`)
   - A description of work to be done

2. **Check for an issue template**: Look for issue templates...

3. **Generate the issue content**: Based on the user's input...

4. **Issue Title**: Generate a concise, descriptive title...

5. **Format rules**: ...

6. **Present the issue content**: Display in code blocks...

7. **Write to file**: Write to `.git/ISSUE-EDITMSG`...

8. **Inform the user**: Provide the `gh issue create` command...

Key Design Patterns

  1. Multi-step workflow - Numbered steps guide Claude through the process
  2. Conditional logic - “If a template exists… If no template exists…”
  3. Format specification - Examples of expected output format
  4. Integration with tools - Uses gh CLI for GitHub operations
  5. Output location - Writes to .git/ISSUE-EDITMSG (git-ignored temp file)
  6. User control - Presents command but doesn’t auto-execute

Why This Skill Works Well

  • Clear instructions: Each step is explicit
  • Handles variations: Works with or without issue templates
  • Consistent output: Always produces same format
  • Safe: Writes to file, user decides when to create issue
  • Reusable: Works across any GitHub repository

Part 4: Creating Your First Skill

Step 1: Create the Directory

mkdir -p ~/.claude/skills/my-first-skill

Step 2: Create SKILL.md

cat > ~/.claude/skills/my-first-skill/SKILL.md << 'EOF'
---
name: my-first-skill
description: A simple skill that greets the user
---

# My First Skill

When invoked, say hello to the user and tell them something
interesting about the current directory.

1. Greet the user warmly
2. Run `ls -la` to see what's in the current directory
3. Count the files and report the total
4. Mention the most recently modified file
EOF

Step 3: Test the Skill

# In Claude Code, type:
/my-first-skill

Step 4: Iterate

  • Edit SKILL.md to refine behavior
  • Add more steps or change the output format
  • Skills update immediately - no restart needed

Part 5: Skill Ideas

Easy Skills (Good for Workshop Exercise)

Skill Name Purpose Complexity
test-summary Summarize pytest results from a log file Easy
bug-report Generate bug report from error description Easy
env-check Check if test environment is ready Easy
flaky-finder Analyze test history for flaky tests Medium
coverage-report Generate coverage summary for PR Medium

Skill 1: test-summary

---
name: test-summary
description: Summarize pytest test results from a log file
argument-hint: [log-file-path]
---

# Test Summary Generator

Analyze pytest output and create a summary.

## Instructions

1. Read the log file provided as an argument (or find the most recent
   pytest log in the current directory)

2. Extract:
   - Total tests run
   - Passed count
   - Failed count
   - Skipped count
   - Error count
   - Duration

3. For any failures, list:
   - Test name
   - Brief error message (first line of traceback)

4. Present in this format:

## Test Results

| Metric | Count |
|--------|-------|
| Total  | X     |
| Passed | X     |
| Failed | X     |
| Skipped| X     |

### Failures

1. `test_name_here` - Error message
2. ...

Skill 2: bug-report

---
name: bug-report
description: Generate a structured bug report from an error description
argument-hint: [error-description]
disable-model-invocation: true
---

# Bug Report Generator

Create a structured bug report.

## Instructions

1. Ask the user for:
   - What they were trying to do
   - What happened instead
   - Any error messages

2. Generate a bug report with:
   - **Title**: Brief summary (under 60 chars)
   - **Environment**: OS, browser, version (ask if not provided)
   - **Steps to Reproduce**: Numbered list
   - **Expected Behavior**: What should happen
   - **Actual Behavior**: What happened
   - **Error Messages**: Any logs or stack traces
   - **Severity**: Critical/High/Medium/Low (suggest based on impact)

3. Write to `.git/BUG-REPORT.md`

4. Provide: `gh issue create --title "..." --body-file .git/BUG-REPORT.md`

Skill 3: env-check

---
name: env-check
description: Check if test environment is ready for testing
---

# Environment Checker

Verify the test environment is properly configured.

## Instructions

Check the following and report status:

1. **Docker**: Is Docker running? (`docker ps`)
2. **Selenium Grid**: Is grid accessible? (`curl http://localhost:4444/status`)
3. **Environment Variables**: Are these set?
   - `ENVIRONMENT_MAP`
   - `RSP_VERSION`
   - `BOX`
4. **Test Target**: Can we reach the test server?
5. **Dependencies**: Is `pytest` installed? Required browsers?

Present results as:

## Environment Check

| Component | Status | Details |
|-----------|--------|---------|
| Docker    | ✅/❌  | ...     |
| Grid      | ✅/❌  | ...     |
| Env Vars  | ✅/❌  | ...     |
| Target    | ✅/❌  | ...     |

**Ready to test:** Yes/No

Part 6: Hands-On Exercise

Exercise: Build Your Own issue-message Skill

Goal: Create a skill similar to issue-message but customized for your workflow.

Steps:

  1. Create the skill directory:

    mkdir -p ~/.claude/skills/my-issue-creator

  2. Start with a basic template:

    touch ~/.claude/skills/my-issue-creator/SKILL.md

  3. Define the workflow:

    • What input does the user provide?
    • What should Claude look for (templates, context)?
    • What format should the output be?
    • Where should it write the result?
    • What command should it suggest?

  4. Write the SKILL.md following the pattern from Part 3

  5. Test with real scenarios:

    • Create an issue from scratch
    • Create an issue from a plan file
    • Create an issue when a template exists

  6. Iterate based on results

Bonus Challenges

  • Add support for different issue types (bug vs feature)
  • Include automatic label suggestions
  • Add a “severity” field based on keywords
  • Support multiple issue trackers (GitHub, Jira, Linear)

Part 7: Best Practices & Tips

Writing Effective Skills

  1. Be explicit - Don’t assume Claude knows your workflow
  2. Use numbered steps - Makes the process clear and debuggable
  3. Provide examples - Show expected output format
  4. Handle edge cases - “If X, do Y. If no X, do Z.”
  5. Keep it focused - One skill = one job

Common Mistakes

Mistake Better Approach
Vague instructions Specific, numbered steps
No output format Include example output
Auto-executing dangerous commands Write to file, user executes
Too many responsibilities Split into multiple skills
Hardcoded values Use arguments or ask user

Debugging Skills

  • Check / menu to see if skill appears
  • Look at the description - is it clear?
  • Try invoking manually with /skill-name
  • Add “verbose” output steps to trace execution