Building Your First Skill
We will build a code review skill from scratch. The goal: when a developer asks Claude Code to review their code, it applies a consistent, opinionated review framework rather than ad-hoc judgment.
Step 1: Create the skill directory
mkdir -p ~/.claude/skills/code-review
touch ~/.claude/skills/code-review/SKILL.md
Step 2: Write the frontmatter
Frontmatter is consumed by the skill loader to determine when to suggest the skill. The description field is critical — it contains the natural language trigger phrases that Claude Code uses to match user intent to available skills. Be specific. Use the exact words developers will use.
---
name: code-review
version: 1.0.0
description: Performs structured code reviews covering
correctness, security, performance, readability, and
test coverage. Trigger with: review this code, review
this PR, code review, check this function, look at
this implementation.
triggers:
- code review
- review this
- PR review
- check my code
author: your-name
tags: [code-quality, review, security]
---
Step 3: Write the instruction body
Use imperative form throughout. Write instructions as direct commands, not descriptions. “Check for SQL injection vulnerabilities” not “The reviewer should check for SQL injection vulnerabilities.”
# Code Review
## Quick Reference
- Lead with the most critical issues (security > correctness
> performance > style)
- Be direct. Do not soften every piece of critical feedback
with praise.
- Suggest specific fixes, not just problems.
- Flag any code you are uncertain about rather than
guessing.
## Review Process
### Security (check first)
- SQL injection: parameterized queries or ORM only
- XSS: user input must be escaped before rendering
- Auth: verify auth checks on every route/method
- Secrets: no hardcoded API keys, tokens, or passwords
- Input validation: untrusted input validated at boundary
### Correctness
- Error paths handled (not just happy path)
- Edge cases covered (empty arrays, null values, overflow)
- Async/await used correctly (no floating promises)
- Race conditions identified in concurrent code
### Performance
- N+1 queries identified and flagged
- Unnecessary re-renders in React components
- Memory leaks in event listeners or subscriptions
- Database indexes required by new query patterns
### Test Coverage
- Happy path covered
- At least one error path covered
- Edge cases tested where correctness issues were flagged
## Output Format
Organize review as:
1. Summary (2-3 sentences: overall assessment + priority)
2. Critical Issues (block merge — must fix)
3. Important Issues (should fix before merge)
4. Minor Issues (fix in follow-up or ignore with reason)
5. Positive observations (1-3 things done well)
Step 4: Add a setup script (optional)
#!/bin/bash
# scripts/setup.sh
# Validates that required linting tools are available
for tool in eslint tsc; do
if ! command -v $tool &> /dev/null; then
echo "Warning: $tool not found. Some checks will be
limited to static analysis."
fi
done
echo "code-review skill ready"
Plugin Structure
Plugins are more structured than skills and add system-level capabilities. A plugin requires a plugin.json manifest:
{
"name": "deployment-assistant",
"version": "1.2.0",
"description": "Deployment workflows for Kubernetes and Docker",
"author": "your-name",
"commands": [
{
"name": "deploy",
"description": "Run deployment workflow for specified
environment",
"script": "scripts/deploy.sh",
"args": [
{
"name": "environment",
"type": "string",
"required": true,
"enum": ["staging", "production"]
}
]
}
],
"agents": [
{
"name": "deployment-reviewer",
"skill": "skills/deployment-review.md",
"triggers": ["review deployment", "check deploy config"]
}
],
"hooks": [
{
"event": "pre-tool",
"tool": "bash",
"script": "hooks/pre-bash-check.sh"
}
]
}
The commands array defines new slash commands available in Claude Code. The agents array registers specialized sub-agents the plugin exposes. The hooks array registers lifecycle scripts.
The Skill Generator Pattern
One of the most powerful patterns in the Claude Code skills ecosystem: using a Claude Code subagent to generate new skills. The Skill Generator skill instructs Claude Code to introspect on a requested capability, identify the key knowledge and procedures involved, and output a complete SKILL.md file ready for installation.
---
name: skill-generator
version: 1.0.0
description: Generates new Claude Code skills from a
description of the desired capability. Trigger with:
create a skill, generate a skill, build a skill for,
write a SKILL.md.
---
# Skill Generator
When asked to create a new skill:
1. Ask for the desired capability if not fully specified
2. Identify the key knowledge domains the skill requires
3. Identify the most common trigger phrases users will
employ
4. Draft the SKILL.md using the standard template
5. Review the draft: is the Quick Reference section
actionable in isolation? Are instructions in imperative
form? Is the output format specified?
6. Output the complete SKILL.md ready to save
7. Provide the installation command:
mkdir -p ~/.claude/skills/[skill-name] &&
cat > ~/.claude/skills/[skill-name]/SKILL.md
MCP Server Integration
MCP Servers expose external tools to Claude Code. A minimal MCP Server in TypeScript:
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from
"@modelcontextprotocol/sdk/server/stdio.js";
const server = new Server(
{ name: "my-internal-tools", version: "1.0.0" },
{ capabilities: { tools: {} } }
);
server.setRequestHandler(ListToolsRequestSchema, async () => ({
tools: [
{
name: "query_internal_db",
description: "Query the internal product database",
inputSchema: {
type: "object",
properties: {
sql: { type: "string",
description: "Read-only SQL query" }
},
required: ["sql"]
}
}
]
}));
server.setRequestHandler(CallToolRequestSchema, async (req) => {
if (req.params.name === "query_internal_db") {
const result = await db.query(req.params.arguments.sql);
return { content: [{ type: "text",
text: JSON.stringify(result) }] };
}
});
await server.connect(new StdioServerTransport());
Register the MCP Server in your Claude Code config, and the tools it exposes become available to Claude Code like any other tool.
Best Practices
- Keep skills under 500 lines. Longer skills dilute focus. If a skill is growing past 500 lines, split it into two focused skills.
- Test across contexts. A skill that works for one type of request may not work for another phrasing of the same request. Test with at least five different phrasings of your trigger intent.
- Version your skills. Use semantic versioning in the frontmatter. Breaking changes to instructions warrant a major version bump. Keep a CHANGELOG in the skill directory.
- Imperative form throughout. Every instruction should be a direct command. “Check X” not “X should be checked.” The imperative form reduces model interpretation variance.
- Specify output format explicitly. If your skill requires a specific output structure, define it explicitly in the instructions. “Output as a numbered list” or “Respond with a JSON object matching this schema.”
Real Examples in Production
Teams using Claude Code at scale have converged on several high-value skill and plugin patterns:
- Formatting hook: A pre-commit hook that uses Claude to check staged files against the team style guide before allowing commit. Catches style issues before code review, not during it.
- Architecture review agent: A plugin agent that reviews new pull requests specifically for architectural concerns — not code-level details, but system-design-level decisions that individual code reviewers often miss.
- Deployment skill: Encodes the team’s deployment checklist as a skill so that every deployment review Claude performs checks the same list of pre-flight items.
- Incident response skill: When a production incident is declared, this skill activates and guides Claude through a structured incident analysis process — timeline reconstruction, impact scoping, root cause investigation, and postmortem draft.
People Also Ask
What is the difference between a Claude Code skill and a Claude Code plugin?
A skill is a SKILL.md file that encodes knowledge and instructions — it extends what Claude Code knows how to do. A plugin is a structured bundle with a plugin.json manifest that adds new commands, agents, and hooks — it extends what Claude Code can do at the system level. Most developers should start with skills; plugins are for more complex, multi-component capability extensions.
Where do Claude Code skills get stored?
Skills are stored in the ~/.claude/skills/ directory by default (per-user), or in a .claude/skills/ directory within a project for project-scoped skills. Project-scoped skills take precedence over user-scoped skills when both define the same trigger.
Can I share Claude Code skills with my team?
Yes. Skills stored in your project’s .claude/skills/ directory are committed with the project and shared with everyone who clones the repository. This is the recommended pattern for team-shared skills. User-scoped skills in ~/.claude/skills/ are personal and not automatically shared.
Ready to put well-engineered AI tools to work immediately? Browse our catalog of production-ready AI tools, prompt packs, and developer resources at wowhow.cloud/browse — built for developers who ship.
Browse Developer AI Tools
Comments · 0
Beta: comments are stored locally on your device and not visible to other readers.
No comments yet. Be the first to share your thoughts.