Skills and slash commands

The previous guide covered agents, which protect your main session by doing work in their own context. Skills solve the complementary problem: making the workflows you run repeatedly fast, consistent, and discoverable. They are different tools for different jobs, and they compose well together.

The most important property of a skill is also the thing that distinguishes it most sharply from an agent: a skill loads its content directly into your main session every time you invoke it. That is the source of both its power and its constraints.

What a Skill Is

A skill is a markdown file at .claude/skills/{name}/SKILL.md (project-level) or ~/.claude/skills/{name}/SKILL.md (global). Each skill has frontmatter (name, description, optional metadata) and a body that describes the workflow. You invoke it with a slash command, typically /sith:{name}.

When you invoke a skill, Claude Code reads the SKILL.md file and loads its body into your current conversation as if you had typed it yourself. From that point forward, Claude follows the instructions in the skill the same way it follows any other instruction in your session.

That single mechanic is what you need to internalize. Skills are not background workers. They are not separate processes. They are pre-written prompts with metadata, loaded into your main session on demand.

The Fundamental Difference From Agents

Agents and skills look superficially similar (both are reusable, both are invoked by name, both encapsulate workflows) but they sit at opposite ends of the context model.

The implication: skills are the right tool when you want guidance, structure, or consistent setup that you actively participate in. Agents are the right tool when you want a result without participating. They solve different problems and they often appear together.

When to Use a Skill

Skills earn their keep when:

• You run the same workflow more than twice. If you have typed the same long prompt three times this month, that prompt should be a skill.
• The workflow needs consistent setup. Argument parsing, path resolution, validation, environment checks. A skill ensures every invocation starts from the same baseline regardless of who is running it.
• You want the workflow to be discoverable. Slash commands appear in autocomplete. New team members can find them without reading documentation. A workflow with a name is easier to share than a paragraph buried in a wiki.
• The workflow has team conventions baked in. Naming patterns, label requirements, output locations. A skill encodes those conventions so they get applied automatically instead of being remembered case-by-case.

If a workflow has none of these properties (one-off prompt, highly variable inputs, no team-wide conventions), it does not need to be a skill. Type it out and move on.

The Skill-Wraps-Agent Pattern

The combination that makes both tools more powerful than either alone: a skill that wraps an agent. This is the dominant pattern in our planning repo and the one worth understanding well.

The division of responsibilities:

• The skill handles everything that needs to happen in your main session: parsing arguments, resolving inputs to canonical forms (story numbers to file paths, repo names to URLs), validating what you provided, and assembling a properly formatted prompt for the agent. It is the consistent entry point.
• The agent handles the heavy work: deep research, multi-file analysis, schema queries, synthesis. All of it happens in the agent’s own context. None of it pollutes yours.
• You type one slash command, get back the agent’s clean report.

This pattern gives you both halves of the value. The skill ensures every invocation is correctly shaped. The agent ensures the work itself does not flood your session. The result is a one-line invocation for an arbitrarily complex workflow, with predictable inputs and clean outputs.

The crucial insight: the skill’s primary job is crafting the prompt the agent receives. Without the skill, every invocation requires you to remember the right arguments, the right format, the right preamble. With the skill, that knowledge is captured once in the skill body and applied every time, by anyone.

A Concrete Example: discover-story

The discover-story skill in our planning repo is the cleanest example of this pattern.

What you type:

/sith:discover-story 181646

What the skill does in your main session:

1. Parses the argument. It might be a work item number (181646), a story file path, a story number pattern (177531-p01-01), or a plain language requirement.
2. If the argument matches a story number pattern, scans planning/features/ to resolve it to an actual file path.
3. Builds a properly formatted prompt that tells the planning-discovery agent exactly what it is looking at: the original input, plus the resolved file paths.
4. Invokes the planning-discovery agent with that prompt.

What the agent does in its own context:

1. Loads the methodology guide, the repo catalog, the story templates.
2. Determines which repositories need changes.
3. Runs schema queries against the live database to verify column names and types.
4. Uses Roslyn to confirm method signatures and interface contracts.
5. Finds existing patterns in the target codebases.
6. Writes the complete story spec with self-contained tasks.
7. Returns a summary of what was created.

What you see in your main session:

• The skill body (a few hundred tokens).
• The argument parsing happening (small).
• The agent’s final report (a few paragraphs).

