Supercharging Your Workflow with Claude Code Skills

Teaching Your AI Coding Partner New Tricks

Claude Code is Anthropic's agentic coding tool that lives in your terminal. It reads your codebase, edits files, runs commands, and handles git workflows through natural language. But its real power emerges when you teach it how your team works — through skills.

Skills are markdown-based playbooks that extend what Claude Code can do. Instead of explaining the same workflow every session — how to deploy, how to write commit messages, how to review PRs — you write it once as a skill, and Claude follows it consistently. With over 77,000 GitHub stars and adoption across the developer community, Claude Code has become a central tool in many development workflows. In this post, we’ll explore how skills work, how to create your own, and the patterns that make them effective.

What Is Claude Code?

Before diving into skills, let’s establish what Claude Code brings to the table. It’s an agentic coding assistant that operates directly in your terminal. Start it in any project directory:

claude

From there, you interact through natural language. Ask it to refactor a function, fix a bug, explain a piece of code, or create a pull request. What makes it “agentic” is that it doesn’t just suggest — it acts. A single request can trigger dozens of independent tool calls: reading files, searching code, editing multiple files, running tests, and committing changes.

Key capabilities include:

• Full codebase understanding: Claude reads and navigates your entire project, understanding relationships between files, modules, and dependencies.
• Multi-file editing: Changes span as many files as needed. Rename a component and Claude updates every import.
• Terminal execution: Runs build commands, tests, linters, and any shell command your workflow requires.
• Git integration: Stages changes, writes commit messages following your conventions, creates branches, and opens pull requests.
• Multi-agent workflows: Spawns parallel agents for large tasks, with a lead agent coordinating the work.
• IDE integration: Available in VS Code, JetBrains IDEs, and as a standalone desktop app — in addition to the terminal.

Claude Code also reads CLAUDE.md files at the start of every session. These project-level configuration files tell Claude about your architecture, coding standards, build commands, and conventions. Think of CLAUDE.md as the persistent context and skills as the on-demand playbooks.

Understanding Skills

Skills are the mechanism for teaching Claude Code how to handle specific tasks. Each skill is a directory containing a SKILL.md file — a markdown document with frontmatter metadata and natural language instructions.

The key insight is how skills are loaded. At startup, Claude only reads the name and description of each available skill. The full instructions are loaded into context only when a skill is actually invoked. This progressive disclosure keeps context usage efficient — you can have dozens of skills installed without paying a context cost for all of them.

Skills can be invoked two ways:

1. Directly by typing /skill-name in the conversation
2. Automatically by Claude when it determines a skill is relevant based on its description

This dual invocation model means skills can serve as both explicit commands and background knowledge that Claude draws on when appropriate.

Where Skills Live

Skills can be defined at three levels, each scoped differently:

Personal skills are great for workflow preferences that follow you across projects — your preferred commit message format, your code explanation style, your deployment checklist. Project skills encode team conventions — API patterns, testing requirements, review processes — and are committed to version control so every team member benefits.

In monorepo setups, Claude automatically discovers skills from nested .claude/skills/ directories when you work in subdirectories. A packages/frontend/.claude/skills/ directory is picked up when you’re working in that package.

The Skill File Format

A skill is a directory with at minimum a SKILL.md file. The file uses YAML frontmatter followed by markdown instructions:

---
name: review-component
description: Reviews React components for accessibility, performance,
  and adherence to project conventions. Use when reviewing PRs or
  checking component quality.
---

When reviewing a React component, check the following areas:

## Accessibility
- All interactive elements have appropriate ARIA attributes
- Images have alt text
- Color is not the only means of conveying information
- Keyboard navigation works correctly

## Performance
- No unnecessary re-renders (check dependency arrays)
- Large lists use virtualization
- Images are optimized and lazy-loaded

## Conventions
- Component uses TypeScript with proper prop types
- Follows the project's naming conventions
- Uses Tailwind utility classes (no inline styles)
- Tests cover the main interaction paths

Provide specific line references for any issues found.

Frontmatter Fields

The frontmatter controls how the skill behaves:

---
name: deploy-production
description: Deploys the application to production. Runs tests,
  builds the Docker image, and pushes to the container registry.
disable-model-invocation: true
user-invocable: true
allowed-tools: Read, Grep, Glob, Bash
argument-hint: "[environment]"
model: claude-sonnet-4-20250514
---

The most important fields:

• name: The slash command name. Lowercase, numbers, and hyphens only (max 64 characters). Defaults to the directory name if omitted.
• description: What the skill does and when to use it (max 1024 characters). This is what Claude reads at startup to decide relevance, so write it carefully.
• disable-model-invocation: Set to true to prevent Claude from automatically invoking this skill. Essential for skills with side effects like deployments or sending messages.
• user-invocable: Set to false to hide from the / menu. Useful for background skills that Claude invokes on its own.
• allowed-tools: Which tools Claude can use without asking permission during skill execution. Restrict to Read, Grep, Glob for read-only skills.
• argument-hint: Shows during autocomplete to guide usage, like [branch-name] or [issue-number].
• model: Override the model for this skill. Use a faster model for simple tasks, a more capable one for complex analysis.

