Claude Code and Skills — reusable command bundles

Claude Code is Anthropic's terminal-based coding assistant CLI, released in February 2025 (research preview at the time). It later moved to general availability and gained features like IDE integration, GitHub Actions, and Skills.

1. About Claude Code

Anthropic's official coding assistant CLI. The basic shape is running claude in a terminal to drive a conversation/work session. It runs on the same model (Claude) but sits in a different place than chatbots like ChatGPT — it directly uses tools (file edits, test execution, git commands) with the user's permissions.

Distinctive aspects:

• Terminal-first interface (later additions: IDE extensions, GitHub Actions integration).
• User approval gates (permission model).
• Acts as an MCP client — external tools can be registered.
• Project-scoped CLAUDE.md convention.

2. About Skills

A feature Anthropic released into general availability on October 16, 2025. It bundles model + tools + scripts + prompts into one unit (Skill) and lets the model pick from these when needed.

How it lands:

• Invokable as commands (slash commands).
• Frontmatter metadata declares name, description, and required tools.
• Helper scripts and assets sit alongside in the skill directory.

3. Directory structure

Location	Meaning
~/.claude/skills/<name>/SKILL.md	User-global skill.
<project>/.claude/skills/<name>/SKILL.md	Project skill (committable).

Frontmatter at the top of SKILL.md:

---
name: review-pr
description: Review the current PR's changes and summarize key risks.
---

# Review PR

## Steps
1. Get the changed-files list
2. ...

A skill can include extra files (helper scripts, templates), and the model references those files from the skill body.

4. Invocation · metadata

Invocation:

• Inside Claude Code, called via a command like /skill-name.
• The model looks at the user intent and auto-selects an appropriate skill from those registered.

The frontmatter description is the key for telling the model when to use the skill. Too short or vague and the model can't pick it. Writing examples and trigger conditions clearly is the recommended shape.

Tool calls inside a skill follow Claude Code's permission model. Auto-allow / requires-approval / blocked are split into settings.

5. Similar concepts

Cursor Rules — natural-language rules in the .cursor/rules/ directory or .cursorrules file. Same place as Claude Code's CLAUDE.md.

Cursor "Custom Modes" (0.46~) — bundle a system prompt, allowed tools, and default model into one unit.

Aider Conventions — explicitly include CONVENTIONS.md in context. The place where you write code-style and architecture decisions at length.

Continue Custom Commands — register frequently used tasks (/test · /review) as commands.

GitHub Copilot Custom Instructions — .github/copilot-instructions.md or custom instructions in user settings. Always include common guidance in the model context.

MCP Prompts — one of the three MCP primitives. The difference is being a client-neutral standard.

6. Skill candidates that work well

• PR review process (change summary · test check · security check).
• Migration steps (library · API version bumps).
• Documentation generation templates (release notes · architecture diagram text).
• Debug procedures (log collection · reproduction · summary).
• Test-writing helpers (your project's test style).

7. Short and clear skills

The longer a skill, the more the model tends to ignore parts. Keep core steps short, put helper material in separate files, and reference them from the body — that's the stable shape.

Permission minimization — when a skill touches system commands, file writes, or external calls, design it together with the permission-model settings. Split auto-execute items from user-approval items.

Team sharing — putting skills under the project .claude/skills/ directory enables team sharing via git. Keep them separate from the user's personal ~/.claude/skills/.

8. Common pitfalls

Name conflicts — when a user-global skill and a project skill share a name, it's unclear which takes precedence.

Missing frontmatter — without name · description, the model can't pick the skill.

External calls inside a skill — when a skill uses external APIs or secrets, watch credential management and log exposure.

Too many skills — the model context gets heavy. Organize per work domain.

Version compatibility — Claude Code changes fast. Old-format skills may stop working.

CLAUDE.md and skill duplication — putting the same rule in both invites drift. Keep it in one place and reference it briefly from the other.

Auto-invocation off intent — the model auto-calls a skill that doesn't match intent. Clarify the description or invoke explicitly.

Closing thoughts

Skills are an attempt to standardize reusable work bundles. CLAUDE.md (global rules) + Skills (work-unit procedures) + Subagents (per-role personas) — splitting these three places keeps operations clean. A short and clear description, organization per work domain, and minimum permissions are the starting point for stable operations.

Next

• subagents
• hooks-settings

We refer to Claude Code docs · Agent Skills announcement (2025-10) · Settings · Hooks · Cursor Rules · Copilot Custom Instructions · Aider CONVENTIONS · MCP Prompts.