Claude Code is a terminal-based coding agent that can automate the repetitive parts of your development workflow, not just generate code.
This article isn't about installation or basic usage. It's written for developers already using Claude Code who want to learn how to design Skills that deliver meaningful automation and consistency in real-world projects.
Among Claude Code's features, Skills are the main way to define how Claude should handle repeatable tasks and follow your project's engineering conventions. In this article, we'll look at how they keep code quality consistent across a team.
Updated July 2026— The January version of this guide described Skills as single.md
files in.claude/commands/
. Skills have since become directory-based (.claude/skills/<name>/SKILL.md
), adopted a formal frontmatter specification, and become an open standard at[agentskills.io]. This revision reflects the current format. The examples come from skills I actually use in real projects.
In Claude Code, a Skill is a directory containing a SKILL.md
file with the instructions, resources, and execution steps Claude follows when the skill is invoked. For personal and project skills, the directory name becomes the command name: .claude/skills/code-review/SKILL.md
gives you /code-review
. (Plugin skills are namespaced by the plugin name: /my-plugin:review
.)
The important distinction is this: a Skill is not an independent agent. It packages instructions, resources, and tool permissions—Claude, or you, decides when to invoke it, unless the frontmatter restricts invocation.
If you remember "custom slash commands"(.claude/commands/*.md
): they've been merged into Skills. A file at.claude/commands/deploy.md
and a skill at.claude/skills/deploy/SKILL.md
both create/deploy
, and old command files keep working. Skills are the recommended format—they add supporting files, invocation control, and a richer frontmatter. If both define the same name, the skill wins.
Skills can be managed per-project or globally across your machine:
| Scope | Location | Applies to |
|---|---|---|
| Personal | ||
~/.claude/skills/<name>/SKILL.md |
||
| All your projects | ||
| Project | ||
.claude/skills/<name>/SKILL.md |
||
| This project only (shared via Git) | ||
| Plugin | ||
<plugin>/skills/<name>/SKILL.md |
||
| Wherever the plugin is enabled |
The file must be named exactly SKILL.md
, and a skill is a directory, not a single file. That directory can carry supporting material that loads only when needed:
code-review/
├── SKILL.md # required: frontmatter + instructions
├── references/ # detailed docs, loaded on demand
├── scripts/ # executable helpers (run, not loaded)
└── assets/ # templates, static resources
For me, this is the most useful improvement over the old single-file format. Keep SKILL.md
under ~500 lines and push heavy reference material into references/
—the body stays in context for the whole session once loaded, so every line has a recurring token cost.
---
name: code-review
description: Review code against .claude/rules/ for architecture and convention violations.
argument-hint: "[path] [--staged|--branch] [--fix]"
allowed-tools: Read Glob Grep Bash(git *)
---
☝️ The description
field is still critical. Claude normally sees the names and descriptions of available Skills and uses that metadata to decide which one is relevant. If you say "review my code," that request gets matched against skill descriptions—so yours must contain clear, searchable keywords.
One distinction worth knowing before the table: the Agent Skills standard defines the portable core fields (name
, description
, license
, compatibility
, metadata
, allowed-tools
). The rest below—argument-hint
, disable-model-invocation
, user-invocable
, context
—are Claude Code extensions. The table covers the fields used in this guide, not every option Claude Code supports (there are also when_to_use
, model
, paths
, hooks
, and more):
| Field | What it does |
|---|---|
name |
|
| Display name (defaults to the directory name) | |
description |
|
| Auto-invocation trigger. Keep it ≤1,024 chars for cross-tool compatibility | |
argument-hint |
|
Autocomplete hint shown after /name |
|
allowed-tools |
|
| Tools Claude may use without permission prompts while the skill runs (space-separated per the standard; Claude Code also accepts commas) | |
disable-model-invocation |
|
true = only you can trigger it; Claude never auto-invokes |
|
user-invocable |
|
false = hidden from the / menu; Claude-only background knowledge |
|
context: fork |
|
| Run the skill in an isolated subagent context |
Two of these encode a design decision the old format couldn't express: who is allowed to pull the trigger. For side-effect workflows—deploying, committing, sending messages—set disable-model-invocation: true
so Claude can't decide on its own that now is a good time to deploy. For pure background knowledge, set user-invocable: false
so it stays out of your command menu.
/code-review
Skill
The architecture-review skill from the January version of this post is still the one I use every day—it has just grown up. Here's the frontmatter of my current production /code-review
skill:
---
name: code-review
description: Review code against .claude/rules/ for architecture and convention
violations. Supports --staged, --head, --last, --today, --branch scope options.
Add --fix to auto-correct.
argument-hint: "[path] [--staged|--head|--last|--today|--branch] [--fix]"
allowed-tools: Read, Glob, Grep, Edit, Bash(git *), Bash(find *)
---
The current version relies on two features that didn't exist in January:
1. Arguments. $ARGUMENTS
in the skill body is substituted with whatever you type after the command, so one skill covers many scopes:
| Invocation | Review scope |
|---|---|
/code-review |
|
| Files changed in the last 5 commits | |
/code-review src/user/ |
|
| A specific directory | |
/code-review --staged |
|
| Final check right before committing | |
/code-review --branch |
|
| Current branch vs main, before opening a PR | |
/code-review --staged --fix |
|
| Auto-fix what it finds |
2. Dynamic context injection. A ! command``
placeholder runs before Claude sees the skill and gets replaced with its output. My skill uses it to enumerate the rule files and changed files up front:
- Project rules: !`find .claude/rules -name "*.md" | sort`
- Staged files: !`git diff --name-only --cached`
The Claude Code client runs these commands during preprocessing; the model receives only the expanded results as part of the skill instructions. That removes an entire class of "the model forgot to check X first" failures.
📎 Full working example: code-review SKILL.md — save it as .claude/skills/code-review/SKILL.md
in your project. The directory name is what creates the /code-review
command.
Claude Code already ships a bundled
/code-review
skill. Adding your owncode-review
skill at the personal or project level overrides the bundled version—which is exactly what I want here: a review driven bymyrule files, not a generic one.
.claude/rules/
dynamically instead of hardcoding policies, so the same skill works in every project and stays aligned with the current rule files.Running /code-review
in the terminal produces results like this:
> /code-review src/user/api/user_router.py
🔍 Reviewing: src/user/api/user_router.py
## Architecture Violations Found
### 🚨 CRITICAL (2)
**Line 45**: Direct Repository import detected
- Found: `from src.user.repositories.user_repository import UserRepository`
- Fix: Remove this import. Use Service layer instead.
**Line 78**: Business logic in API layer
- Found: `if user.age >= 18 and user.verified:`
- Fix: Move this validation to UserService.validate_user_eligibility()
### ⚠️ WARNING (1)
**Line 23**: Service manually instantiated
- Found: `service = UserService()`
- Fix: Use `service: UserService = Depends(get_user_service)`
### 💡 SUGGESTION (1)
**Line 12**: Consider adding return type hint
- Current: `async def get_user(user_id: int):`
- Suggested: `async def get_user(user_id: int) -> StandardResponse[UserResponse]:`
---
Summary: 2 critical, 1 warning, 1 suggestion
Run `/code-review --fix` to auto-fix applicable issues.
One command produces a repeatable first-pass architecture review based on your project's documented rules. It doesn't replace human review—but it catches routine violations before a pull request ever reaches another developer.
The same two features that make skills powerful make them worth auditing. Skills are executable workflow definitions, not passive documentation:
allowed-tools
pre-approves tool usage for the duration of the skill—no permission prompts.! command``
run disableSkillShellExecution
setting.)Bash(git *)
beats Bash(*)
, and list only the tools the procedure actually needs.Human reviewers vary by mood and energy. A well-defined Skill applies the same checklist every time, reducing variation and making common omissions less likely.
Tasks that touch multiple files (adding a new API endpoint requires Router, Service, Schema, and Test files) can be bundled into a single Skill, reducing the chance of missing a step.
Embed your design philosophy into Skill files and share via Git. Junior developers can generate code that is consistently aligned with documented senior guidelines. And because Skills follow an open standard, the SOPs you encode aren't locked into one tool.
These are skills currently in my ~/.claude/skills/
and project .claude/skills/
directories—not hypotheticals:
| Skill Command | What It Does |
|---|---|
| /code-review | |
Check architecture violations against .claude/rules/ with severity levels and --fix |
|
| /commit-push | |
| Stage, generate a conventional commit message, confirm, push | |
| /create-post | |
| Scaffold a new blog post following every content convention (slug rules, image folders, frontmatter schema) | |
| /feature-image | |
| Crop and convert cover images to 16:9 WebP under a size budget | |
| /review-skill | |
The meta one: audit SKILL.md files against the open standard, with --fix |
|
Notice the pattern in the last row—once your process knowledge lives in files, you can write skills that maintain other skills.
.claude/rules/
is the single source and the skill is the procedure that applies it.SKILL.md
leanreferences/
files that load on demand; the skill body occupies context for the whole session.disable-model-invocation: true
. Guardrails belong in frontmatter, not in hope.Claude Code Skills turn repeated instructions into reusable, version-controlled workflows.
Their quality depends less on clever prompting than on how clearly you've defined the process Claude should follow.
If your team repeatedly explains the same conventions during code reviews, those conventions are good candidates for a Skill. Start with one narrow workflow, test it against real tasks, and refine it as your process changes.
In the next article, we'll explore Custom Agents—how to build AI that autonomously decides when to use which Skill.
Originally published at jamongx.com.