Agent Skills

Table of Contents

1. Introduction

Skills are model-invoked capabilities that Claude autonomously uses based on context. Unlike slash commands (user-invoked), skills are automatically activated when relevant to the current situation.

1.1. How Skills Work

  1. Discovery: Claude discovers skills from .claude/skills/*/SKILL.md directories
  2. Context matching: Claude evaluates if a skill's description matches the current context
  3. Automatic activation: When relevant, Claude uses the skill's instructions
  4. Tool execution: Skills execute within their defined allowed-tools

1.2. Skill Structure

Each skill is a directory containing SKILL.md: 

.claude/skills/
├── typescript-types/
│   └── SKILL.md
├── test-coverage/
│   └── SKILL.md
└── emacs-context/
    └── SKILL.md

1.3. Frontmatter Format

---
name: Skill Display Name
description: Clear description of when and how this skill activates
allowed-tools:
  - Read
  - Write
  - Grep
model: "sonnet"  # Optional model override
---

1.4. Writing Good Descriptions

The description is crucial - it determines when the skill activates.

Good descriptions:

  • "Automatically generate TypeScript type definitions from API responses, JSON data, or existing JavaScript code"
  • "Analyze test coverage and suggest missing test cases when code is added or modified"

Bad descriptions:

  • "Types" (too vague)
  • "Does TypeScript stuff" (unclear when to activate)

2. Skill Categories

This directory contains skills organized by category. Each category has its own file for better navigation and maintenance.

2.1. JavaScript/TypeScript Development Skills

JavaScript and TypeScript development skills for modern syntax, type safety, security, and testing.

Includes:

  • JavaScript/TypeScript Conventions Enforcer (✓ tangled)
  • TypeScript Type Generator (✓ tangled)
  • JavaScript/TypeScript Security Checker (✓ tangled)

2.2. Rails Development Skills

Ruby on Rails specific skills for conventions, security, performance, and testing.

Includes:

  • Rails Convention Enforcer (✓ tangled)
  • N+1 Query Detector (example)
  • Rails Security Checker (✓ tangled)
  • Test Coverage Assistant (Rails) (example)
  • Migration Safety Checker (✓ tangled)
  • Rails Upgrade Helper (example)

2.3. Python Development Skills

Python development skills for PEP 8, type safety, testing, security, and common pitfalls.

Includes:

  • Python Conventions Enforcer (✓ tangled)
  • Type Hints Assistant (example)
  • Python Testing Assistant (example)
  • Python Security Checker (✓ tangled)
  • Python Common Pitfalls (example)

2.4. Emacs Integration Skills

Skills that leverage the Emacs MCP server for enhanced context-aware assistance.

Includes:

  • Emacs Context Helper (✓ tangled)

2.5. Documentation Skills

Skills for maintaining and improving documentation quality.

Includes:

  • Documentation Completeness Checker (example)

3. Best Practices for Skills

3.1. Skill Design Principles

3.1.1. Clear Activation Conditions

The description should clearly state when to activate:

  • Specific contexts (working with TypeScript)
  • Specific actions (code is added)
  • Specific problems (missing tests)

3.1.2. Appropriate Tool Access

Only request tools the skill actually needs:

  • More tools = more powerful but also more risky
  • Restrict to minimum necessary
  • Document why each tool is needed

3.1.3. Complementary to Commands

Skills and commands should work together:

  • Commands: User explicitly invokes
  • Skills: Automatic based on context
  • Commands can leverage skills' logic
  • Skills can suggest relevant commands

3.2. Writing Effective Skills

3.2.1. Be Proactive But Not Pushy

Good:

  • "I notice there are no tests for this new function. Would you like me to generate some?"
  • "This code could benefit from TypeScript types. Should I add them?"

Bad:

  • "You MUST add tests now!"
  • "I'm going to fix all your code"

3.2.2. Provide Value Automatically

Skills should:

  • Save time on repetitive tasks
  • Catch issues early
  • Suggest improvements proactively
  • Enhance capabilities without extra effort

3.2.3. Respect User Intent

Don't:

  • Make changes without asking
  • Override user decisions
  • Be overly verbose
  • Activate when not relevant

## Testing Skills

After creating a skill:

  1. Tangle the file to generate .claude/skills/skill-name/SKILL.md
  2. Restart Claude Code to discover the new skill
  3. Create test scenarios that match activation conditions
  4. Verify appropriate activation - not too eager, not too shy
  5. Check tool restrictions - ensure only allowed tools are used
  6. Refine description if activation isn't right

## Skill vs Command Decision

Use a Skill when:

  • Action should happen automatically
  • Context determines relevance
  • Saves user from repetitive invocation
  • Enhances existing workflows

Use a Command when:

  • User should explicitly invoke
  • Action needs user input/confirmation
  • Used occasionally, not continuously
  • Clear start and end point

Use Both when:

  • Skill detects need
  • Skill suggests using a command
  • Command uses skill's logic

Example: Test Coverage

  • Skill: Detects missing tests, suggests adding them
  • Command: /test explicitly generates tests

4. Related Configuration

5. Resources

5.1. General Skills

5.2. JavaScript/TypeScript Development

5.2.1. Official Documentation

5.2.2. TypeScript & Type Safety

5.2.3. JavaScript/TypeScript Testing

5.2.4. JavaScript/TypeScript Security

5.2.5. Code Quality & Formatting

5.2.6. Frameworks & Libraries

5.3. Python Development

5.3.1. Official Python Documentation

5.3.2. Python Testing

5.3.3. Python Security

5.3.4. Python Code Quality

5.3.5. Python Type Hints

5.4. Rails Development

5.4.1. Official Rails Documentation

5.4.2. Rails Security

5.4.3. Rails Performance

5.4.4. Rails Migration Safety

5.4.5. Rails Testing

  • RSpec - Behavior-driven testing framework
  • FactoryBot - Fixture replacement for testing
  • SimpleCov - Code coverage analysis
  • Capybara - Integration testing framework

5.4.6. Rails Conventions

5.4.7. Rails Upgrade Resources