You do not see the schema queries, the file reads, the pattern discoveries, or the iterations through the methodology guide. None of that ever lands in your context. The next thing you ask Claude to do gets full attention on what you are saying, not on the residual noise of producing the story.

The same pattern shows up across our skill catalog: discover-feature wraps feature-decomposition, ado-sync wraps ado-story-sync, code-review wraps code-review-agent. In each case, the skill is the standardized entry point and the agent is where the actual work happens.

Anatomy of a Skill File

A minimal skill:

---
name: sith:hello-world
description: Says hello and reports the current branch.
---

# Hello World

Greet the user and report the current branch they are on.

## Task

$ARGUMENTS

## Steps

1. Run `git branch --show-current` and capture the result.
2. Reply with: "Hello. You are on branch {result}."

The frontmatter:

• name: the slash command (without the leading /). Use the sith: prefix for team skills.
• description: shown in autocomplete and used by Claude when deciding whether the skill matches a user request. Be specific.

The body:

• Standard markdown.
• $ARGUMENTS is substituted with whatever the user typed after the slash command.
• Should read like instructions to Claude, because that is what it becomes when loaded into your session.

The body should not duplicate content that already exists elsewhere. If the workflow follows a guide in the planning repo, link to the guide and let Claude read it. If the workflow uses a specific agent, name the agent and pass the right arguments. Skills should be thin orchestrators, not encyclopedias.

Custom Skills

Where to create them:

• Project-level at {repo}/.claude/skills/{name}/SKILL.md. Committed to source control. Available to anyone who clones the repo. This is the right home for team-specific workflows.
• Global at ~/.claude/skills/{name}/SKILL.md. Personal. Available across every project on your machine. This is the right home for workflows tied to your individual habits.

Pattern to follow:

1. Identify the workflow. The trigger is usually “I just typed this same long prompt for the third time.”
2. Write the skill as a thin orchestrator. Argument parsing, validation, then either inline steps or an agent invocation.
3. Name it well. Slash commands should read like the action being performed.
4. Add it to the catalog README. A skill nobody knows exists provides no value.

For team skills that wrap an agent: keep the skill thin and put the heavy logic in the agent. The skill is the door; the agent is the room.

Working Examples

The two skills referenced earlier in this guide are good reference implementations of the wrap-an-agent pattern. Both are short, both illustrate the division of responsibility cleanly, and both are in active use.

• discover-story wraps the planning-discovery agent. The skill handles input shape detection (work item number, story number pattern, file path, plain language requirement), resolves story numbers to file paths, and hands off to the agent with a properly formatted prompt. Read this one first if you are looking for the simplest version of the pattern.

• discover-feature wraps the feature-decomposition agent. The skill handles mode selection (full, analyze, discover, stories, transcript), validates the working directory, and assembles the agent prompt with the right context for each mode. This is the more complex example, useful when the wrapped agent supports multiple invocation shapes.

Both skill files are short. The agent specs they delegate to are large. That ratio is the pattern: the skill is the cheap, consistent entry point; the agent carries the depth.

When NOT to Use a Skill

Skills are not free. Each one is a file to maintain, a name to remember, and a thing that can drift out of sync with whatever it wraps. Skip them when:

• The workflow is genuinely one-off. If you wrote a long prompt once and will not write it again, do not turn it into a skill on principle.
• The inputs are too variable. Skills work well when arguments map cleanly to a few shapes. If every invocation needs significantly different setup, a skill becomes a wrapper around a giant if-statement.
• You would rather type it out. For workflows where typing the prompt is part of how you think through the problem, a skill takes that thinking away. That is not always desirable.

Putting It Together

The mental model that ties guides 2 and 3 together:

• Skills are how you make a workflow consistent and discoverable. They live in your main context.
• Agents are how you keep work isolated from your main context. They live in their own.
• Skills that wrap agents give you both: a one-line invocation that triggers heavy work without polluting your session.

When you find yourself doing something repeatedly, your first question should be “could this be a skill?” If the answer is yes, the second question is “and does the skill need to wrap an agent to keep my context clean?” When both answers are yes, you have found one of the highest-leverage patterns in Claude Code.

The next guide in this series covers hooks: the lower-level mechanism that lets you inject context, run validations, and respond to lifecycle events automatically, without invoking anything explicitly.