Claude Code Skills and Agents: Advanced Techniques

Claude Code handles 80% of a developer’s day-to-day work out of the box. The remaining 20% is repeatable workflows, project-specific checks, team standards, and automations that a plain prompt can’t capture. Skills, Agents, Hooks, and Memory turn Claude Code from a general-purpose assistant into a tool built around a specific project and team.

This guide covers the full extension system: from writing your first slash command to orchestrating hundreds of parallel subagents through Dynamic Workflows. Every section includes ready-to-copy configurations.

Skills: Slash Commands on Steroids

Skills (slash commands) are markdown files that Claude Code executes as instructions. The user types /review, and Claude receives a detailed prompt with context, constraints, and an output format.

Location and Scope

Skills live in several places. The new format is a <skill-name>/SKILL.md directory; the older .claude/commands/<skill>.md still works, but skills take priority:

A .claude/skills/deploy/ directory with SKILL.md inside becomes the /deploy command. Nested directories are supported: apps/web/.claude/skills/deploy/SKILL.md becomes /apps/web:deploy when there’s a name conflict.

File Format

The simplest skill is plain markdown, no frontmatter needed:

Check the current code for SQL injection, XSS, and authentication issues.
Point to specific lines and assign a severity level to each finding.

Save it as .claude/skills/security-scan/SKILL.md and the /security-scan command is ready.

YAML Frontmatter

Frontmatter adds control over the skill’s behavior:

---
description: Review a PR for code quality
allowed-tools: Read, Grep, Bash(git:*)
model: sonnet
argument-hint: [pr-number]
---

Field by field:

description - a short description shown in /help. If omitted, the first paragraph of the content is used instead.

when_to_use - extra context for automatic triggering: trigger phrases, example requests. Appended to the description in listings.

allowed-tools - grants permission for the listed tools without prompting. Bash(git:*) allows git commands without confirmation. Doesn’t restrict other tools - they’re still available but require approval.

disallowed-tools - completely removes tools from what’s available while the skill is active. Resets on the next message.

model - picks a model for the duration of the skill: haiku for quick tasks, sonnet for standard work, opus for complex analysis. A full model ID also works (claude-sonnet-5, claude-opus-5, claude-haiku-4-5). Defaults to inheriting from the session.

argument-hint - an argument hint shown during autocomplete.

arguments - named positional arguments for $name substitution. For example, arguments: [issue, branch] makes $issue and $branch available.

disable-model-invocation - if true, Claude won’t invoke the skill automatically; only the user can, manually, via /name.

user-invocable - if false, the skill is hidden from the / menu, but Claude can still call it itself. Useful for background instructions.

context: fork - runs the skill in an isolated subagent.

effort - effort level: low, medium, high, xhigh, max. Overrides the session’s effort level for the duration of the skill.

paths - glob patterns: the skill activates automatically only when working with matching files.

license - the skill’s license (name or link). Used when distributing publicly through plugins.

compatibility - environment requirements (OS, Claude Code version, subscription plan).

metadata - extra key-value pairs: owner, version, internal team tags.

Dynamic Arguments

Skills accept arguments via $ARGUMENTS (all arguments as one string) or positionally: $0, $1, $2 (0-indexed).

---
description: Fix an issue by number
argument-hint: [issue-number]
---

Fix issue #$ARGUMENTS following the project's standards.
Read the description, find the relevant code, propose a fix.

Usage: /fix-issue 123 - Claude gets the prompt with the number substituted in.

Positional arguments pass multiple parameters (0-indexed):

---
description: Deploy the application
argument-hint: [environment] [version]
---

Deploy the application to environment $0, version $1.
Check the configuration, run pre-deploy checks, execute the deployment.

Named arguments go through the arguments frontmatter field:

---
description: Deploy the application
arguments: [environment, version]
argument-hint: [environment] [version]
---

Deploy the application to environment $environment, version $version.

Dynamic Context: ! and @

Two mechanisms pull in context at runtime:

@path - includes a file’s contents in the prompt:

Check @tsconfig.json and @package.json for consistency.
Make sure the TypeScript versions match.

!command - runs a bash command and includes its output:

---
allowed-tools: Bash(git:*)
---

Files in the current PR: !`git diff --name-only main...HEAD`

Review each changed file.
Check: code quality, potential bugs, test coverage.

Combining both mechanisms gives context-aware skills:

---
description: Analyze recent changes
allowed-tools: Read Bash(git:*)
---

Last commit: !`git log -1 --format="%H %s"`
Changed files: !`git diff --name-only HEAD~1`
Current branch: !`git branch --show-current`

Analyze the changes in the context of the project.
Check whether they break existing architecture.

Example: A Full /review Skill

---
description: Comprehensive code review with a checklist
allowed-tools: Read Grep Glob Bash(git:*)
model: sonnet
argument-hint: [file-or-directory]
---

## Task

Review the code in $ARGUMENTS (or all changed files if no argument is given).

## Context

Changes: !`git diff --cached --name-only 2>/dev/null || git diff --name-only HEAD~1`
Branch: !`git branch --show-current`

