Claude Code Skills: Coding Workflow Guide
What Are Claude Code Skills?
Claude Code Skills are folders of instructions, scripts, and resources that Claude Code loads dynamically to improve how it handles specific coding tasks. They work directly in your terminal — Claude scans available skills at session start, loads them when relevant, and follows their instructions to produce better, more consistent results.
Skills were introduced by Anthropic in October 2025. In Claude Code specifically, skills integrate with the CLI, subagents, plugins, and MCP servers to form a powerful automation layer for developer workflows.
What makes Claude Code Skills different from Claude.ai Skills:
How to Set Up Claude Code Skills
Getting skills into Claude Code takes less than a minute. Three installation paths depending on your scope.
Personal Skills (Global)
Skills that apply to all your projects. Place them in your home directory:
~/.claude/skills/ ├── my-code-review/ │ └── SKILL.md ├── my-changelog/ │ └── SKILL.md └── my-testing/ ├── SKILL.md └── scripts/ └── run-tests.sh
Project Skills (Local)
Skills scoped to a specific project. Place them in the project root:
your-project/ ├── .claude/ │ └── skills/ │ └── project-conventions/ │ └── SKILL.md ├── src/ └── package.json
Skills in .claude/skills/ within additional directories (--add-dir) are also loaded automatically.
Plugin Marketplace
Install pre-built skills from Anthropic's plugin marketplace (launched December 2025 with 36 curated plugins):
# Install a plugin containing skills /plugin install document-skills@anthropic-agent-skills # List available skills /skills
Verify Installation
Run /skills inside a Claude Code session to see all loaded skills, their source (personal, project, or plugin), and their status.
Claude Code Skill Format — Anatomy of a SKILL.md
Every skill starts with a SKILL.md file. Here's the complete format with Claude Code-specific features.
Basic Structure
--- name: my-skill-name description: What this skill does and when Claude should use it --- # My Skill Name ## Instructions [Step-by-step guidance for Claude to follow] ## Examples [Concrete usage examples] ## Guidelines [Constraints and best practices]
Claude Code-Specific Frontmatter
Claude Code supports additional frontmatter fields beyond the basics:
--- name: pr-summary description: Summarize changes in a pull request context: fork agent: Explore allowed-tools: Bash(gh *) ---
Shell Command Preprocessing
Claude Code skills support the !command syntax — shell commands that execute before the skill content is sent to Claude. The output replaces the placeholder, so Claude receives real data, not the command.
markdown
## Pull request context - PR diff: !`gh pr diff` - PR comments: !`gh pr view --comments` - Changed files: !`gh pr diff --name-only` ## Your task Summarize this pull request...
Claude receives the fully-rendered prompt with actual PR data. This is preprocessing, not something Claude executes — Claude only sees the final result.
Extended Thinking
To enable extended thinking (deep reasoning) in a skill, include the word ultrathink anywhere in your skill content.
Token Budget
Skill description character budget scales with context window — approximately 2% of the available context. Users with larger context windows can load more skill descriptions without truncation.
Advanced Claude Code Skills Patterns
Once you have the basics down, these patterns unlock serious workflow power.
Skills + Subagents
Subagents are specialized Claude instances with their own context windows. Combine them with skills for domain-specific automation:
--- name: reviewer description: Use for thorough code reviews model: sonnet color: orange --- You are an expert code reviewer. Focus on security, performance, and maintainability.
The skill tells Claude what to do. The subagent gives it a focused persona and model to do it with.
Skills + MCP Servers
MCP provides tool access. Skills provide the workflow knowledge on top. Together they enable complex integrations:
| Aspect | Claude.ai Skills | Claude Code Skills |
|---|---|---|
| Environment | Web-based chat with code execution sandbox | Terminal with full filesystem, git, and shell access |
| Installation | Upload ZIP via Settings | Drop into ~/.claude/skills/ or .claude/skills/ |
| Distribution | Manual upload per user | Version control, plugins, plugin marketplace |
| Capabilities | Sandboxed code execution | Full shell access, git worktrees, MCP integrations |
| Shell Commands | Not supported | !command syntax for live data preprocessing |
| Subagents | Not available | Skills can be combined with specialized subagents |
| Network Access | Limited/configurable | Full network access (same as local environment) |
Skills in Plugins
Package skills for distribution via the plugin system:
my-plugin/ ├── .claude-plugin/ │ └── plugin.json ├── skills/ │ └── my-skill/ │ └── SKILL.md ├── commands/ ├── agents/ ├── hooks/ └── .mcp.json
Plugins can bundle skills alongside custom commands, subagents, hooks, and MCP server configs — making them the most powerful distribution unit in Claude Code.Best Practices for Claude Code Skills
Lessons from early adopters, Anthropic's internal teams, and the Verdent community.
Claude Code Skills + Verdent: Parallel Skill-Powered Workflows
Verdent's multi-agent architecture takes Claude Code Skills further — run multiple skill-powered tasks in parallel, across isolated workspaces, with full planning and review.
| Field | Purpose |
|---|---|
| name | Unique identifier for the skill |
| description | What the skill does + when to use it (appears in Claude's system prompt — keep it tight) |
| context | Execution context — fork runs in an isolated context |
| agent | Which subagent to use (e.g., Explore for read-only tasks) |
| allowed-tools | Restrict which tools the skill can invoke (e.g., Bash(gh *) limits to GitHub CLI commands) |
| Pattern | MCP Provides | Skill Provides |
|---|---|---|
| Sentry Bug Fixing | Error data from Sentry API | Workflow for analyzing, reproducing, and fixing detected bugs |
| Jira Sprint Planning | Ticket data from Jira API | Your team's sprint planning methodology and estimation standards |
| Database Migration | Database schema access | Your organization's migration conventions and safety checks |
| Practice | Why It Matters |
|---|---|
| Write the description first | The frontmatter description determines if Claude loads the skill. A vague description means the skill never fires. A clear one with trigger phrases ("Use when user says 'review PR'") ensures reliable activation |
| One skill, one job | Keep each skill focused on a single task area. Composability beats complexity — Claude can load multiple skills simultaneously |
| Use concrete examples | Abstract instructions lead to inconsistent output. Show Claude exactly what good input and output look like |
| Preprocess with !command | Fetch live data (git diffs, API responses, file contents) before Claude sees the prompt. This grounds the skill in real context, not assumptions |
| Scope allowed-tools | Use allowed-tools to restrict what the skill can do. This prevents accidental side effects and makes skills safer to share |
| Test with varied prompts | Don't just test the happy path. Try ambiguous requests, edge cases, and unrelated prompts to make sure the skill loads when it should and stays silent when it shouldn't |
| Version control your skills | Store skills in your project repo. Share via Git, review changes in PRs, and maintain a changelog — just like any other code |
| Combine with CLAUDE.md | CLAUDE.md provides project-wide context. Skills provide task-specific procedures. Use both: CLAUDE.md for "what this project is" and skills for "how to do X in this project" |
| Verdent Feature | How It Enhances Skills |
|---|---|
| Parallel Agents | Run a code review skill, a test generation skill, and a documentation skill simultaneously — each in its own agent, zero conflicts |
| Isolated Workspaces | Every agent operates in its own git worktree. Skill-driven changes stay separate until you review and merge |
| Planning Mode | Before any skill fires, Verdent helps you shape the task into a clear plan — so the skill gets the right input from the start |
| Diff Review | See exactly what each skill-powered agent changed, with highlighted diffs and summaries, before you confirm anything |
| Task Dashboard | Track all active skill-powered tasks across projects in one view — see progress, review outputs, and merge results |