Claude Skills Guide.
Turn repeatable workflows into named commands.
Skills are how you give Claude Code repeatable, consistent behavior on demand. A skill is a named procedure the tool can invoke with a slash command. If you do something weekly and it has a clear shape, it should be a skill.
Ricardo Ramirez
Founder, Sprintt · Product Builder
TL;DR · 4 takeaways
- 01
SKILL.md defines behavior. user-invocable: true makes it a /command.
- 02
Good skills are scoped tight. One job, one outcome.
- 03
Skills stack for consistency across sessions.
- 04
Use skills for procedure. Use agents for judgment.
What a skill is.
A skill is a markdown file, SKILL.md, with frontmatter that describes the skill and a body that describes the procedure. When marked user-invocable, it becomes a slash command in Claude Code. Typing /push invokes the push skill. That is it.
Skills are procedures. Agents are judgment. Use the right tool.
Skills are the mechanism you reach for when the steps are knowable up front. The agent does not need to think hard, it needs to remember to do A, then B, then C, consistently.
SKILL.md explained.
---
name: push
description: Stage, commit with conventional commit format, and push safely.
user-invocable: true
---
## When to use
Use when the user asks to push changes, commit, or save work.
## Steps
1. Run `git status`. If there are no changes, exit with a message.
2. Run `git diff` on staged and unstaged changes. Summarize the diff.
3. Draft a conventional commit message. Confirm it with the user.
4. Stage the appropriate files. Never use `git add -A` if .env files are present.
5. Commit with the confirmed message. Never pass --no-verify.
6. Push to the current branch. Do not force push.
## Non-goals
- Do not push to main or master without explicit confirmation.
- Do not rebase or reset.Skills worth building first.
Do not build a kitchen sink. Build the handful of skills that cover the work you actually do every week.
- 01
/push
Stage, commit, push, with guardrails. The one skill that pays for itself the most.
- 02
/pr
Generate a PR from the current branch with a structured body. Summary, why, test plan.
- 03
/check
Run lint, typecheck, and tests. Summarize failures. Offer to fix simple ones.
- 04
/new-feature
Create a feature branch from latest main with a conventional name. Saves five seconds and one typo.
- 05
/component
Scaffold a component file that follows your conventions. Named export, right directory, test stub.
Skill or agent?
A common trap is building a skill where you actually needed an agent, or vice versa. The rule of thumb:
- 01
Use a skill when the steps are clear
The procedure is knowable up front. Consistency matters more than creativity. /push, /pr, /check.
- 02
Use an agent when judgment is needed
The work requires a specialist lens. Security review. Design critique. Architecture assessment. A system prompt shapes how it thinks, not what steps it runs.
- 03
Compose them
A /check skill can call an @security agent. Skills are the mechanics. Agents are the brains. They work best together.
Keep it tight.
The best skills have the same shape. One job. Clear guardrails. Refuses to go out of scope. Four principles:
- 01
One outcome
A skill does one thing. If it is branching into three modes, it is actually three skills.
- 02
Explicit non-goals
List what the skill does not do. Prevents scope creep and subtle misuse.
- 03
Confirm before destructive actions
Anything that rewrites history, pushes remote, or drops data gets a confirmation step. Always.
- 04
Fail loudly
If a precondition is not met, stop and say why. Do not guess. Guessing is how skills become footguns.
Do one thing well. Say what you are about to do. Let me say no.
Distribution via plugins.
A single skill lives in .claude/skills/ inside a project. To share skills across projects or teams, bundle them in a plugin and install the plugin.
team-skills/
├── plugin.json
└── skills/
├── push/SKILL.md
├── pr/SKILL.md
├── check/SKILL.md
└── component/SKILL.mdOne skill plugin per team, kept on GitHub, installed by every engineer. Everyone gets the same slash commands, the same guardrails, the same voice.
If this was useful, pass it on.
Ricardo Ramirez
Product Builder and Founder of Sprintt. Advising product teams on AI strategy and operating models.