## Checklist

### Pass 1: Correctness
- Logic errors
- Unhandled edge cases
- Null/undefined handling

### Pass 2: Architecture
- Consistency with existing project patterns
- Separation of concerns
- Module coupling and cohesion

### Pass 3: Security
- Input validation
- SQL injection, XSS
- Secret leaks

### Pass 4: Performance
- N+1 queries
- Unnecessary re-renders
- Suboptimal algorithms

## Output Format

For each finding, provide:
- File and line
- Severity: critical / warning / suggestion
- Description of the problem
- Suggested fix

Summary: overall PR verdict (approve / request changes) and key recommendations.

Agents: Autonomous Subagents

Whether a task needs a subagent at all, what launching one costs, and when it gets in the way are covered in a separate article on Claude Code subagents. This section covers the file format, the frontmatter fields, and ready-made examples.

Agents (subagents) are specialized AI helpers that perform complex, multi-step tasks in an isolated context. Unlike skills, agents:

• Run in a separate context - they don’t clutter the main session with intermediate results
• Run in parallel
• Have their own system prompts and tool restrictions
• Return only the result, not the full trace of work
• Can run in an isolated git worktree (isolation: worktree) - the agent gets a clean copy of the repository

Location

File Format

An agent is a markdown file with required frontmatter:

---
name: code-reviewer
description: Use this agent when...
model: inherit
color: blue
tools: ["Read", "Grep", "Glob"]
---

Agent's system prompt...

Frontmatter Fields

name (required) - a unique identifier of up to 256 characters, such as code-reviewer. It can’t contain : (reserved for plugin agents like my-plugin:reviewer) or start with -. The agent is identified by this field, not by the file name.

description (required) - the most important field. Determines when Claude launches the agent. It’s recommended to include:

1. Trigger conditions: “Use this agent when…”
2. <example> blocks with context, the user’s request, and the assistant’s reaction
3. <commentary> blocks explaining why the agent fits

model (optional) - the alias sonnet, opus, haiku, or fable, a full model ID (for example, claude-opus-5-5), or inherit (the main conversation’s model). The subagent’s model is chosen in this order:

1. The model parameter of a specific agent call
2. The model frontmatter field
3. The CLAUDE_CODE_SUBAGENT_MODEL environment variable
4. The main conversation’s model

With nothing set explicitly, the subagent runs on the main session’s model.

color (optional) - a UI color: red, blue, green, yellow, purple, orange, pink, cyan.

tools (optional) - available tools, as a comma-separated string (Read, Grep, Bash) or a YAML list. If omitted, the agent inherits every tool available to subagents. Follow the principle of least privilege: an analysis agent shouldn’t have Write.

disallowedTools (optional) - tools explicitly denied to the agent, in the same format as tools. An entry with a specifier such as Bash(git push *) still removes the whole tool.

isolation (optional) - worktree runs the agent in an isolated git worktree. The worktree is automatically removed if the agent made no changes.

maxTurns (optional) - maximum number of turns the agent can take. When it hits the limit, the result comes back marked as partial, and Claude can resume the agent.

memory (optional) - persistence across sessions: user, project, or local.

effort (optional) - effort level: low, medium, high, xhigh, max.

background (optional) - true keeps the agent in the background even when Claude is about to wait for its result. Subagents launched from the main conversation already start in the background by default.

skills (optional) - a list of skills injected into the agent’s context at launch. Gives the agent expertise without needing to discover skills during execution.

permissionMode (optional) - permission mode: default, acceptEdits, auto, dontAsk, bypassPermissions, or plan; manual works as an alias for default.

mcpServers (optional) - a list of MCP servers for the agent: server-name strings or inline {name: config} objects.

hooks (optional) - lifecycle hooks scoped to the agent. All events are supported, but PreToolUse, PostToolUse, and Stop are the most common.

initialPrompt (optional) - a first user turn submitted automatically when the agent runs as the session’s main agent (--agent or the agent setting).

omitClaudeMd (optional) - true starts the agent without the user, project, and local CLAUDE.md files; managed policy still loads. Useful for agents that get everything they need from the task. Requires Claude Code v2.1.271+.

autoCompactWindow (optional) - a smaller auto-compact window for the agent, from 100000 to 1000000 tokens. Requires v2.1.296+.

experimental.cacheTtl (optional) - the prompt cache lifetime for the agent’s requests: 5m or 1h. Requires v2.1.248+.

Note: for plugin subagents, the hooks, mcpServers, and permissionMode fields are ignored for security reasons; initialPrompt doesn’t apply to them either.

Example: Security Scanner Agent

---
name: security-scanner
description: |
  Use this agent for security review of code changes.
  Triggers on auth, payments, API endpoints, user data handling.

  <example>
  Context: User modified authentication flow
  user: "Review the auth changes I just made"
  assistant: "I'll use the security-scanner agent to check for vulnerabilities"
  <commentary>Auth changes require specialized security review</commentary>
  </example>

  <example>
  Context: New API endpoint added
  user: "Check if this endpoint is secure"
  assistant: "I'll use the security-scanner agent to verify input validation and authorization"
  <commentary>New endpoints need OWASP Top 10 verification</commentary>
  </example>
