Unlocking Claude Code Agent Skills 2.0: A Deep Dive into Subagents, Context Injection, and Built‑in Commands

Claude Code’s skill system has been upgraded to Agent Skills 2.0, a programmable agent platform where each skill is a self‑contained program with isolated context, dynamic data injection, lifecycle hooks, and formal evaluation.

Main Changes

Commands and skills are now unified. Files can still live under .claude/commands/ but the recommended location is .claude/skills/ because it supports richer front‑matter, auxiliary files, and the new capabilities.

Every Claude Code installation ships with built‑in slash commands: /simplify – launches three parallel review agents for code reuse, quality, and efficiency. /batch – analyses a repository, splits a large change into 5‑30 independent units, creates a plan, and runs a background agent for each unit in a separate Git worktree. /debug – reads the session debug log and diagnoses problems, optionally focusing on a specific issue. /claude-api – automatically loads Anthropic SDK reference material for the detected language (Python, TypeScript, Java, Go, Ruby, C#, PHP, cURL).

Sub‑Agent Execution (Context Fork)

Adding context: fork to a skill’s front‑matter creates an isolated sub‑agent with its own 200 000‑token window. The skill’s markdown becomes the sub‑agent’s task prompt, and the optional agent field selects the execution environment (Explore, Plan, general‑purpose, or a custom agent). Results are summarized back into the main conversation, keeping the primary dialog clean.

Dynamic Context Injection

Prefix a shell command with ! to execute it before Claude receives the prompt; the command’s output replaces the placeholder. Example: ! git branch This enables real‑time data such as PR diffs, file lists, or test results to be injected directly into the prompt.

Fine‑Grained Permissions

Three front‑matter fields control who can invoke a skill and what tools it may use: disable-model-invocation: true – only the user can trigger the skill. user-invocable: false – only Claude can invoke the skill automatically. allowed-tools – restricts the set of tools (e.g., Bash, Read, Grep, Glob) the skill may call.

Skill File Structure

Each skill resides in its own directory with a mandatory SKILL.md entry point and optional auxiliary files:

my-skill/
├── SKILL.md          # Main instructions (required)
├── reference.md      # Detailed docs (loaded on demand)
├── examples/
│   └── sample.md      # Example outputs
├── scripts/
│   └── validate.sh   # Executable scripts
└── ...

The SKILL.md file consists of a YAML front‑matter block followed by the markdown instructions. Example front‑matter:

---
name: explain-code
description: Explains code with visual diagrams and analogies.
---

Key fields include name, description, argument-hint, model, context, agent, hooks, and others that shape behavior.

Built‑In Skills Overview

/simplify : runs three parallel agents to check code reuse, quality, and performance; optional focus argument (e.g., /simplify focus on memory efficiency).

/batch : accepts a change description, analyses the repo, splits work into independent units, generates a plan, and launches a background agent per unit in its own Git worktree, creating pull requests for each.

/debug : reads the session log and diagnoses issues; can be scoped with a description (e.g., /debug why is the Bash tool failing?).

/claude-api : auto‑activates when Anthropic SDK imports are detected, providing language‑specific API reference, tool‑use guidance, streaming, batching, structured output, and common pitfalls.

Example Skill Definitions

These examples illustrate various features:

---
name: deep-research
description: Research a topic thoroughly in the codebase
context: fork
agent: Explore
---
Research $ARGUMENTS thoroughly:
1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with specific file references

Variable substitution supports $ARGUMENTS, indexed arguments ( $ARGUMENTS[0] or $0), session ID ( ${CLAUDE_SESSION_ID}), and skill directory ( ${CLAUDE_SKILL_DIR}).

Testing and Evaluation

Three testing dimensions are recommended:

Trigger testing – verify that the skill loads when appropriate and stays silent otherwise (target ≥ 90 % hit rate, zero false triggers).

Functional testing – ensure correct output across normal, edge, and error cases.

Risk & quality testing – run A/B comparisons with and without the skill, measuring output quality, token consumption, and task‑completion speed.

Iterative Development Workflow

Identify a difficult task where Claude fails.

Iterate until Claude succeeds by refining prompts, adding examples, and polishing instructions.

Extract the successful method into a reusable skill.

Expand test coverage for variants and edge cases.

Version‑control the skill, commit changes with rationale, and roll back if performance regresses.

Best Practices

Keep SKILL.md under 500 lines; move detailed docs to auxiliary files.

Use structured formats (bulleted or numbered lists) to reduce token usage.

Provide concrete examples of correct and incorrect behavior.

Write specific descriptions to improve trigger accuracy.

Load skills conditionally; avoid adding every skill to every session.

Treat skills as code: commit, document reasons, and revert regressions.

Portability and Open Standard

The Agent Skills open standard (agentskills.io) makes skills portable across AI tools. Whether you build a personal review-pr skill or a plugin with dozens of agents, the underlying architecture remains the same: a SKILL.md file, optional auxiliary files, and a set of front‑matter fields that precisely control behavior. Full documentation is available at https://code.claude.com/docs/en/skills.