The invocation control matrix gives you fine-grained control:

String Substitutions and Dynamic Context

Skills support variable substitution for arguments passed during invocation:

---
name: fix-issue
description: Reads a GitHub issue and implements the fix
argument-hint: "[issue-number]"
---

## Issue Context
Read GitHub issue #$ARGUMENTS and understand the problem.

## Implementation
1. Find the relevant code
2. Implement the fix
3. Write tests
4. Create a commit with message: "fix: resolve #$ARGUMENTS"

Invoking /fix-issue 42 replaces $ARGUMENTS with 42 throughout the skill.

For more powerful context injection, skills support the !`command` syntax, which runs shell commands before the skill content is sent to Claude. The command output replaces the placeholder:

---
name: pr-summary
description: Summarizes the current pull request
context: fork
agent: Explore
---

## Pull Request Context
- Changed files: !`gh pr diff --name-only`
- PR description: !`gh pr view --json body -q .body`
- Review comments: !`gh api repos/{owner}/{repo}/pulls/{number}/comments`

## Task
Summarize this pull request. Focus on:
1. What changed and why
2. Any concerns raised in review comments
3. Suggested improvements

This is incredibly powerful. The skill dynamically fetches live data — the actual PR diff, comments, and description — and hands it to Claude as context. Every invocation works with current data, not stale instructions.

Subagent Execution

For tasks that benefit from isolation, skills can run in a forked context:

---
name: deep-research
description: Performs thorough codebase research on a topic
context: fork
agent: Explore
---

Research the following topic in this codebase: $ARGUMENTS

Trace through all relevant code paths. Map the architecture.
Identify patterns, abstractions, and dependencies.
Return a comprehensive summary with the 10 most important
files to understand this area of the codebase.

The context: fork setting runs the skill in an isolated subagent. The subagent has access to the codebase and tools but not the conversation history. This prevents research tasks from consuming your main context window.

Built-in agent types include Explore (optimized for codebase navigation), Plan (for architecture design), and general-purpose (full capabilities). You can also define custom agents in .claude/agents/ for specialized workflows.

Skill Directory Structure

While a single SKILL.md is sufficient, skills can include supporting files:

review-security/
├── SKILL.md              # Main instructions
├── owasp-checklist.md    # Reference material
├── examples/
│   ├── good-review.md    # Example of expected output
│   └── bad-review.md     # Example of what to avoid
└── scripts/
    └── scan.sh           # Script Claude can execute

Reference files provide detailed context that Claude loads as needed. The SKILL.md stays concise with instructions, while owasp-checklist.md contains the full reference. This separation keeps the primary skill lean while making deep knowledge available.

For strict output formatting, use a template file:

<!-- template.md -->
## Security Review: {{component_name}}

### Summary
{{one_paragraph_summary}}

### Findings
{{findings_table}}

### Risk Level
{{low|medium|high|critical}}

### Recommended Actions
{{numbered_action_items}}

Reference the template from your SKILL.md:

Format your output according to the template in template.md.
Fill in all placeholder fields.

Built-in Skills

Claude Code ships with several built-in skills that demonstrate the pattern:

• /simplify: Reviews recently changed files for code reuse, quality, and efficiency. Spawns three parallel review agents and aggregates findings.
• /batch <instruction>: Orchestrates large-scale changes across a codebase. Decomposes work into independent units, spawns background agents in isolated git worktrees, implements changes, runs tests, and opens PRs.
• /loop [interval] <prompt>: Runs a prompt repeatedly on a schedule. Useful for monitoring deploys or polling for status changes.

These bundled skills are good reference implementations for your own skills. They demonstrate patterns like parallel agent spawning, work decomposition, and iterative execution.

Practical Examples

Here are skills that solve common development workflow problems:

Conventional Commits

---
name: commit
description: Creates a conventional commit from staged changes.
  Analyzes the diff, determines the commit type, and writes a
  descriptive message.
disable-model-invocation: true
---

Create a git commit following the Conventional Commits specification.

## Steps
1. Run `git diff --staged` to see what's being committed
2. Analyze the changes to determine the type:
   - `feat`: New feature
   - `fix`: Bug fix
   - `refactor`: Code restructuring
   - `docs`: Documentation only
   - `test`: Adding or updating tests
   - `chore`: Maintenance tasks
3. Write a commit message: `type(scope): description`
   - Scope is the primary area affected (component name, module)
   - Description is imperative mood, lowercase, no period
   - Add a body if the "why" isn't obvious from the diff
4. Include `Co-Authored-By: Claude <noreply@anthropic.com>`
5. Show the message and ask for confirmation before committing