model: sonnet
color: red
tools: ["Read", "Grep", "Glob", "Bash"]
---

You are a security engineer with an attacker's mindset.
Focus on real-world exploitable vulnerabilities, not theoretical concerns.

## Review Process

1. **Identify attack surface**: endpoints, inputs, auth flows, data access
2. **Check OWASP Top 10**: injection, broken auth, XSS, IDOR, misconfigurations
3. **Verify authorization**: every endpoint checks permissions before data access
4. **Review input validation**: all user inputs validated and sanitized
5. **Check secrets**: no hardcoded API keys, tokens, passwords

## Output Format

For each vulnerability:
- **Location**: file:line
- **Severity**: Critical / High / Medium / Low
- **Category**: OWASP category
- **Description**: what's wrong
- **Exploit scenario**: how an attacker would use this
- **Fix**: specific code change

Summary: total vulnerabilities by severity, overall risk assessment.

Example: Test Writer Agent

---
name: test-writer
description: |
  Use this agent to generate comprehensive tests for code.
  Triggers on: "write tests", "add tests", "test coverage", new features without tests.

  <example>
  Context: User implemented a new utility function
  user: "Write tests for the parseConfig module"
  assistant: "I'll use the test-writer agent to generate comprehensive tests"
  <commentary>New code without tests needs systematic test generation</commentary>
  </example>

  <example>
  Context: User asks about test coverage
  user: "This module has no tests, fix it"
  assistant: "I'll use the test-writer agent to analyze the module and create tests"
  <commentary>Missing tests require understanding module contracts</commentary>
  </example>
model: inherit
color: green
tools: ["Read", "Write", "Grep", "Glob", "Bash"]
---

You are a testing specialist. Write tests that verify behavior, not implementation.

## Process

1. Read the source code and understand its public API
2. Identify test categories: happy path, edge cases, error handling, integration
3. Check existing test patterns in the project (framework, style, conventions)
4. Generate tests following project conventions
5. Run tests to verify they pass

## Test Design Principles

- **One assertion per test** where practical
- **Descriptive test names**: "should return empty array when input is null"
- **AAA pattern**: Arrange, Act, Assert
- **No implementation coupling**: test behavior through public API
- **Cover edge cases**: null, undefined, empty, boundary values, concurrent access
- **Mock only external dependencies**: database, network, file system

## Output

- Test file(s) following project naming convention
- Summary of coverage: what's tested, what's intentionally skipped and why

Example: Code Reviewer Agent

---
name: code-reviewer
description: |
  Use this agent for detailed code review with actionable feedback.
  Triggers on: "review this", "check my code", PR review requests.

  <example>
  Context: User completed a feature implementation
  user: "Review the changes in src/api/"
  assistant: "I'll use the code-reviewer agent for a detailed multi-pass review"
  <commentary>Feature review needs systematic multi-pass analysis</commentary>
  </example>
model: sonnet
color: cyan
tools: ["Read", "Grep", "Glob"]
---

You are a senior engineer conducting code review.
Prioritize: Correctness > Security > Performance > Maintainability.

## Multi-Pass Review

### Pass 1: Correctness (mandatory)
- Logic errors, off-by-one, null handling
- All code paths handled
- Error propagation correct

### Pass 2: Architecture
- Fits existing project patterns
- Single responsibility maintained
- No unnecessary coupling

### Pass 3: Performance
- No N+1 queries
- Efficient algorithms for data size
- No memory leaks or unnecessary allocations

### Pass 4: Maintainability
- Code is self-documenting
- No magic numbers or strings
- Tests present and meaningful

## Output Format

**Verdict**: APPROVE / REQUEST CHANGES / NEEDS DISCUSSION

For each finding:
- 📍 Location: `file:line`
- 🔴/🟡/🟢 Severity
- Description and suggested fix

**Summary**: key strengths and areas for improvement.

Isolation and Context

Agents run in an isolated context:

• The main agent doesn’t see the subagent’s intermediate steps - only the final result
• The subagent has no access to the main chat’s history
• Multiple subagents can run in parallel without conflicts

The practical value is in context management: a subagent reads dozens of files and returns only a 20-line summary, keeping the main session clean.

Automatic and Explicit Invocation

Claude Code decides when to launch an agent based on the description. The more precise the examples in <example> blocks, the more accurate the triggering.

Explicit invocation: “Use the security-scanner agent to check this file” - Claude will find the agent by name.

Hooks: Event-Driven Automation

Hooks are handlers that Claude Code runs automatically at fixed points in its loop: before and after a tool call, when a prompt is submitted, at session start and stop, and before compaction. A handler can be a bash command (command), an HTTP endpoint (http), an MCP tool (mcp_tool), an LLM prompt (prompt), or a subagent (agent, marked experimental). Unlike an instruction in CLAUDE.md, a hook runs every time and doesn’t depend on the model’s judgment.

