Claude Code represents a shift in terminal-based development by allowing engineers to interact with their codebase through a persistent, agentic interface. While the core model possesses a baseline understanding of programming tasks, its utility is significantly expanded through “skills.” These skills are modular extensions that provide Claude with specific instructions, custom commands, and the ability to execute complex, multi-step workflows.
A skill in Claude Code is essentially a directory containing a SKILL.md file. This file uses YAML frontmatter to define metadata and Markdown to provide the logic or instructions the agent follows. By implementing skills, organizations can codify their internal standards, automate repetitive architectural shifts, and integrate third-party tools directly into the Claude Code environment.
The architecture of Claude Code skills
Skills are built on the Agent Skills open standard, ensuring interoperability across various AI development tools. Claude Code enhances this standard by adding features such as invocation control, subagent execution, and dynamic context injection.
A skill is defined by its location, which determines its scope of influence:
| Location | Path | Application scope |
|---|---|---|
| Enterprise | Managed settings | All users within a verified organization |
| Personal | ~/.claude/skills/<name>/SKILL.md | All projects for a specific user |
| Project | .claude/skills/<name>/SKILL.md | Only the current repository or directory |
| Plugin | <plugin>/skills/<name>/SKILL.md | Active only where the plugin is enabled |
When skills share the same name across these levels, the hierarchy follows a “most specific to most general” override logic: Enterprise takes precedence over Personal, which takes precedence over Project.
Core components of a SKILL.md file
The SKILL.md file is the entry point for every custom capability. It consists of two primary sections:
- YAML frontmatter: Encased in — markers, this section contains configuration fields like name, description, and allowed-tools.
- Markdown content: The body of the file containing the prompt logic, step-by-step instructions, or reference material Claude uses when the skill is active.
How do you activate Claude Skills?
Claude Code supports two primary methods of skill activation: manual invocation by the user and automatic discovery by the model.
Manual invocation (Slash commands)
Users can trigger any skill by typing / followed by the skill name in the Claude Code terminal. For example, a skill named review-pr can be executed by typing /review-pr. This is the preferred method for tasks with significant side effects, such as deployments or database migrations.
Automatic discovery
Claude analyzes the description field in a skill’s frontmatter to determine its relevance to a user’s natural language query. If a user asks, “How does the authentication flow work?”, and a skill exists with a description like “Explains codebase architecture and logic flows,” Claude may automatically load and apply that skill to its response.
Controlling model access
To prevent Claude from executing sensitive tasks without explicit consent, developers can use the disable-model-invocation: true flag in the frontmatter. This ensures the skill only runs when the user manually enters the slash command. Conversely, user-invocable: false hides a skill from the slash command menu, reserving it for background knowledge that Claude should only use as reference.
Advanced skill capabilities
Beyond simple text instructions, skills can orchestrate sophisticated operations through subagents and shell execution.
Subagent execution (context: fork)
By setting context: fork in the frontmatter, a skill runs in an isolated environment. This “subagent” does not see the main conversation history, which preserves the primary context window and prevents “hallucination” from irrelevant chat data. This is particularly useful for “deep research” tasks where an agent must scan hundreds of files to find a specific pattern.
Dynamic context injection
Skills can execute shell commands and inject the output directly into the prompt before Claude receives it. This is achieved using the ! command syntax. For example:
---
name: pr-status
description: Fetches current PR status
---
Current PR diff: !`gh pr diff`
Summarize the changes above.In this scenario, the output of the GitHub CLI is retrieved and placed into the prompt, providing Claude with real-time data that was not present in its initial training set or the local file system alone.
Bundled skills for large-scale operations
Claude Code ships with several pre-installed “bundled skills” that demonstrate the power of the platform’s orchestration capabilities. Unlike built-in commands that use fixed logic, bundled skills are prompt-based playbooks.
The /simplify command
The /simplify skill reviews recently changed files for code reuse, quality, and efficiency. It operates by spawning three parallel review agents, aggregating their findings, and then applying the suggested fixes to the codebase.
The /batch command
For large-scale refactoring, the /batch skill can automate changes across an entire repository. It decomposes a large instruction (e.g., “Migrate all components from Class to Functional”) into 5 to 30 independent units. It then spawns background agents in isolated git worktrees to implement the changes and run tests before opening pull requests.
To see these capabilities in action within your own infrastructure, organizations often start with an AI discovery session to identify which manual workflows are most eligible for automation via custom skills. For teams looking to implement these complex subagent architectures, our Claude workshop provides the deep-dive training necessary to scale these tools safely across an enterprise.
Building visual output skills
A powerful pattern in skill development is the generation of interactive visual content. Because skills can execute scripts (Python, Node.js, etc.), they can generate HTML files to visualize complex data.
An example is a “Codebase Visualizer” skill that:
- Scans the local directory using a Python script.
- Calculates file sizes and categorizes extensions.
- Generates a self-contained HTML file with a collapsible tree view and bar charts.
- Opens the file automatically in the user’s default browser.
This allows the developer to gain a high-level overview of project structure that would be difficult to parse through a standard text-based terminal output.
Technical configuration reference
The following table details the YAML frontmatter fields available for customizing skill behavior:
| Field | Dscription | Default |
|---|---|---|
| Name | The identifier used for the /name command. | Directory name |
| Description | The metadata used by Claude to decide when to auto-load the skill. | First paragraph of MD |
| Disable-model-invocation | If true, Claude cannot trigger this skill automatically. | false |
| Allowed-tools | Limits which tools (e.g., Bash, Read, Grep) Claude can use. | All tools |
| Context | Set to fork to run in an isolated subagent. | Inline |
| Agent | Defines which subagent type to use (e.g., Explore, Plan). | general-purpose |
String substitutions
Skills support dynamic values through placeholders:
- $ARGUMENTS or $0, $1: Accesses text passed after the slash command.
- ${CLAUDE_SESSION_ID}: Inserts the unique ID of the current terminal session, useful for logging.
For teams looking to integrate these advanced workflows, professional AI implementation services can assist in mapping existing CI/CD pipelines and developer experience (DevEx) standards into the Claude Code skill ecosystem.
Frequently asked questions
How do I troubleshoot a skill that isn’t triggering?
First, verify that the skill appears in the list of available skills by checking the internal logs or using the /help command. If the skill is not auto-triggering, ensure the description field in the YAML frontmatter contains keywords that align with your natural language request. You can also invoke the skill directly using its /name to confirm the logic within the Markdown body is functional.
What is the difference between a command and a skill?
While older versions of Claude Code used a commands directory, these have been merged into the skills system. Skills are the recommended format as they support additional features like supporting files (templates, scripts, examples), subagent execution, and more granular invocation controls.
Is there a limit to how many skills I can have?
There is no hard limit on the number of skills you can have, but they must fit within a 4,000-token budget (roughly 2% of the context window). If your descriptions exceed this, you’ll receive a warning when running /context. You can increase this limit by adjusting the SLASH_COMMAND_TOOL_TOKEN_BUDGET environment variable.
Can skills interact with private APIs?
Yes, by using the ! shell execution syntax or the Bash tool, a skill can call internal CLI tools, fetch data from private APIs (using curl or gh), and then pass that data to Claude for analysis or processing.
