Claude Code Skills: The Power Feature Most Teams Are Ignoring

Most teams using Claude Code are leaving its most powerful feature completely untouched. They use it to write functions, debug errors, and generate boilerplate, all valid use cases, but all scratching the surface.

Skills change the game. They let you give Claude persistent, reusable instructions that transform it from a generic coding assistant into an opinionated team member that knows your architecture, your conventions, and your workflow, and follows them every single time.

What Are Skills?

A Skill is a markdown file, specifically a SKILL.md) that gives Claude a structured set of instructions it loads before executing a task. Think of it as a run-book for Claude: when you invoke a skill, Claude reads the file and follows it like a senior engineer following an internal playbook.

Skills live in your project's .claude/skills/ directory (or in ~/.claude/skills/ for global skills). Each one is a self-contained unit that Claude can invoke by name, via slash commands, or automatically when it detects a matching task.

The SKILL.md Format

Every skill file follows the same basic structure: YAML frontmatter at the top, followed by markdown instructions in the body.

---
name: my-skill
description: A concise description of what this skill does
trigger: invocation
---

# My Skill

Instructions for Claude go here. You can use full markdown:

## Step 1
Do this first.

## Step 2
Then do this.

```typescript
// You can include code examples Claude should follow
const example = "Claude will use this as a reference"
```

The frontmatter configures how the skill gets activated. The body tells Claude what to do once it's loaded. Simple as that.

Frontmatter Fields

The frontmatter is where you control the skill's identity and behavior. Here are the key fields:

Directory Structure

Skills can live in two places: project-local or global.

your-project/
├── .claude/
│   └── skills/
│       ├── pr-review/
│       │   ├── SKILL.md
│       │   └── templates/
│       │       └── review-checklist.md
│       ├── deploy/
│       │   └── SKILL.md
│       └── migration/
│           ├── SKILL.md
│           └── scripts/
│               └── validate.sh

~/.claude/
└── skills/
    └── global-formatting/
        └── SKILL.md

Each skill gets its own directory. The SKILL.md file is required. Everything else is optional supporting files that your skill instructions can reference. Claude can read any file in the skill directory during execution.

Building a PR Review Skill: Step by Step

Let's build something real. Say your team has specific PR review standards: you want Claude to check for breaking changes, verify test coverage, enforce naming conventions, and flag security concerns. Here's how you'd encode that into a skill.

Step 1: Create the Directory

mkdir -p .claude/skills/pr-review
touch .claude/skills/pr-review/SKILL.md

Step 2: Write the Frontmatter

---
name: pr-review
description: >
  Review pull requests against our team standards. Checks for
  breaking changes, test coverage, naming conventions, security
  issues, and documentation completeness.
trigger: invocation
---

Step 3: Write the Instructions

This is where you encode your team's actual standards. Be specific. Claude follows instructions better when they're concrete rather than abstract.

# PR Review Skill

When reviewing a PR, follow this exact checklist:

## 1. Breaking Changes
- Check all modified function signatures for parameter changes
- Look for renamed or removed exports
- Verify database migration compatibility
- Flag any changes to public API contracts

## 2. Test Coverage
- Every new function MUST have at least one unit test
- Modified functions must have updated tests
- Integration tests required for any new API endpoint
- If test coverage drops below 80%, flag it as blocking

## 3. Naming Conventions
- Functions: camelCase
- Components: PascalCase
- Constants: SCREAMING_SNAKE_CASE
- Files: kebab-case for utilities, PascalCase for components
- Database columns: snake_case

## 4. Security Review
- No hardcoded secrets, tokens, or API keys
- All user input must be validated/sanitized
- SQL queries must use parameterized statements
- Check for exposed internal endpoints

## 5. Output Format
Produce a structured review with:
- **Summary**: One paragraph overview
- **Blocking Issues**: Must fix before merge
- **Suggestions**: Nice to have improvements
- **Approval Status**: APPROVE, REQUEST_CHANGES, or NEEDS_DISCUSSION

Step 4: Use It

Invoke the skill from Claude Code with a slash command:

/pr-review

# Or with context:
Review the PR at #142 using the pr-review skill

Advanced Patterns

Once you're comfortable with basic skills, these patterns unlock serious power.

Invocation Control

You can control exactly when skills fire. Setting trigger: automatic lets Claude decide when the skill is relevant based on the description field. This is great for skills like "always format SQL migrations this way" , you want it to fire without remembering to invoke it.

---
name: auto-migration-format
description: >
  Automatically formats SQL migration files with proper headers,
  rollback scripts, and version tracking. Triggers whenever the
  user creates or modifies a file in the migrations/ directory.
trigger: automatic
---

# Migration Formatting

When you detect a SQL migration file being created or modified:

1. Add a header comment with timestamp and description
2. Ensure UP and DOWN migrations are both present
3. Add a version number following semver
4. Validate SQL syntax before saving

Dynamic Context Loading

Skills can reference other files in their directory. This lets you keep templates, examples, and reference docs alongside the skill.

.claude/skills/api-endpoint/
├── SKILL.md
├── templates/
│   ├── controller.ts.template
│   ├── service.ts.template
│   └── test.ts.template
└── examples/
    └── user-endpoint.ts

In your SKILL.md, tell Claude to read these files:

When creating a new API endpoint, read the templates in
./templates/ and follow their structure exactly. Reference
./examples/user-endpoint.ts as a working example.

Subagent Execution

For complex multi-step skills, you can instruct Claude to spawn subagents, separate Claude instances that handle parts of the task in parallel. This is especially useful for skills that need to analyze multiple files or run multiple checks simultaneously.

# Full Codebase Audit

Execute the following checks in parallel using subagents:

1. **Security Audit**: Spawn a subagent to scan for vulnerabilities
2. **Performance Check**: Spawn a subagent to identify N+1 queries
   and unnecessary re-renders
3. **Style Compliance**: Spawn a subagent to verify code style
4. **Dependency Audit**: Spawn a subagent to check for outdated
   or vulnerable dependencies

Collect all results and produce a unified report.

Tool Restriction

The allowed_tools field lets you sandbox what Claude can do during a skill. This is critical for safety: a "review only" skill shouldn't be able to write files.

---
name: read-only-review
description: Review code without making any changes
trigger: invocation
allowed_tools:
  - read
  - grep
  - glob
---

# Read-Only Code Review

Analyze the codebase and provide recommendations.
DO NOT modify any files. This is a review-only skill.

Script Bundling

Skills can include shell scripts that Claude executes as part of the workflow. Bundle validation scripts, build scripts, or test runners alongside the skill.

---
name: deploy
description: Deploy the current branch to staging or production
trigger: invocation
---

# Deployment Skill

Before deploying, run the validation script:

```bash
bash .claude/skills/deploy/scripts/pre-deploy-check.sh
```

If validation passes, proceed with deployment.
If it fails, report the errors and stop.

String Substitutions

You can use dynamic placeholders in your skill instructions that Claude resolves at runtime. Reference the current branch, file paths, user input, and other context variables to make skills adaptable.

What This Means for Your Team

Skills are the difference between "we use Claude Code" and "Claude Code is an integrated part of our engineering process." They encode institutional knowledge in a format that's version-controlled, shareable, and consistently executed.

Teams that invest in skills see dramatic improvements in consistency. Code reviews follow the same rubric. Migrations follow the same format. New endpoints match existing patterns. The AI isn't guessing what your team prefers. It knows, because you told it.

Start small. Pick the one workflow where your team wastes the most time explaining conventions, and encode it as a skill. Once you see the results, you'll want to encode everything.