Claude Code Skills
Skills give Claude Code reusable, specialized know-how — beyond a quick command. Here's what they are, how they layer with the rest of your setup, and what makes them reliable on a team.
As teams push Claude Code past one-off tasks, skills
have become how you give the agent specialized, reusable capability —
deeper than a quick command, broader than a single instruction. This
page covers what skills are, how they fit alongside commands and
CLAUDE.md, and the thing that decides whether a skill
produces sharp output or generic noise.
What a skill is
A skill packages how to do a specific kind of task well — a defined set of instructions, often with supporting files, that the agent can draw on when the task calls for it. Think of it as teaching the agent a capability once, then reusing it: a code-review skill, a migration skill, a docs skill.
How skills layer with the rest
Skills don't replace your other setup — they sit on top of it:
- CLAUDE.md — always-on baseline context (commands, conventions, layout).
- Commands — quick, invokable workflow shortcuts.
- Skills — richer, reusable capabilities for a class of task the agent leans on when relevant.
Together they make the agent's loop more capable and more repeatable.
Anatomy of a skill
A skill is just a folder under .claude/skills/, named for the
capability, with a SKILL.md at its root. The agent discovers it
by reading the front-matter, and only loads the full body when a task looks
like a match. Supporting files — scripts, templates, reference docs — live
alongside it and are pulled in on demand:
.claude/skills/
review-pr/
SKILL.md # name, description, instructions
rubric.md # reference the agent reads when needed
check-sql.sh # a script the skill can run
db-migration/
SKILL.md
template.sql
The SKILL.md itself is plain Markdown with a small
YAML header. The description is the part the agent scans to
decide whether the skill is relevant, so it carries most of the weight:
---
name: review-pr
description: Review a pull request diff for SQL safety, trust-boundary
bugs, and conditional side effects. Use when asked to review a PR,
check a diff, or before landing changes.
---
# Reviewing a pull request
1. Read the diff against the base branch.
2. For every changed query, apply rubric.md.
3. Flag any user input that crosses a trust boundary unsanitized.
4. Run check-sql.sh and surface anything it returns.Keep the body short and procedural. Push long checklists and examples into sibling files the skill points at — the agent reads them only when the task actually needs them, which keeps your context window lean.
Writing a skill that triggers reliably
The most common failure mode isn't a bad skill — it's a skill the agent
never invokes, or invokes at the wrong moment. Two levers fix almost all of
it: the description and the scope.
- Describe the trigger, not the topicName the user phrases that should fire it — "review a PR", "check my diff" — not just "PR review skill". The agent matches on intent.
- Scope to one jobA skill that reviews, tests, and deploys never triggers cleanly. Split it. One capability per skill.
- State the boundariesSay when NOT to use it. "Skip for docs-only diffs" stops false fires on unrelated tasks.
- Defer the detailReference rubric.md, template.sql, examples — load them lazily instead of inlining everything in the body.
A quick way to test a new skill: describe a matching task in plain language
("can you review this diff before I land it?") and watch whether the agent
reaches for the skill without being told its name. If it doesn't, the
description is too topical — rewrite it around the words a
teammate would actually type. Iterate on that line first; it changes
behavior more than anything in the body.
Sharing skills across a team
Commit skills to the repo and every teammate's agent gets them. But a shared skill runs into the same wall as everything else: a skill encodes how to do a task, not what your team decided about your codebase. A review skill that doesn't know your conventions produces generic review; a migration skill that doesn't know your constraints produces a migration you have to redo.
First-Tree gives skills the context they operate on — and the orchestration around them.
First-Tree is an open-source agent orchestration platform: agents work alongside humans in shared threads, GitHub issues and PRs become the work queue the right agent picks up, and a living context tree of the team's decisions, designs, and ownership stays in your repo. Skills stay about capability; the tree — an owned, versioned set of decisions the agent reads on every run (via a SessionStart hook) — means a skill's output reflects what your team actually decided instead of a generic best-guess. Shared skills, shared memory, and coordinated work is the combination that scales.
Skills, commands, a tight CLAUDE.md, and a shared context tree are the full Claude Code best practices stack for teams — and on First-Tree they sit inside a platform that also routes work through GitHub and lets agents coordinate in shared threads, the foundation of running AI agent teams where every agent is capable, informed, and working off the same queue.