Core Events

There are more than 30 events, and the list grows with almost every release, so check the Hooks reference for the full set. For most tasks, ten of them are enough:

Configuration

Hooks are defined in settings.json (user, project, or local scope), in plugins, and in the frontmatter of a skill or subagent. The structure has three levels: event, a group with a matcher, and a list of handlers.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh",
            "timeout": 5,
            "onFailure": "block"
          }
        ]
      }
    ]
  }
}

On tool events, matcher filters by tool name: "Write|Edit" is an exact list, "*" or an empty value matches everything, and a string with other characters ("mcp__.*") is read as a regex. timeout is in seconds and defaults to 600 for command, http, and mcp_tool, so set it explicitly on frequent events. Guard hooks need onFailure: "block": without it, a timed-out or crashed hook doesn’t block the call. All matching handlers for an event run in parallel.

Exit Codes

• 0 - success. Stdout is parsed as a JSON response; plain text reaches Claude’s context only on UserPromptSubmit, UserPromptExpansion, SessionStart, and PostModelSwitch, and goes to the debug log on other events.
• 2 - a block on events that support it (PreToolUse, UserPromptSubmit, Stop, and others). Write the reason to stderr as plain text, and Claude sees it. JSON printed to stderr doesn’t count as a decision.
• Any other code, including 1, is a non-blocking error: Claude Code shows hook error and the action goes ahead. A guard hook that exits with 1 blocks nothing.

Example: Protecting Critical Files

The protect-files.sh script for the configuration above blocks edits to secrets, .git/, and the lock file:

#!/bin/bash
P=$(jq -r '.tool_input.file_path // empty')
[ -z "$P" ] && exit 0
case "$P" in
  *.env|*/.env.*|*/.git/*|*/package-lock.json|*.pem|*.key)
    echo "Blocked: $P is on the protected paths list" >&2
    exit 2 ;;
esac
exit 0

The hook only sees Edit and Write: it won’t catch echo X > .env run through Bash, which needs a deny rule in permissions.

Hook edits in settings files are usually picked up without a restart, because Claude Code watches those files. If a change doesn’t show up, restart the session. The /hooks command lists the loaded hooks.

More detail: exit codes per event, JSON decisions, guard recipes for Bash, a Stop gate that checks stop_hook_active, formatting after edits, notifications, debugging, and securing the hooks themselves are covered in Claude Code Hooks: Recipes, Exit Codes, and Safety.

Memory: Persistence Across Sessions

Memory is the mechanism for persisting knowledge across sessions. Claude remembers decisions, patterns, and project context, and doesn’t ask the same thing twice.

Types of Memory

CLAUDE.md files - instructions Claude loads at startup:

Auto-memory - Claude automatically saves feedback and decisions.

Location: ~/.claude/projects/<project>/memory/ (the path is derived from the project’s git repository)

When Claude receives a correction from the user, it saves it to memory files. The MEMORY.md file serves as an index. At session start, the first 200 lines or first 25KB of this file are loaded.

MEMORY.md Structure

# Memory Index

- [feedback_article_tone.md](feedback_article_tone.md) — Article tone: professional, technical
- [feedback_publish_date.md](feedback_publish_date.md) — Publish date = actual publication day
- [reference_telegram_channel.md](reference_telegram_channel.md) — Telegram channel: @futcraft
- [project_reddit_strategy.md](project_reddit_strategy.md) — Reddit Growth Strategy: 6-month roadmap

Types of Memory Files

File names follow a naming convention by type:

feedback_ - corrections from the user. “Don’t add emoji to commits,” “Use vitest, not jest.” The most common type.

reference_ - reference information. Channel IDs, API URLs, key configs. Things Claude won’t find in the code.

project_ - project decisions. Architectural choices, strategies, roadmaps. Context Claude factors into its work.

user_ - personal preferences. Code style, preferred tools, output formats.

Practice: Working With Memory Effectively

Memory works automatically, but you can manage the process explicitly:

1. Correction - correct Claude: “No, use pnpm, not npm.” It’ll save this as feedback and apply it in the next session.

2. Explicit saving - “Remember: in this project, all API responses are wrapped in { data, error, meta }.” Claude will create a memory file.

