Agent Skills Cheatsheet

Single-page quick reference for everything you need while building agent skills.

Skill File Structure

Skill directory layout

my-skill/
  SKILL.md          # Main skill file (required)
  templates/        # Supporting templates (optional)
  config/           # Supporting configs (optional)
  scripts/          # Helper scripts (optional)

SKILL.md anatomy

---
description: Short summary of what the skill does
allowed-tools:                    # optional
  - Read
  - Write
  - Bash(npm run *)
context:                          # optional
  - file: path/to/file
  - command: shell-command
---

# Skill Title

Instructions for the agent go here. Use Markdown.
Reference $ARGUMENTS and other substitution variables.

Frontmatter Fields

Field	Type	Required	Purpose
`description`	`string`	Yes	Discovery and display text. Keep under 100 chars, start with a verb.
`allowed-tools`	`string[]`	No	Restrict which tools the skill can use. Omit for full access.
`context`	`object[]`	No	Inject file contents or command output at load time.

Substitution Variables

Variable	Source	Description
`$ARGUMENTS`	User	Full text after skill name
`$1` - `$9`	User	Whitespace-split positional args
`${CLAUDE_SESSION_ID}`	Built-in	Unique session identifier
`${SKILL_DIR}`	Built-in	Absolute path to skill directory
!`cmd`	Dynamic	Shell command output injected at load time

ℹ️Processing order

String substitutions ($ARGUMENTS, $1-$9, built-ins) are applied first, then !`command` expressions execute with the substituted values.

Allowed Tools Syntax

Syntax	Meaning
`Read`	Allow the Read tool (no arguments needed)
`Write`	Allow the Write tool
`Edit`	Allow the Edit tool
`Glob`	Allow the Glob tool
`Grep`	Allow the Grep tool
`Bash(exact cmd)`	Allow only this exact shell command
`Bash(git *)`	Allow any git subcommand (glob pattern)
`Bash(npm run *)`	Allow any npm script
`Bash(*)`	Unrestricted shell access (use with caution)
`WebSearch`	Allow web search
`WebFetch`	Allow fetching URLs
`Task`	Allow subtask creation

Skill Locations (Priority Order)

Priority	Location	Scope	Use Case
1 (highest)	Enterprise managed settings	Organization	Enforced standards, cannot be overridden
2	`~/.claude/skills/`	User (all projects)	Personal workflows that follow you everywhere
3	`.claude/skills/`	Project (team)	Shared skills committed to version control
4 (lowest)	Plugin skills	External	Third-party skills from registries or packages

💡Same name = highest priority wins

When skills share the same name across locations, the higher-priority location takes precedence. Enterprise skills always win.

Common Patterns

Read-Only Analysis

Pattern: read-only

---
description: Analyze code complexity and suggest refactoring targets
allowed-tools:
  - Read
  - Glob
  - Grep
---

Scoped Shell Access

Pattern: scoped shell

---
description: Run tests for a specific module
allowed-tools:
  - Bash(npm test -- --filter $1)
  - Bash(npm run lint -- $1)
  - Read
---

File Generation with Templates

Pattern: templated generation

---
description: Generate a new component from project templates
allowed-tools:
  - Read
  - Write
  - Glob
context:
  - file: .templates/component.tsx.hbs
---

Read the template from context. Create a new component
named $1 in src/components/$1/.

Git-Aware Workflow

Pattern: git-aware

---
description: Generate release notes from recent commits
allowed-tools:
  - Bash(git *)
  - Write
---

Current branch: !`git branch --show-current`
Commits since last tag:
!`git log $(git describe --tags --abbrev=0)..HEAD --oneline`

Generate release notes grouped by conventional commit type.

Dynamic Tool Scoping

Pattern: dynamic scoping

---
description: Work with a specific service
allowed-tools:
  - Bash(docker compose * $1)
  - Bash(docker logs $1)
  - Read
---

Manage the **$1** service in the Docker Compose stack.

Supporting Files

Pattern: supporting files

---
description: Create an API endpoint following our conventions
allowed-tools:
  - Read
  - Write
---

Read the route template from:
${SKILL_DIR}/templates/route.ts.hbs

Read the test template from:
${SKILL_DIR}/templates/route.test.ts.hbs

Create a new endpoint for $ARGUMENTS using these templates.