Claude Skills tutorial series — Part 1: What are Claude Skills?

Claude Skills are the mechanism for extending Claude Code with reusable, specialised behaviours. Think of Conduction's own /review-pr, /opsx-new, or the whole hydra-gate-* family: each one is a skill. This first part explains in ten minutes what a skill is, how it gets activated, and when you should not write one. It's part 1 of a four-part track; by the end you'll be ready to write your own in part 2 — and in part 3 we introduce the 7-level maturity framework that takes a skill from "feels good" to "measured good" (part 4 continues with L6 and L7).

In one sentence

A Claude Skill is a folder under .claude/skills/<name>/ containing a SKILL.md (and optionally scripts, examples, reference files). The frontmatter of that SKILL.md tells Claude when the skill is relevant; the body is the instruction Claude follows once the skill is loaded.

In practical terms: a skill is a unit of bundled behaviour. Instead of pasting a thousand lines of prompt text into CLAUDE.md, or retyping the same instructions every time, you write it once as a skill. Reusable, testable, and shareable with your team.

.claude/skills/
└── review-pr/
    ├── SKILL.md          ← required: the skill logic
    ├── templates/        ← optional: files with placeholders
    ├── references/       ← optional: standards and background
    ├── examples/         ← optional: examples of desired output
    └── scripts/          ← optional: shell or Python scripts

How a skill gets invoked

A single skill can be triggered in two ways:

1. Manually — you type /review-pr in a Claude session. Direct, predictable, and the skill runs exactly when you want it to.
2. Automatically — Claude reads the description of every available skill and picks one itself when the current situation matches. Ask "can you review this PR?" and Claude triggers review-pr on its own if it's available.

Which mode is allowed is controlled in the skill's own frontmatter:

• disable-model-invocation: true — only you can invoke it via /<name>. Use this for skills with side effects (/opsx-apply modifies code, /create-pr opens a PR). Claude shouldn't fire these on its own.
• user-invocable: false — only Claude itself may load it. Use this for background knowledge that doesn't make sense as an action (e.g. a legacy-system-context that only informs).
• Neither set → both are allowed. The default for most skills.

In a Hydra pipeline skills mostly run automatically: containers have no keyboard and rely on auto-activation. Behind your own keyboard you'll more often type / explicitly for control.

The frontmatter, field by field

A minimal SKILL.md looks like this:

---
name: review-pr
description: Review a Pull Request — runs local checks, summarises the diff, and posts inline comments
metadata:
  category: Workflow
  tags: [github, review]
---

# Review PR

Short explanation of what the skill does.

**Input**: how you invoke the skill and which arguments it accepts.

**Steps**

1. **Step name**
   Instructions...

2. **Step name**
   Instructions...

**Guardrails**
- What the skill must never do
- What it must check before destructive actions

Three fields deserve extra attention:

Why the description matters more than you think

Claude loads skills in three layers:

That means: only your description is always "on". If it's vague, your skill never fires automatically. Write it in third person, start with a verb, and front-load the most specific trigger words (only the first ~250 characters are visible in skill listings).

# Bad — vague, passive, no trigger words
description: A skill that helps with various document-related tasks

# Good — specific, third person, action verb up front
description: Create a Pull Request from the current branch — runs local checks, picks target branch, and opens the PR on GitHub

Deeper frontmatter fields

Besides name, description and metadata there are a few optional fields that subtly steer a skill's behaviour. You won't always need them, but knowing they exist helps later:

Start with the three required/basic fields. Add the above only when you have a concrete reason — otherwise you'll make your skill quieter or stricter than necessary.

Naming convention: namespace-action

Skills are conventionally named <namespace>-<action> using only lowercase letters, digits and hyphens. Conduction uses, among others:

The folder name, the name field, and the way you type it (/<name>) all need to be exactly identical.

Skill vs. prompt vs. agent

A common question: when is a skill the right choice, and when is something else? Three categories, briefly:

The pragmatic test: write a skill when…

1. The behaviour is repeatable — needed more than once, in more than one place.
2. It's mechanically describable — you can instruct it in 1-3 paragraphs without devolving into "it depends on the context".
3. A teammate would want to do the same — otherwise it's a personal macro, not a team skill.

For one-off work: just prompt. For repeatable work: skill. For heavy isolation of a sub-workflow: subagent.

Where skills "live"

Skills can sit at three levels:

In Conduction repos the vast majority live as project skills in <repo>/.claude/skills/. That ensures the whole team — and Hydra's Docker personas — have exactly the same skills.

Test yourself

Four short questions to check you understood this part. Stuck? Click Hint. Curious about the answer? Click Answer.