Component Generator

---
name: create-component
description: Generates a new React component with TypeScript,
  tests, and Storybook story following project conventions.
argument-hint: "[ComponentName]"
---

Generate a new React component named `$ARGUMENTS`.

## File Structure
Create these files:
- `src/components/$ARGUMENTS/$ARGUMENTS.tsx`
- `src/components/$ARGUMENTS/$ARGUMENTS.test.tsx`
- `src/components/$ARGUMENTS/$ARGUMENTS.stories.tsx`
- `src/components/$ARGUMENTS/index.ts` (barrel export)

## Component Conventions
- Use TypeScript with an exported Props interface
- Use `forwardRef` for components that render DOM elements
- Use Tailwind CSS for styling (no CSS modules)
- Include JSDoc comment on the Props interface
- Export as named export, not default

## Test Conventions
- Use Vitest and Testing Library
- Test rendering, interaction, and edge cases
- Use `screen` queries, not container queries

## Story Conventions
- Use CSF3 format with `satisfies Meta<typeof Component>`
- Include `tags: ['autodocs']`
- Create stories for: Default, WithProps, EdgeCase

Safe Explorer

---
name: explore
description: Read-only codebase exploration. Use when you want to
  understand code without risk of modifications.
allowed-tools: Read, Grep, Glob
context: fork
agent: Explore
---

Explore this codebase to answer: $ARGUMENTS

You are in read-only mode. Search files, read code, and trace
through execution paths. Do not suggest changes — focus entirely
on understanding and explaining what exists.

Return:
1. A clear explanation of what you found
2. Key files involved (with paths and line numbers)
3. Architecture diagram in ASCII if applicable

CLAUDE.md and Skills: Working Together

CLAUDE.md and skills serve complementary roles. The CLAUDE.md file is loaded into context at the start of every session — it’s the persistent project knowledge. Skills are loaded on demand — they’re the task-specific playbooks.

A well-structured setup looks like:

project/
├── CLAUDE.md                          # Project context (always loaded)
├── .claude/
│   └── skills/
│       ├── commit/SKILL.md            # Commit workflow
│       ├── review-pr/SKILL.md         # PR review process
│       └── create-component/SKILL.md  # Component scaffolding

Your CLAUDE.md defines the “what” — project architecture, coding standards, key commands. Skills define the “how” — step-by-step workflows for specific tasks. When a skill runs, CLAUDE.md is also loaded alongside it, so skills always have project context available.

Generate an initial CLAUDE.md by running /init in Claude Code. It analyzes your codebase and produces a starting point that you can refine over time.

Best Practices

Keep Skills Focused

Each skill should do one thing well. A “deploy-and-notify-and-update-docs” skill should be three separate skills that can be composed. Small, focused skills are easier to test, maintain, and reuse.

Write Descriptions for Discovery

The description is the most important field in your frontmatter. Claude uses it to decide when a skill is relevant, so be specific about both what the skill does and when to use it:

# Bad
description: Helps with components

# Good
description: Generates a new React component with TypeScript,
  tests, and Storybook story. Use when creating new UI components
  or when the user asks to scaffold a component.

Use Progressive Disclosure

Keep SKILL.md under 500 lines. Move detailed reference material to separate files within the skill directory. Structure your content as: metadata (~100 tokens), instructions (<5000 tokens), and resources (loaded as needed). Every token in a skill is a token that can’t be used for reasoning about your code.

Restrict Dangerous Skills

Any skill that has side effects — deploying, sending messages, deleting resources — should set disable-model-invocation: true. This ensures it’s only run when you explicitly type the slash command, not when Claude decides it might be helpful:

---
name: deploy
description: Deploys to production
disable-model-invocation: true
---

Test Across Models

Skills that work well with Claude Opus might need more detail for Sonnet or Haiku. Test your skills across models and adjust the level of instruction detail accordingly. You can even set a specific model per skill using the model field.

Use the Agent Skills Standard

Skills follow the Agent Skills open standard, which works across multiple AI tools including Cursor, Gemini CLI, and Codex CLI. Writing skills to this standard means they’re portable — a skill you write for Claude Code can work in other tools that support the specification.

Conclusion

Skills transform Claude Code from a general-purpose assistant into a tool that knows your team’s specific workflows. The combination of CLAUDE.md for persistent context and skills for on-demand playbooks creates a development environment where Claude understands not just your code, but how your team works with it.

Start small — pick one repetitive workflow you explain to Claude regularly and encode it as a skill. As your skill library grows, you’ll find that the consistency and time savings compound. Every new team member benefits from the same encoded knowledge, and every session starts with Claude already knowing how you work.

The skills system is an open standard, meaning the investment you make in writing skills pays off across tools, not just Claude Code. That portability, combined with the progressive disclosure architecture that keeps context usage efficient, makes skills one of the most practical ways to customize your AI development workflow.

‘Till next time!