Slash commands and Agent Skills are the two primary mechanisms for packaging repeatable Claude Code workflows into reusable building blocks. Knowing when to use each, how to structure them, and how they load context progressively is tested throughout Domain 3.
Think of a large accounting firm. When a junior analyst presses Alt+R on their keyboard, a macro fires: it opens the monthly template, inserts today's date, and formats the header. That’s a slash command — a short, precise, deterministic trigger for a known sequence of steps the user invokes on purpose.
Now think of the firm’s onboarding manual for new hires in the Tax Compliance team. It teaches the full workflow: “First verify the client’s jurisdiction, then check the applicable code sections, then draft the filing in the standard template, then run the compliance checklist.” A new analyst reads only the section relevant to today’s task — they don’t read the whole manual every time. That’s an Agent Skill — a structured, progressive-disclosure knowledge package that activates automatically when relevant.
Slash commands: user-invoked, immediate, single-purpose. Skills: auto-detected, multi-step, domain-expert knowledge layers.
Custom slash commands in Claude Code are Markdown files stored in .claude/commands/ (project-level, committed to git) or ~/.claude/commands/ (personal, global). When a user types /command-name, Claude reads the Markdown file and executes the instructions as a prompt template.
# Project-level (committed, shared with team) .claude/ └── commands/ ├── review-pr.md # /review-pr ├── write-tests.md # /write-tests ├── deploy-check.md # /deploy-check └── summarize-diff.md # /summarize-diff # Personal global (not committed, cross-project) ~/.claude/commands/ ├── my-style.md # /my-style └── standup-prep.md # /standup-prep
A slash command file is a plain Markdown prompt with optional $ARGUMENTS placeholder that injects whatever the user types after the command name.
# PR Review ## Instructions You are conducting a structured code review for the current branch. Focus your review on: 1. Correctness — does the logic match the stated intent? 2. Security — any injection risks, exposed secrets, or missing auth checks? 3. Test coverage — are new code paths tested? 4. Naming & style — consistent with project CLAUDE.md conventions? ## Scope Review only files changed in: $ARGUMENTS If no argument provided, review all staged changes. ## Output Format For each file: summary, issues (CRITICAL / WARNING / SUGGESTION), and fix recommendations. End with an overall APPROVE / REQUEST_CHANGES verdict.
The $ARGUMENTS placeholder turns a static template into a parameterized command. A user can type /review-pr src/payments/ to scope the review to that directory, or /write-tests UserService to target a specific class. Without $ARGUMENTS, commands are fixed-purpose but still valuable for zero-friction repeated tasks.
| Use Slash Commands When… | Example |
|---|---|
| The task is user-initiated and deliberate | /deploy-check before merging a PR |
| The workflow is short (<5 steps) and known upfront | /summarize-diff for standup notes |
| No external tool calls or MCP integration needed | /write-changelog from git log |
| Team needs a shared, version-controlled workflow | /security-scan standard checklist |
| The prompt is simple enough to fit in one Markdown file | /explain-error with error as $ARGUMENTS |
An Agent Skill is a folder that packages structured workflow instructions, optional scripts, reference docs, and asset templates. Unlike slash commands (user-invoked), skills activate automatically when Claude determines the current task matches the skill’s declared trigger conditions.
sprint-planner/ # kebab-case folder name (required) ├── SKILL.md # Required — MUST be exactly this name ├── scripts/ # Optional — executable helpers │ ├── fetch_velocity.py │ └── validate_tasks.sh ├── references/ # Optional — detailed docs linked from SKILL.md │ ├── estimation-guide.md │ └── sprint-templates/ └── assets/ # Optional — templates, icons, fonts └── sprint-report.md
The main instruction file must be named SKILL.md exactly (case-sensitive). skill.md, SKILL.MD, and Skill.md will all fail to load. The skill folder name must use kebab-case: sprint-planner ✓ — Sprint Planner ✗, sprint_planner ✗, SprintPlanner ✗. Do not include a README.md inside the skill folder.
Skills use a three-level loading system that minimizes token usage while keeping specialized knowledge available:
The name and description fields are always loaded. Claude reads these to decide whether the skill is relevant — without loading the full instructions.
The full instruction body is loaded when Claude determines the task matches the skill. Contains step-by-step workflows, examples, and error handling.
Files in references/, scripts/, and assets/ are loaded only as Claude navigates to them while executing the workflow. Never pre-loaded.
--- name: sprint-planner description: Manages end-to-end sprint planning workflows including velocity analysis, task creation, and capacity allocation. Use when user says "plan sprint", "create sprint tasks", "sprint planning", or asks to "set up next sprint" or "organize sprint backlog". license: MIT metadata: author: platform-team version: 2.1.0 mcp-server: linear --- # Sprint Planner Skill ## Step 1: Gather Context 1. Fetch current project velocity from Linear (via MCP: `get_velocity`) 2. Get team capacity for the sprint period (via MCP: `get_capacity`) 3. List backlog items (via MCP: `list_backlog`) ## Step 2: Analyze & Prioritize Consult `references/estimation-guide.md` for story point conventions. Sort backlog by priority × impact. Flag items exceeding capacity. ## Step 3: Create Sprint Tasks For each prioritized item, call MCP `create_task` with: - title, estimated_points, assignee, sprint_id ## Step 4: Generate Report Use `assets/sprint-report.md` template. Populate: velocity, capacity, committed items, risks. ## Error Handling If Linear MCP unavailable: surface error immediately, do not guess data. If capacity < committed points: flag as over-planned and ask for confirmation.
The description field in the YAML frontmatter is how Claude decides whether to load the skill. It must include both what the skill does AND when to use it (trigger phrases users would actually say). A description like “Helps with projects” will almost never trigger. A description citing specific phrases like “Use when user says ‘plan sprint’ or ‘create sprint tasks’” triggers reliably. On the exam, questions asking “Why does the skill never activate?” always trace back to a vague or trigger-phrase-free description.
Choosing the right mechanism prevents over-engineering (turning a 3-line slash command into a multi-file skill) and under-engineering (using a slash command for a complex multi-MCP workflow that needs structured guidance).
| Dimension | Slash Command | Agent Skill |
|---|---|---|
| Activation | User-initiated (types /command) | Auto-detected by Claude from task context |
| Structure | Single Markdown file | Folder: SKILL.md + optional scripts/refs/assets |
| Context Loading | Entire file loaded immediately | Progressive: frontmatter → body → linked files |
| Complexity | Simple, 1–5 step prompts | Multi-step workflows, MCP orchestration, domain knowledge |
| MCP Integration | Not designed for it | Core use case; coordinates multiple MCP tools |
| Token Efficiency | Full file always in context | Only loads what's needed via progressive disclosure |
| Location | .claude/commands/ or ~/.claude/commands/ | Skill folder uploaded to Claude or placed in skills dir |
| Distribution | Via git (committed with project) | Upload to Claude.ai, deploy org-wide, or via API |
| Best For | PR reviews, changelogs, checklists | Sprint planning, onboarding, design-to-code handoffs |
The most-tested distinction: slash commands require the user to explicitly invoke them by typing /name. Skills are automatically detected by Claude based on the task description matching the skill's frontmatter. If an exam question says “the team wants Claude to automatically apply the workflow without users needing to remember a command” — the answer is a Skill, not a slash command.
The progressive disclosure system ensures Claude never loads unnecessary tokens. Here’s exactly what happens when a skill-enabled session receives a task:
# Security Scan Perform a targeted security review of: $ARGUMENTS ## Checklist For each file in scope, evaluate: ### 1. Injection Risks - SQL: are all DB queries parameterized? No raw string interpolation. - Command injection: shell calls use list args, not string input? - XSS: user input sanitized before rendering? ### 2. Authentication & Authorization - Every endpoint has an explicit auth check (not relying on middleware assumption). - Privilege levels match what the endpoint actually needs. ### 3. Secrets & Data Exposure - No hardcoded credentials, tokens, or private keys. - Sensitive fields masked in logs (passwords, card numbers, SSNs). - API responses don't leak internal IDs or stack traces. ### 4. Dependency Risks - Note any packages with known CVEs if visible from imports. ## Output Table: File | Risk Level (CRITICAL/HIGH/MEDIUM/LOW) | Finding | Recommendation End with: Pass ✓ or Fail ✗ and top-3 priority fixes.
--- name: pr-review-linker description: Automated PR review that analyzes code changes, generates structured feedback, and links findings to Linear issues. Use when user says "review this PR", "code review", "review my changes", "check this pull request", or "review before merging". metadata: author: eng-platform version: 1.0.0 mcp-server: linear --- # PR Review Linker ## Step 1: Gather PR Context 1. Run: `git diff origin/main...HEAD --stat` to see changed files 2. Run: `git log origin/main...HEAD --oneline` to understand commit intent 3. Ask user for PR title if not provided ## Step 2: Structured Code Review Consult `references/review-checklist.md` for team standards. Review categories (in order): - **Correctness**: logic matches stated intent? - **Security**: see `references/security-rules.md` - **Test coverage**: new paths have tests? - **Style**: matches CLAUDE.md conventions? ## Step 3: Link to Linear For each CRITICAL or HIGH finding: - Call MCP `search_issues` to find related Linear issue - Call MCP `add_comment` to attach finding to the issue ## Step 4: Generate Review Summary Use template in `assets/review-summary.md`. Fields: PR title, verdict (APPROVE/CHANGES), findings count by severity, linked Linear issues, top 3 action items. ## Error Handling - If git commands fail: report "Not in a git repo" and stop. - If Linear MCP unavailable: complete review, skip linking step, note it. - If no changes found: output "No changes detected vs main."
Keep the most critical “always check X” or “never do Y” rules inline in the SKILL.md body so they’re unmissable. Move verbose reference content (long checklists, API docs, templates) into references/ files and link to them. Claude loads linked files only when that step is reached — so the body stays scannable and critical rules stay prominent.
Three proven patterns cover the majority of real-world skill use cases. Knowing which pattern to apply — and why — is exam-tested judgment.
Use when: Multi-step process must happen in a specific order, with dependencies between steps.
## Workflow: Onboard New Customer ### Step 1: Create Account MCP tool: `create_customer` | params: name, email, company → Store returned customer_id for steps below ### Step 2: Setup Payment MCP tool: `setup_payment_method` | requires: customer_id from Step 1 → Wait for verification before proceeding ### Step 3: Create Subscription MCP tool: `create_subscription` | params: plan_id, customer_id → Do NOT proceed if Step 2 verification failed ### Step 4: Send Welcome Email MCP tool: `send_email` | template: welcome_email Key: explicit ordering + dependency gates + rollback instructions
Use when: Output quality improves through validation and iteration cycles (e.g., report generation, design review).
## Iterative Report Creation ### Initial Draft 1. Fetch data via MCP → generate first draft 2. Save to temp file (do not deliver yet) ### Quality Check Run: `scripts/validate_report.py --input draft.md` Check for: missing sections, data gaps, formatting errors ### Refinement Loop (max 3 iterations) IF validation issues found: - Fix each identified issue - Re-run validate_report.py - Repeat until PASS or max iterations reached ### Finalization Apply final formatting → deliver to user Key: explicit quality criteria + iteration cap + validation scripts
Use when: A workflow spans multiple external services, each providing a different capability.
## Design-to-Development Handoff ### Phase 1: Design Export (Figma MCP) 1. Export assets from Figma: `export_design_assets` 2. Generate component spec: `get_design_specs` ### Phase 2: Asset Storage (Drive MCP) 1. Create project folder: `create_folder` 2. Upload all assets: `upload_files` 3. Generate shareable links: `get_share_links` ### Phase 3: Task Creation (Linear MCP) 1. Create dev tasks: `create_issue` for each component 2. Attach asset links to each task ### Phase 4: Notify Team (Slack MCP) Post handoff summary to #engineering with links + ETA Key: clear phase separation + data passing between MCPs + centralized error handling
| Pattern | Trigger Condition | Key Technique |
|---|---|---|
| Sequential | Steps have hard dependencies; order matters | Explicit step numbers, dependency gates, rollback instructions |
| Iterative | Quality improves with validation cycles | Validation scripts, iteration cap, quality criteria |
| Multi-MCP | Workflow spans multiple external services | Phase separation, data passing between phases, unified error handling |
Slash commands are distributed simply by committing the .claude/commands/ folder to the project repository. Every team member who clones the repo automatically has access to the team’s shared commands. Personal commands go in ~/.claude/commands/ and are never committed.
| Distribution Method | How | Best For |
|---|---|---|
| Individual Upload | Zip skill folder → Claude.ai Settings → Capabilities → Skills → Upload | Personal use, testing, small teams |
| Claude Code Directory | Place skill folder in Claude Code skills directory | Developer workflows, CLI-heavy teams |
| Organization Deployment | Admins deploy workspace-wide (automatic updates, centralized management) | Enterprise teams needing consistent Claude behavior |
| API Integration | /v1/skills endpoint + container.skills parameter in Messages API | Production apps, automated pipelines, agents |
| GitHub + Docs | Public repo with README (outside skill folder) + link in MCP documentation | Open-source skills, MCP server companions |
When skills are used programmatically via the Messages API, they require the Code Execution Tool beta to be enabled — this provides the secure environment skills need to run scripts. The exam may ask what additional capability is required when deploying skills in production API applications. Answer: Code Execution Tool beta.
| Level | Location | Committed? | Use Case |
|---|---|---|---|
| Personal | ~/.claude/commands/ | Never | Individual style preferences, personal productivity macros |
| Project | .claude/commands/ in repo | Yes | Team-shared workflows tied to this specific project |
| Organization | Admin-deployed workspace skills | N/A | Company-wide standards, compliance workflows, onboarding |
Writing “Helps with projects.” in the description field. Claude cannot determine when to load the skill. Result: skill never auto-activates and users must manually invoke it every time.
Naming the main file skill.md, SKILL.MD, or instructions.md. SKILL.md is case-sensitive and exact. Any variation causes the skill to silently fail to upload or load.
Putting entire API documentation, style guides, and all workflow steps inline in SKILL.md. This forces Claude to load all tokens every time the skill triggers, eliminating the token efficiency of progressive disclosure.
Creating a multi-file skill folder for a 3-step task that doesn’t use MCP or have real multi-step orchestration. Over-engineering — a slash command would achieve the same result with far less setup overhead.
Using a slash command to orchestrate multi-step MCP calls. Slash commands have no progressive disclosure or structured error handling — the entire prompt is loaded at once with no ability to reference linked scripts.
Including a README.md inside the skill folder. All skill documentation must go in SKILL.md or references/. README.md belongs in the parent GitHub repo for human users, not inside the skill itself.
Always include 3–5 concrete phrases users would actually say: “Use when user says ‘plan sprint’, ‘set up next sprint’, or ‘create sprint tasks’”. Test triggering by asking Claude: “When would you use the [skill name] skill?”
Keep SKILL.md body focused on the core workflow steps (under ~50 lines). Move detailed style guides, API documentation, and long checklists to references/ files and link to them from the step that needs them.
Slash command for user-initiated, simple, non-MCP tasks. Skill for auto-detected, multi-step, MCP-orchestrated workflows. Never conflate the two — each mechanism has a sweet spot where it dramatically outperforms the other.
Scenario: A platform team wants to standardize how Claude performs PR reviews across all projects. They want the review to automatically trigger when developers describe their PR, link findings to Linear issues, and follow a security checklist. What mechanism should they use and how should it be structured?
Correct answer: An Agent Skill (not a slash command) because: (1) auto-detection needed without explicit user invocation, (2) multi-step workflow with MCP integration (Linear), (3) references a security checklist (linked file via progressive disclosure), (4) deployed org-wide via admin workspace deployment. SKILL.md contains the step-by-step workflow; security checklist goes in references/; Linear calls in the workflow steps.
Common distractor: “A slash command in .claude/commands/ with the full checklist inline” — wrong because slash commands require explicit invocation and cannot efficiently handle MCP orchestration across multiple steps with linked reference material.
If an exam question states “the skill never activates automatically even when the user describes a relevant task,” the root cause is always the description field. Fix: add specific trigger phrases users would actually use. To debug: ask Claude “When would you use [skill name]?” — if Claude quotes back a vague description, the description needs more specific trigger conditions.
/command-name. Skills activate automatically when Claude determines the task matches the skill’s description. If the team wants zero-friction automatic activation, use a Skill.SKILL.md. No README.md inside the folder. Optional subdirs: scripts/, references/, assets/. Any naming deviation silently breaks the skill..claude/commands/.