CC5: Skills & Slash Commands

Learning Objectives

• Explain why custom commands and skills merged — and when to still use the simple-command shape.
• Drop a SKILL.md anywhere in the 4-scope hierarchy and have Claude pick it up live.
• Use all six argument substitution variables ($ARGUMENTS, $N, $name, ${CLAUDE_SESSION_ID}, ${CLAUDE_EFFORT}, ${CLAUDE_SKILL_DIR}).
• Inject live data with !`cmd` backtick syntax (and disable it via policy).
• Pick when to use context: fork for isolation vs inline execution.
• Reach for the right bundled skill (/simplify, /batch, /debug, /loop, /claude-api) instead of writing one.

Commands and Skills, Unified

The 4 Scopes — Where Skills Live

Conflict resolution: Enterprise overrides Personal overrides Project. Plugin skills use plugin-name:skill-name namespacing — they cannot conflict with non-plugin skills. If a skill and a custom command share a name at the same scope, the skill wins.

Live change detection: add, edit, or remove a skill inside ~/.claude/skills/, project .claude/skills/, or any directory passed via --add-dir — the change takes effect during the current session. No restart needed. Creating a brand-new top-level skills directory does require a restart so it can be watched.

Monorepo bonus: nested discovery

When you work on a file in packages/frontend/, Claude Code also scans packages/frontend/.claude/skills/. Each sub-package can ship its own skills without polluting the root.

Build Your First Skill in 60 Seconds

Concrete example: a skill that runs the test suite, parses failures, and prints a focused report. We'll call it /test-triage.

mkdir -p .claude/skills/test-triage
cat > .claude/skills/test-triage/SKILL.md <<'EOF'
---
description: Run the test suite, identify failures, propose fixes
allowed-tools: Bash(pnpm test*), Bash(pnpm typecheck*), Read, Edit
---

Run `pnpm test` and capture the output.

For each failure:
1. Identify the test file and the failing assertion.
2. Read the source under test.
3. Decide whether the test is wrong or the source is wrong.
4. Propose the smallest change that makes the test pass without breaking others.

Report:
- Total: X tests, Y failing
- For each failure: file, root cause, proposed change
- Don't apply changes — just report.
EOF

Now in any session inside that repo:

> /test-triage

Claude runs the suite, reads the source, and reports. The allowed-tools entry pre-approves Bash for pnpm test and pnpm typecheck only — nothing else.

SKILL.md Frontmatter — The Knobs

15 frontmatter fields. You'll use 4-5 most of the time. The full list:

Argument Substitution — Six Variables

Variables interpolate before the skill body is sent to Claude. Positional args use shell-style quoting ("hello world" = one arg, not two).

Example: a fix-issue skill

---
name: fix-issue
description: Fix a GitHub issue by number
arguments: [issue, branch]
disable-model-invocation: true
allowed-tools: Bash(gh issue view*), Read, Edit, Bash(git*)
---

Fix GitHub issue $issue on branch $branch.

1. Run `gh issue view $issue` and read the description.
2. Identify the affected files.
3. Implement the fix on $branch.
4. Run tests.
5. Open a PR linked to issue #$issue.

If $branch doesn't exist, create it from main.

Invoke with /fix-issue 1234 fix/login-bug — $issue becomes 1234, $branch becomes fix/login-bug.

Shell Injection — !`cmd` Runs Before Claude Sees Anything

Skills can run shell commands at render time using backtick syntax. The output replaces the placeholder, and the rendered prompt is what reaches Claude. This is preprocessing — not Claude executing the command.

---
name: pr-summary
description: Summarize the current pull request using live GitHub data
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

## PR diff
!`gh pr diff`

## Reviewer comments
!`gh pr view --comments`

## Multi-line block
```!
node --version
npm --version
git status --short
```

Summarize the changes and flag anything that needs reviewer attention.

When this runs:

1. Each !`cmd` executes; stdout is captured.
2. Output replaces the placeholder in the rendered text.
3. Claude receives the rendered prompt with actual PR data inlined — no tool round-trips needed.

Skills That Run in a Fork — context: fork

Add context: fork and the skill runs in a forked subagent context: it gets the system prompt, no main-conversation access, and its tool calls don't pollute your transcript — only the final result returns. Pair with agent: to choose which subagent type executes (CC6 covers the full subagent system).

---
name: deep-research
description: Research a topic across the codebase
context: fork
agent: Explore
---

Research $ARGUMENTS thoroughly:
1. Use Glob and Grep to find relevant files
2. Read the most relevant ones
3. Summarize findings with specific file references
4. Identify follow-up questions worth pursuing

When to use fork: the skill produces verbose intermediate output (file reads, search results) you don't need in main context. When NOT: reference content like API conventions; those should run inline so Claude can use them alongside your conversation.

Bundled Skills — Use Before You Build

