Claude Code Skills

Claude Code is where skills do the most work, because the CLI gives them real surfaces to act on: your filesystem, your shell, your git history. A skill that writes a changelog can actually run git log; a skill that generates screenshots can actually save PNGs. The same SKILL.md on claude.ai gets the instructions but not the execution layer.

Two filesystem locations matter. ~/.claude/skills/ is user-level: available in every session, in every project — the right place for skills you want everywhere. .claude/skills/ inside a repository is project-level: scoped to that codebase, committed or ignored as your team prefers. Team-specific workflow skills belong at project level; personal productivity skills at user level.

Loading is progressive, like everywhere else: name and description are always in context, the SKILL.md body loads on trigger, and attached scripts and references load on demand. You can carry dozens of installed skills without paying their full token cost per session.

Claude Code exposes several extension points and they're easy to conflate:

• Skills — expertise the agent applies when a task matches. You ask naturally; the skill decides whether it's relevant.
• Slash commands — explicit invocations you type. /review runs when you type it, not when the agent thinks it's useful.
• Hooks — shell commands that fire on lifecycle events (before a tool call, after a file write). Deterministic automation, not judgment.
• Subagents — separate agents with their own context window and tool allowlist, for delegated subtasks.
• Plugins — the packaging layer. A plugin can bundle skills, commands, hooks, and MCP servers into one installable unit via a marketplace.

Rule of thumb: if it's knowledge, it's a skill; if it's a keystroke, it's a command; if it's an event reaction, it's a hook; if it needs its own context, it's a subagent. Plugins are how you ship any of the above.

Three paths, fastest first:

# 1. The skills CLI — copies from GitHub, works across runtimes
npx skills add owner/repo

# 2. Manual — clone into the right skills directory
cp -r path/to/skill-folder ~/.claude/skills/

# 3. Plugin marketplace — for skills bundled as plugins
/plugin marketplace add owner/repo
/plugin install plugin-name@repo

After any install, start a new session — Claude Code discovers skills at session start, so a skill added mid-conversation won't trigger until you restart. The npx skills CLI is the least error-prone path for GitHub-sourced skills; manual copy is better when you're writing your own and iterating on the SKILL.md in place.

Installing to the project level (.claude/skills/) lets you commit skills alongside the repo so a team shares the same agent behavior — useful for changelog formats, review checklists, and release procedures that should be identical for everyone.

Start at project level: create .claude/skills/your-skill/SKILL.md inside the repo where the skill will be used. The frontmatter needs two fields — a hyphenated name matching the folder, and a description written as a trigger condition ("Generate release notes from merged PR titles when the user asks for a changelog"), not a definition. The body is a numbered procedure the agent follows when the description matches.

Iterate on the description before polishing the steps — misfires and non-triggers are almost always description problems. Trigger it with a natural request in a new session; if it fires on the wrong tasks, tighten the description's when-clause; if it never fires, add the words users actually say. Once it works, promote the folder to ~/.claude/skills/ for cross-project use, or keep it committed so the team shares it.

For a deeper walkthrough of the format — frontmatter fields, progressive disclosure, references and scripts — the guide to what are Claude skills covers it end to end.