3. Review - open ~/.claude/projects/*/memory/MEMORY.md, delete stale entries.

4. Migration - if a rule is global, move it to ~/.claude/CLAUDE.md.

CLAUDE.md: Advanced Configuration

CLAUDE.md is a markdown file with persistent instructions that Claude Code loads into context at the start of every session: build and test commands, team conventions, non-obvious project constraints. It is context for the model, not enforced configuration. If an action must be blocked with no exceptions, move it into a hook.

Key facts:

• Four levels. In load order, from broadest to narrowest: the organization’s managed policy, the user-level ~/.claude/CLAUDE.md, the project’s ./CLAUDE.md or ./.claude/CLAUDE.md, and the personal ./CLAUDE.local.md (add it to .gitignore).
• Files are concatenated, not overridden. The order runs from the filesystem root to the working directory, so the model reads instructions closer to the launch directory last. If two files contradict each other, Claude may pick either one: resolve contradictions in the files themselves.
• Rules for part of the codebase go into .claude/rules/ with a paths field in the frontmatter: such rules load when Claude works with matching files. An @path/to/file import pulls in another file but does not save context: the imported file loads together with its parent.
• Short and specific. The docs recommend keeping each CLAUDE.md under 200 lines and writing verifiable instructions: “Use pnpm, not npm” instead of “Use the correct package manager.” CRITICAL tags and all caps are unnecessary: current models follow plain wording, and emphasis can make them apply a rule more broadly than intended.

The CLAUDE.md guide covers how nested CLAUDE.md files load, imports, .claude/rules/, a file template, and an audit checklist.

Combinations: Orchestrating the Components

The real power is in combining all the components. Skills launch agents, hooks pass context through env variables, memory accumulates rules across sessions, and Dynamic Workflows scales this to hundreds of parallel tasks.

A Skill Calls an Agent

A skill can include an instruction to launch a specific agent:

---
description: Full PR review cycle
argument-hint: [pr-number]
allowed-tools: Bash(gh:*), Read
---

PR #$ARGUMENTS:
Info: !`gh pr view $ARGUMENTS --json title,body,files`

Phase 1: Run the code-reviewer agent to analyze the changes.
Phase 2: Run the security-scanner agent to check for security issues.
Phase 3: Based on both agents' results, form a final verdict.

Claude launches both agents (potentially in parallel), collects their results, and forms an overall conclusion.

A Hook Informs Claude Through Context

A SessionStart hook loads information that a skill or agent then uses:

# load-context.sh
#!/bin/bash

# Check for open PRs
OPEN_PRS=$(gh pr list --json number,title --limit 5 2>/dev/null || echo "[]")
echo "export OPEN_PRS='$OPEN_PRS'" >> "$CLAUDE_ENV_FILE"

# Last failed CI run
FAILED_RUN=$(gh run list --status failure --limit 1 --json databaseId,name 2>/dev/null || echo "[]")
echo "export FAILED_CI='$FAILED_RUN'" >> "$CLAUDE_ENV_FILE"

Now a skill uses this context:

---
description: Morning project status
---

Show the morning status:
1. Current branch and uncommitted changes
2. Open PRs (from env OPEN_PRS)
3. Last failed CI run (from env FAILED_CI)
4. Priority tasks for today

Short context doesn’t need variables: plain text that a SessionStart hook prints to stdout goes straight into Claude’s context. That option and re-injecting context after compaction are covered in the Claude Code hooks article.

Memory Informs an Agent

When Claude gets a correction (“Don’t use Lodash in this project, everything’s covered by the standard library”), it’s saved to memory. In the next session, the code-reviewer agent factors this rule in without being reminded - CLAUDE.md and memory load at startup.

The chain: the user corrects Claude → memory saves the feedback → CLAUDE.md loads it at startup → the agent applies it during analysis.

Real Workflows

Workflow 1: Onboarding a New Developer

A new developer clones the project. CLAUDE.md describes the architecture, conventions, and commands. Skills handle the routine:

• /setup - installs dependencies, configures the environment, checks prerequisites
• /architecture - explains the project structure, key modules, data flows
• /find-examples - finds usage examples of a pattern in the codebase

Agents help with onboarding:

• The code-reviewer agent reviews the first PRs
• The test-writer agent generates tests following project conventions

Hooks enforce quality:

• A PreToolUse hook checks that new code doesn’t break conventions
• A Stop hook checks that tests were written and pass

Workflow 2: Automated PR Review

---
description: Automated PR review
argument-hint: [pr-number]
allowed-tools: Bash(gh:*), Read, Grep, Glob
model: sonnet
---

## PR Review Pipeline

PR: !`gh pr view $ARGUMENTS --json title,body,additions,deletions,changedFiles`
Files: !`gh pr diff $ARGUMENTS --name-only`

### Step 1: Scope Assessment
Assess the scope of the changes. If > 500 lines, warn about large-PR risks.

### Step 2: Code Review
Run the code-reviewer agent on the changed files.

### Step 3: Security Check
If the changes touch auth, API endpoints, or data handling —
run the security-scanner agent.

### Step 4: Test Coverage
Check for tests covering the new functionality.
If there are none, run the test-writer agent.

### Step 5: Final Verdict
Combine the results of all checks.
Format: APPROVE / REQUEST CHANGES with concrete action items.

Workflow 3: Release Management

---
description: Prepare a release
argument-hint: [version]
allowed-tools: Bash(git:*, npm:*, gh:*), Read, Write, Edit
---

## Release Checklist for version $ARGUMENTS

### Pre-release
1. Check: !`git status --porcelain`
2. Current branch: !`git branch --show-current`
3. All tests pass: !`npm test 2>&1 | tail -5`

### Changelog
4. Collect commits since the last release: !`git log $(git describe --tags --abbrev=0)..HEAD --oneline`
5. Generate a changelog in Keep a Changelog format

### Version Bump
6. Update the version in package.json to $ARGUMENTS
7. Update CHANGELOG.md

### Release
8. Create a commit: "chore: release v$ARGUMENTS"
9. Create a tag: v$ARGUMENTS
10. Show the push commands (but don't run them without confirmation)

Workflow 4: Debugging Methodology

---
description: Systematic debugging of an issue
argument-hint: [description]
allowed-tools: Read, Grep, Glob, Bash(*)
model: opus
---

## Systematic Debugging: $ARGUMENTS

### Phase 1: Reproduce
Determine the exact steps to reproduce the problem.
Find the minimal test case.

### Phase 2: Isolate
Use binary search across commits if the issue is a regression.
Determine which module, function, line causes the problem.

### Phase 3: Hypothesize
Formulate 3 hypotheses about the cause.
For each, describe how to verify it and what to look for.

### Phase 4: Verify
Check each hypothesis, starting with the most likely.
Show evidence (logs, values, stack traces).

### Phase 5: Fix
Propose a minimal fix.
Explain why it addresses the root cause, not just the symptom.
Suggest a test that will prevent a regression.

Dynamic Workflows: Orchestrating Hundreds of Subagents

Dynamic Workflows is 2026’s headline update. These are JavaScript scripts that Claude writes itself and runs in the background, coordinating dozens or hundreds of parallel subagents within a single session.

How It Works

You describe the task: “Run a security audit of the entire codebase” or “Migrate from REST to GraphQL.” Claude:

1. Builds a plan - decomposes the work into parallel subtasks
2. Generates a JavaScript orchestration script
3. Launches subagents - up to 16 in parallel, no more than 1,000 total per run
4. Validates results before the final answer

Your main session stays responsive: the workflow runs in the background, progress is visible in the UI.

Typical Scenarios

• Codebase audits (security, quality, documentation)
• Large migrations (framework version, API changes)
• Cross-project research spanning multiple sources

Saving and Reusing

Scripts are saved through the workflow menu (press s). Two storage paths:

• ~/.claude/workflows/ - personal
• Inside a skill’s folder, referenced in SKILL.md - for distribution via plugins

---
description: Security audit workflow
---

Run the dynamic workflow from @security-audit.js to audit the entire codebase.
Use the script as a template and adapt it to the current stack.

Availability

Dynamic Workflows are on by default for Max, Team, Enterprise plans and when working through the API. Pro plan users can enable it in /config. Activate via /workflows or the ultracode setting.

Agent Teams: Parallel Team Work

Agent Teams is an experimental feature, disabled by default. Enable it via the CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS variable in settings.json. Has known limitations around session resumption and task management.

Agent Teams extends the subagent model further: multiple Claude instances work in parallel on different subtasks, coordinating through a shared task list.

Unlike manually running several sessions, Agent Teams provides built-in coordination:

• Agents claim tasks without conflicts - through file locking when claiming tasks
• Team members communicate directly via mailbox, not just through a lead agent
• A lead agent coordinates the task list and synthesizes results

The TeammateIdle hook event lets you react when a team member finishes a task - for example, to launch the next processing stage.

Plugins: Distributing Skills and Agents

As the Claude Code ecosystem grew in 2026, a distinction emerged between skills and plugins:

• Skill - a single SKILL.md file with instructions
• Plugin - a bundle: several skills + MCP servers + agents + configs, packaged as one installable unit

Plugins are installed via the /plugin command inside Claude Code:

/plugin marketplace add <user-or-org/repo-name>

There’s no centralized official marketplace - the ecosystem is decentralized. Plugins are published in git repositories; a marketplace is connected via a URL or a GitHub repo containing a .claude-plugin/marketplace.json file. Anthropic’s official catalog is available via /plugin marketplace add anthropics/claude-code.

To publish your own plugin, use the license, compatibility, and metadata fields in SKILL.md.

Headless Mode and Automation

Claude Code supports non-interactive execution via the -p flag:

# Basic headless run
claude -p "Run a security audit of src/" --output-format json

# With a specific model
claude -p "Update dependencies to the latest versions" \
  --model claude-opus-5 \
  --allowedTools "Read,Write,Bash"

# Continuing a previous session
claude --continue -p "Now write tests for the fixed code"

# Structured output
claude -p "Analyze the API and return a JSON report" \
  --output-format json \
  --json-schema report-schema.json

As of February 2026, a Remote Control mode is available: launch it via /remote-control - Claude shows a QR code to connect from your phone through the Claude app. This gives full session control, including file management and progress monitoring.

The Redesigned Desktop App

In April 2026, Anthropic shipped a major redesign of Claude Code Desktop:

Multi-session support - a sidebar manages all active and recent sessions. Run work across several repositories at once and switch between them as results come in.

Integrated tools - a built-in terminal, file editor, a faster diff viewer for large changesets, HTML/PDF preview, and local server launching.

Custom layout - every panel (terminal, preview, diff, chat) is draggable, and the grid adjusts to your working style.

CLI parity - plugin support and SSH for remote machines (macOS and Linux).

The app is available on all plans: Pro, Max, Team, Enterprise, and via API.

Ready-Made Templates

5 Skills to Copy

1. /adr - Architecture Decision Record

---
description: Create an Architecture Decision Record
argument-hint: [title]
allowed-tools: Read, Write, Glob
---

Create an ADR (Architecture Decision Record) on the topic: $ARGUMENTS

Find existing ADRs: !`ls docs/decisions/ 2>/dev/null || echo "No ADRs"`

ADR format:

# ADR-[NEXT_NUMBER]: $ARGUMENTS

## Status
Proposed

## Context
[What problem is being solved]

## Decision
[What was decided]

## Consequences
### Positive
- [Pros]

### Negative
- [Cons]

### Neutral
- [Neutral consequences]

## Alternatives Considered
[What alternatives were considered and why they were rejected]

Save to docs/decisions/adr-[NUMBER]-[slug].md

2. /test - Run and Analyze Tests

---
description: Run tests and analyze the result
argument-hint: [test-path]
allowed-tools: Bash(npm:*, npx:*, pnpm:*), Read
model: sonnet
---

Run tests: !`npm test -- $ARGUMENTS 2>&1 | tail -50`

If tests passed: a short report, coverage.
If tests failed:
1. Determine the root cause of each failure
2. Propose a specific fix
3. State whether it's a regression or a new bug

3. /deploy - Pre-Deploy Checks

---
description: Pre-deploy checks and deployment
argument-hint: [environment]
allowed-tools: Bash(*), Read
---

## Pre-Deploy Checklist for $ARGUMENTS

1. Git status: !`git status --porcelain`
2. Current branch: !`git branch --show-current`
3. Unpushed commits: !`git log @{u}..HEAD --oneline 2>/dev/null || echo "No upstream"`
4. Tests: !`npm test 2>&1 | tail -10`
5. Build: !`npm run build 2>&1 | tail -10`

If all checks pass, show the deploy command for $ARGUMENTS.
If not, show what needs fixing.

4. /refactor - Safe Refactoring

---
description: Refactor while preserving behavior
argument-hint: [file-or-module]
allowed-tools: Read, Write, Edit, Grep, Glob, Bash(npm:*)
model: opus
---

## Refactoring: $ARGUMENTS

### Phase 1: Understand
Read the code. Determine: what it does, how it's used, which tests cover it.

### Phase 2: Identify
Find code smells:
- Duplication
- Functions that are too long (> 50 lines)
- Deep nesting (> 3 levels)
- Single Responsibility violations

### Phase 3: Plan
Propose a refactoring plan. Each step should:
- Preserve behavior (tests keep passing)
- Be atomic (one commit)

### Phase 4: Execute
Perform the refactoring step by step.
After each step: run the tests.

5. /api-docs - Generate API Documentation

---
description: Generate documentation for an API endpoint
argument-hint: [file-path]
allowed-tools: Read, Grep, Glob
---

Read @$1 and generate API documentation.

Format for each endpoint:

### [METHOD] /path

**Description:** Short description

**Authentication:** Required/Optional

**Request:**
- Headers: ...
- Body: schema with types

**Response:**
- 200: Success schema
- 400: Validation error
- 401: Unauthorized
- 500: Server error

**Example:**
```bash
curl -X POST /api/endpoint \
  -H "Authorization: Bearer token" \
  -d '{"key": "value"}'

Use types from the code, don’t invent them.

### 3 Agents to Copy

#### 1. Database Migration Reviewer

```markdown
---
name: migration-reviewer
description: |
  Use this agent to review database migrations for safety and correctness.
  Triggers on: migration files, schema changes, SQL modifications.

  <example>
  Context: User created a new migration
  user: "Review this migration before I apply it"
  assistant: "I'll use the migration-reviewer agent to check for data safety issues"
  <commentary>Migrations need careful review for data loss, locking, and rollback</commentary>
  </example>
model: sonnet
color: yellow
tools: ["Read", "Grep", "Glob"]
---

You are a database migration specialist. Review migrations for safety, correctness, and performance.

## Checklist

1. **Data Safety**
   - Can this migration cause data loss?
   - Is there a rollback path?
   - Are default values set for new NOT NULL columns?

2. **Locking**
   - Will this lock tables for a long time?
   - Use CONCURRENTLY for indexes on large tables?
   - Avoid ALTER TABLE on hot tables during peak hours

3. **Performance**
   - Will this migration be fast enough for production data volume?
   - Are new indexes necessary and efficient?
   - No missing indexes for new foreign keys

4. **Compatibility**
   - Is this backward-compatible with current application code?
   - Can old and new code run simultaneously during deploy?

## Output
- SAFE / NEEDS ATTENTION / DANGEROUS
- Specific issues with fixes
- Estimated execution time for production data

2. Dependency Auditor

---
name: dependency-auditor
description: |
  Use this agent to audit project dependencies for security and health.
  Triggers on: "audit dependencies", "check packages", dependency updates.

  <example>
  Context: User wants to check dependency health
  user: "Audit our dependencies"
  assistant: "I'll use the dependency-auditor agent to check for vulnerabilities and outdated packages"
  <commentary>Regular dependency audits catch vulnerabilities early</commentary>
  </example>
model: sonnet
color: yellow
tools: ["Read", "Bash", "Grep"]
---

You are a dependency security specialist. Audit project dependencies comprehensively.

## Process

1. Run security audit: `npm audit` / `pip audit` / `cargo audit`
2. Check for outdated packages with major version gaps
3. Identify packages with known CVEs
4. Check license compatibility
5. Identify abandoned packages (no updates > 2 years)

## Output

### Critical (act now)
- Packages with known exploited vulnerabilities

### High (act this sprint)
- Packages with high-severity CVEs
- Packages 2+ major versions behind

### Medium (plan for)
- Outdated packages with breaking changes ahead
- Packages approaching end-of-life

### Info
- License summary
- Dependency tree depth
- Total package count

3. Performance Profiler

---
name: performance-profiler
description: |
  Use this agent to analyze code for performance issues.
  Triggers on: "performance", "slow", "optimize", "profiling".

  <example>
  Context: User reports slow API endpoint
  user: "This endpoint takes 3 seconds, find out why"
  assistant: "I'll use the performance-profiler agent to analyze bottlenecks"
  <commentary>Performance issues need systematic profiling, not guessing</commentary>
  </example>
model: opus
color: purple
tools: ["Read", "Grep", "Glob", "Bash"]
---

You are a performance engineer. Find and fix bottlenecks systematically.

## Analysis Process

1. **Identify hot path**: trace the execution path of the slow operation
2. **Database queries**: find N+1, missing indexes, full table scans
3. **Algorithm complexity**: check for O(n^2) or worse in loops
4. **I/O operations**: unnecessary disk reads, synchronous network calls
5. **Memory**: large allocations, data structure inefficiency
6. **Caching**: missed caching opportunities, cache invalidation issues

## Report Format

### Bottleneck #N
- **Location**: file:line
- **Impact**: estimated time/memory cost
- **Root cause**: why it's slow
- **Fix**: specific code change
- **Expected improvement**: quantified estimate

### Summary
- Top 3 bottlenecks ranked by impact
- Quick wins vs. architectural changes
- Recommended order of fixes

Hooks to Copy

Ready-made hook recipes with correct exit codes (file protection, a Bash guard, formatting after edits, a Stop gate, an activity log, notifications) are collected in Claude Code Hooks: Recipes, Exit Codes, and Safety.

File Organization

Recommended .claude/ structure for a medium-complexity project:

.claude/
├── settings.json           # Permissions, hooks, env
├── settings.local.json     # Personal overrides (gitignored)
├── CLAUDE.md               # Or CLAUDE.md at the project root
├── skills/                 # Project skills (new format)
│   ├── review/
│   │   └── SKILL.md
│   ├── test/
│   │   └── SKILL.md
│   └── deploy/
│       └── SKILL.md
├── commands/               # Legacy skills (still work)
│   └── ...
├── agents/                 # Project agents
│   ├── code-reviewer.md
│   ├── test-writer.md
│   └── security-scanner.md
└── rules/                  # File-scoped rules
    ├── api.md
    ├── database.md
    └── tests.md

For personal (user-scope) use - a similar structure in ~/.claude/:

~/.claude/
├── settings.json
├── CLAUDE.md
├── skills/                 # Global skills
│   ├── debug/
│   │   └── SKILL.md
│   ├── git-workflow/
│   │   └── SKILL.md
│   └── morning-standup/
│       └── SKILL.md
├── agents/                 # Global agents
│   ├── senior-reviewer.md
│   └── performance-profiler.md
└── hooks/                  # Hook scripts
    ├── protect-files.sh
    └── auto-format.sh

Summary

Skills, Agents, Hooks, Memory, and Dynamic Workflows are the five core mechanisms for extending Claude Code, each at its own level:

• Skills - slash commands for repeatable tasks with a predictable format. Invoked manually or automatically. Stored in .claude/skills/<name>/SKILL.md.
• Agents - isolated subprocesses for complex, multi-step tasks. Return only the result. Support skills, permissionMode, mcpServers, hooks, and initialPrompt.
• Hooks - automatic reactions to events (30+ event types). For enforcing rules and integrating with external tools. Handlers: command, http, mcp_tool, prompt, agent.
• Memory - persistence across sessions. Claude learns from corrections and doesn’t repeat mistakes.
• CLAUDE.md - declarative instructions defining Claude’s behavior in the project.
• Dynamic Workflows - JavaScript orchestration of hundreds of parallel subagents for large-scale tasks. Written by Claude, runs in the background. Available on all paid plans (on Pro, enable it in /config).
• Agent Teams - multiple Claude instances working in parallel, coordinated through a shared task list. Experimental, requires enabling via CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS.
• Plugins - bundled packages (skills + MCP + agents) distributed through a marketplace.