Learn Claude Skills
Guide

Claude Code Cheat Sheet: Skills Edition

Quickly look up SKILL.md frontmatter keys, directory layouts, slash commands, environment variables, and trigger rules.

~6 min read

When you are actively building Claude skills, you do not want to re-read long tutorials just to check whether a frontmatter key uses a hyphen or an underscore, or whether personal skills override project skills.

Here is the definitive quick-reference cheat sheet for skill authors: frontmatter schemas, directory hierarchies, character budgets, slash commands, and essential environment variables.

SKILL.md frontmatter reference

There are two specifications to keep in mind: the universal open standard (portable across all agent tools) and the Claude Code extended fields.

Comment: Universal Open Standard (agentskills.io) - Portable everywhere
File: name: # Required. kebab-case string (must match directory name)
File: description: # Required. 1 to 1024 chars. The primary matching trigger
File: license: # Optional. Free text (e.g. MIT, Apache-2.0)
File: compatibility: # Optional. String <= 500 chars (e.g. "requires node >= 18")
File: metadata: # Optional. Key-value string map
File: allowed-tools: # Optional. Space-separated tool list
Comment: Claude Code Extended Fields (CLI only)
File: when_to_use: # Appended to description. Truncates at 1,536 total chars
File: disable-model-invocation: true # Runs ONLY on explicit slash command
File: user-invocable: false # Claude auto-triggers only; hidden from menu
File: context: fork # Spawns an isolated subagent
File: shell: powershell | bash # Overrides default shell for ! commands
The core fields recognized in SKILL.md frontmatter.

Directory resolution hierarchy

When skills share the same name, Claude Code resolves them using strict precedence order:

You type: /skills
Output: Indexed skills:
Output: - commit-helper (.claude/skills/commit-helper) [project]
Output: - release-notes (~/.claude/skills/release-notes) [personal]
Output: - github:pr-review (plugin:github) [plugin]
Note: Project skills override personal skills when names match.
Checking active skills index across all hierarchy scopes.
  1. Enterprise managed: `/etc/claude-code/.claude/skills/` (overrides all user settings).
  2. Personal skills: `~/.claude/skills/<name>/SKILL.md` (available across all projects).
  3. Project skills: `.claude/skills/<name>/SKILL.md` (scoped to current repository).
  4. Plugin skills: `<plugin>/skills/<name>/SKILL.md` (namespaced as `plugin-name:skill-name`).

Essential session commands and shortcuts

You type: /permissions
Output: Active mode: Auto mode
Output: Allow rules: Bash(npm test*), FileEdit(src/**)
You type: /doctor
Output: Environment check: All 15 skills valid, no syntax errors.
Note: Run /doctor whenever you pull upstream changes to verify skill health.
Quick health and permissions verification.
  • /skills: Lists all skills currently indexed and available in the active session.
  • /permissions: Displays active permission mode and allow/deny rules.
  • /compact [note]: Compresses transcript history while retaining key task context.
  • /clear: Resets conversation history completely while keeping CLAUDE.md and skills active.
  • /doctor: Runs system integrity checks on Node, Git, permissions, and skill manifests.
  • Shift+Tab: Cycles permission modes between Normal, Auto, and Bypass.

Environment variables reference

Useful environment variables for configuring advanced agent behavior:

  • ANTHROPIC_API_KEY: Authenticates non-interactively in CI/CD and headless runner pipelines.
  • CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH: Controls subagent nesting limits (defaults to 3).
  • CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS: Caps simultaneous background subagent workers (defaults to 20).
Stay updated

Get new guides in your inbox

One task, one guide, done fast. Practical Claude Code skills, zero noise.

Keep learning

Related guides and paths

Claude Code Slash Commands for Beginners

This guide covers the slash commands that matter on day one, grouped by job. It also covers what command lists skip: your own skills are invokable as /name.

  • ~7 min