Claude Code ships with prompt-based skills in every session. Reach for these before writing your own:

Plus a few built-in commands also available through the Skill tool: /init, /review, /security-review. Block all skills with a Skill deny rule, restrict to specific ones with Skill(name) in permissions.allow. To trigger extended thinking from a skill, include the literal word "ultrathink" anywhere in the skill content.

Hands-On Lab — Build a /new-resource Generator for the API

Working in the PublicRecords API. You'll author a project-scoped slash command that scaffolds Controller + Service + Repository + MockMvc test for a new UCC entity, given just an entity name. About 10 minutes.

Step 1 — Create the command file

From the project root, make the commands directory:

Create the command file with this content:

---
description: Scaffold Controller + Service + Repository + test for a UCC entity
argument-hint: <EntityName>
---

Generate four Java files for a new resource named `$1` in the
`com.publicrecords.api.$1lower` package, where `$1lower` is `$1` lowercased.

Follow the existing layout in `com.publicrecords.api.filing` exactly:

1. **`$1.java`** — JPA entity. Always include:
   - `id` (Long, `@GeneratedValue` IDENTITY, primary key)
   - `state` (String, 2-char, `@NotBlank`, `@Size(min=2,max=2)`)
   - `createdAt` (Instant, `@Column(nullable=false)`)
   - 2–3 entity-specific fields appropriate for US public records
     (e.g., for `Amendment`: `originalFilingId`, `amendmentType`,
     `amendedAt`).

2. **`$1Repository.java`** — extends `JpaRepository<$1, Long>`.
   Add a `findByState(String state)` derived query.

3. **`$1Service.java`** — `@Service` with `findAll`, `findById`,
   `create($1 entity)`. Constructor-inject the repository (no `@Autowired`).

4. **`$1Controller.java`** — `@RestController` with `@RequestMapping("/$1lower")`.
   - `GET /` → service.findAll()
   - `GET /{id}` → service.findById, returning `ResponseEntity<$1>`
     with `.notFound()` on miss
   - `POST /` → service.create with `@Valid @RequestBody`
   Every public method gets a 1-line JavaDoc.

5. **`$1ControllerTest.java`** under
   `src/test/java/com/publicrecords/api/$1lower/` — one MockMvc test
   asserting `GET /$1lower` returns 200.

After generating, run `mvn compile` and report any errors.

Step 2 — Verify Claude sees the command

Restart Claude Code and type / — /new-resource should appear in the picker. Type /help new-resource to confirm the description and argument-hint are loaded.

Step 3 — Generate a real resource

> /new-resource Amendment

Claude reads the existing filing/ package as reference, generates the five files under amendment/, then runs mvn compile. Watch the file ribbon — you should see five Edit/Write calls in sequence. If mvn compile fails, ask Claude to fix the errors and re-compile.

Step 4 — Verify the structure matches the existing pattern

$ tree src/main/java/com/publicrecords/api/amendment src/test/java/com/publicrecords/api/amendment
$ mvn test
$ curl http://localhost:8080/amendments  # in another terminal after mvn spring-boot:run

Expected: five new files in the right packages, all tests pass, and /amendments returns [] (no seed data, but the endpoint responds 200).

Step 5 — Generate a second resource and confirm consistency

> /new-resource Termination

The command should produce a structurally identical package — same field naming, same controller method signatures, same test shape. That consistency is the whole point of a slash command: the next teammate doesn't have to remember conventions because the command bakes them in.

Step 6 — Convert it to a Skill (optional, for autoinvocation)

Slash commands are explicit (/new-resource X). A Skill with the same description fires whenever Claude infers it's needed. Convert:

$ mkdir -p .claude/skills/new-resource
$ mv .claude/commands/new-resource.md .claude/skills/new-resource/SKILL.md

Now ask Claude in plain language: "We need a new entity for UCC continuation filings." The skill should fire without you typing the command. (If it doesn't, your description field isn't specific enough — Claude won't auto-invoke a skill it isn't confident about.)

Knowledge Check

Module Summary

• Commands and skills merged. New work uses skill format; old .claude/commands/*.md still works.
• 4 scopes: Enterprise > Personal > Project. Plugins use plugin:skill namespace.
• SKILL.md frontmatter has 15 fields; you'll use description, allowed-tools, disable-model-invocation, context, arguments most often.
• Substitution: $ARGUMENTS, $N, $name, ${CLAUDE_SESSION_ID}, ${CLAUDE_EFFORT}, ${CLAUDE_SKILL_DIR}.
• Inline shell injection: !`cmd` for one-liners, ```! ... ``` for blocks. Disable via disableSkillShellExecution.
• context: fork + agent: for isolated research; inline for reference content.
• Bundled: /simplify, /batch, /debug, /loop, /claude-api. Plus /init, /review, /security-review.
• Trigger extended thinking by including "ultrathink" anywhere in skill content.