CLAUDE CODE CAPABILITIES LEARNING GUIDE

Deep Learning Claude Code Capabilities

A comprehensive learning guide to master Claude Code’s advanced features through hands-on projects.

Core Concept Analysis

Claude Code is an agentic coding assistant with four key capability areas:

Capability Area	Core Concepts
Agent Skills	Progressive loading, SKILL.md structure, filesystem-based resources, metadata/instructions/code hierarchy
Subagents	Task delegation, context isolation, tool permissions, specialized expertise
Output Styles	System prompt modification, behavior customization, domain-specific modes
Headless Mode	Non-interactive execution, CI/CD integration, JSON streaming, session management

1. Agent Skills

What It Is

Skills are modular capabilities packaged as filesystem directories containing instructions, code, and resources. They follow a progressive disclosure pattern:

Level 1: Metadata (always loaded)     → ~100 tokens
Level 2: Instructions (when triggered) → <5k tokens
Level 3: Resources (as needed)        → Unlimited

Key Architecture

pdf-skill/
├── SKILL.md          # Main instructions (YAML frontmatter + markdown)
├── FORMS.md          # Additional guidance
├── REFERENCE.md      # API docs
└── scripts/
    └── fill_form.py  # Executable scripts (code never enters context!)

Configuration File (SKILL.md)

---
name: your-skill-name    # Max 64 chars, lowercase + hyphens only
description: When to use this skill and what it does  # Max 1024 chars
---

# Your Skill Instructions
[Step-by-step guidance Claude follows]

Locations

Type	Location	Scope
Project	`.claude/skills/`	Current project
User	`~/.claude/skills/`	All projects

How Skills Work

Startup: System prompt includes skill metadata (name + description)
User request: Claude matches request to skill descriptions
Claude invokes: bash: read skill/SKILL.md → Instructions loaded into context
Claude determines: What additional files are needed
Claude executes: Uses instructions and runs scripts as needed

Security Considerations

Only use Skills from trusted sources (yourself or Anthropic)
Audit all files in third-party Skills thoroughly
External URL fetching in Skills poses particular risk
Treat Skills like installing software

2. Subagents

What They Are

Specialized AI assistants that Claude delegates tasks to. Each operates in its own context window with specific tools and prompts.

Built-in Subagents

Subagent	Model	Tools	Purpose
General-Purpose	Sonnet	All	Complex multi-step tasks
Plan	Sonnet	Read, Glob, Grep, Bash	Research during planning
Explore	Haiku	Glob, Grep, Read, Bash (read-only)	Fast codebase searching

Key Benefits

Context Preservation: Each subagent operates in its own context
Specialized Expertise: Fine-tuned for specific domains
Reusability: Can be used across different projects
Flexible Permissions: Different tool access levels for each type

Configuration File

---
name: code-reviewer
description: Reviews code for quality and security. Use proactively after code changes.
tools: Read, Grep, Glob, Bash    # Optional - inherits all if omitted
model: sonnet                     # sonnet, opus, haiku, or 'inherit'
permissionMode: default           # default, acceptEdits, bypassPermissions
skills: skill1, skill2            # Auto-load these skills
---

You are a senior code reviewer...
[Full system prompt here]

Configuration Fields

Field	Required	Description
`name`	Yes	Unique identifier (lowercase letters and hyphens)
`description`	Yes	Natural language description of purpose
`tools`	No	Comma-separated list; inherits all if omitted
`model`	No	Model alias (`sonnet`, `opus`, `haiku`) or `'inherit'`
`permissionMode`	No	`default`, `acceptEdits`, `bypassPermissions`, `plan`, `ignore`
`skills`	No	Comma-separated list of skills to auto-load

Locations

Type	Location	Priority
Project	`.claude/agents/`	Higher
User	`~/.claude/agents/`	Lower

Usage

# Interactive management
/agents

# In conversation
> Use the code-reviewer subagent to check my changes
> Have the debugger subagent investigate this error

# Chaining subagents
> First use code-analyzer to find issues, then use optimizer to fix them

# Resuming subagents
> Resume agent abc123 and analyze the authorization logic

Example: Code Reviewer Subagent

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:
- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific examples of how to fix issues.

Example: Debugger Subagent

---
name: debugger
description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
tools: Read, Edit, Bash, Grep, Glob
---

You are an expert debugger specializing in root cause analysis.

When invoked:
1. Capture error message and stack trace
2. Identify reproduction steps
3. Isolate the failure location
4. Implement minimal fix
5. Verify solution works

Debugging process:
- Analyze error messages and logs
- Check recent code changes
- Form and test hypotheses
- Add strategic debug logging
- Inspect variable states

For each issue, provide:
- Root cause explanation
- Evidence supporting the diagnosis
- Specific code fix
- Testing approach
- Prevention recommendations

Focus on fixing the underlying issue, not the symptoms.

3. Output Styles

What They Are

Output styles modify Claude Code’s system prompt to adapt behavior for different use cases.

Built-in Styles

Style	Behavior
Default	Efficient software engineering
Explanatory	Educational insights between tasks
Learning	Collaborative with `TODO(human)` markers

How Output Styles Work

Output styles directly modify Claude Code’s system prompt by:

Excluding instructions for efficient output (like responding concisely)
Excluding coding instructions in custom styles (unless keep-coding-instructions: true)
Adding custom instructions to the end of the system prompt
Triggering reminders for Claude to adhere to output style instructions

Custom Output Style File

---
name: Learning Project Advisor
description: Recommends buildable projects for learning
keep-coding-instructions: false   # Remove default coding prompts
---

# Custom Instructions

You are a Learning Project Advisor...
[Your full custom system prompt]

Frontmatter Properties

Property	Purpose	Default
`name`	Display name for the style	Inherits from file name
`description`	UI description shown in `/output-style` menu	None
`keep-coding-instructions`	Retain Claude Code’s coding system prompt sections	false

Locations

User: ~/.claude/output-styles/
Project: .claude/output-styles/

Usage

/output-style              # Interactive menu
/output-style explanatory  # Direct selection

Settings are saved at the project level in .claude/settings.local.json.

Feature	Behavior
Output Styles	Replace software engineering sections of default system prompt
CLAUDE.md	Adds contents as a user message after the default system prompt
`--append-system-prompt`	Appends content to system prompt without removing defaults
Agents/Subagents	Handle specific tasks with additional settings (model, tools, context)
Custom Slash Commands	“Stored prompts” vs Output Styles as “stored system prompts”

4. Headless Mode

What It Is

Non-interactive mode for CI/CD pipelines and automation scripts.

Basic Usage

claude -p "Stage my changes and write commits" \
  --allowedTools "Bash,Read" \
  --permission-mode acceptEdits

Key Flags

Flag	Description	Example
`--print`, `-p`	Run in non-interactive mode	`claude -p "query"`
`--output-format`	Specify output format (`text`, `json`, `stream-json`)	`claude -p --output-format json`
`--resume`, `-r`	Resume a conversation by session ID	`claude --resume abc123`
`--continue`, `-c`	Continue the most recent conversation	`claude --continue`
`--verbose`	Enable verbose logging	`claude --verbose`
`--append-system-prompt`	Append to system prompt (only with `--print`)	`claude --append-system-prompt "Custom instruction"`
`--allowedTools`	Tools that execute without prompting	`claude --allowedTools mcp__slack mcp__filesystem`
`--disallowedTools`	Tools removed from model’s context	`claude --disallowedTools mcp__splunk`
`--mcp-config`	Load MCP servers from JSON file	`claude --mcp-config servers.json`

Output Formats

Text Output (Default)

claude -p "Explain file src/components/Header.tsx"
# Output: This is a React component showing...

JSON Output

claude -p "How does the data layer work?" --output-format json

Response structure:

{
  "type": "result",
  "subtype": "success",
  "total_cost_usd": 0.003,
  "is_error": false,
  "duration_ms": 1234,
  "duration_api_ms": 800,
  "num_turns": 6,
  "result": "The response text here...",
  "session_id": "abc123"
}

Streaming JSON Output

claude -p "Build an application" --output-format stream-json

Each message is emitted as a separate JSON object, starting with an init system message, followed by user and assistant messages, then a final result system message with stats.

Multi-turn Conversations

# Continue the most recent conversation
claude --continue "Now refactor this for better performance"

# Resume a specific conversation by session ID
claude --resume 550e8400-e29b-41d4-a716-446655440000 "Update the tests"

# Resume in non-interactive mode
claude --resume 550e8400-e29b-41d4-a716-446655440000 "Fix all linting issues" --no-interactive

Automation Use Cases

SRE Incident Response Bot

#!/bin/bash

investigate_incident() {
    local incident_description="$1"
    local severity="${2:-medium}"

    claude -p "Incident: $incident_description (Severity: $severity)" \
      --append-system-prompt "You are an SRE expert. Diagnose the issue, assess impact, and provide immediate action items." \
      --output-format json \
      --allowedTools "Bash,Read,WebSearch,mcp__datadog" \
      --mcp-config monitoring-tools.json
}

investigate_incident "Payment API returning 500 errors" "high"

Automated Security Review

# Security audit agent for pull requests
audit_pr() {
    local pr_number="$1"

    gh pr diff "$pr_number" | claude -p \
      --append-system-prompt "You are a security engineer. Review this PR for vulnerabilities, insecure patterns, and compliance issues." \
      --output-format json \
      --allowedTools "Read,Grep,WebSearch"
}

# Usage and save to file
audit_pr 123 > security-report.json

Multi-turn Legal Assistant

# Legal document review with session persistence
session_id=$(claude -p "Start legal review session" --output-format json | jq -r '.session_id')

# Review contract in multiple steps
claude -p --resume "$session_id" "Review contract.pdf for liability clauses"
claude -p --resume "$session_id" "Check compliance with GDPR requirements"
claude -p --resume "$session_id" "Generate executive summary of risks"

Best Practices

Use JSON output format for programmatic parsing:

result=$(claude -p "Generate code" --output-format json)
code=$(echo "$result" | jq -r '.result')
cost=$(echo "$result" | jq -r '.total_cost_usd')

Handle errors gracefully:

if ! claude -p "$prompt" 2>error.log; then
    echo "Error occurred:" >&2
    cat error.log >&2
    exit 1
fi

Use session management for maintaining context in multi-turn conversations

Consider timeouts for long-running operations:

timeout 300 claude -p "$complex_prompt" || echo "Timed out after 5 minutes"

Respect rate limits when making multiple requests by adding delays between calls

Learning Projects

Project 1: Build a Code Review Skill

File: CLAUDE_CODE_CAPABILITIES_LEARNING_GUIDE.md
Main Programming Language: Python
Alternative Programming Languages: TypeScript, Bash
Coolness Level: Level 3: Genuinely Clever
Business Potential: Level 2: The “Micro-SaaS / Pro Tool”
Difficulty: Level 2: Intermediate (The Developer)
Knowledge Area: AI Tooling, Developer Tools
Software or Tool: Claude Code, SKILL.md
Main Book: Claude Code Documentation

What you’ll build: A custom Agent Skill that reviews code changes against your team’s style guide and security standards.

Why it teaches Claude Code: Forces you to understand progressive loading, SKILL.md structure, and how to package executable scripts that run without entering context.

Core challenges you’ll face:

Structuring instructions for effective Claude consumption (maps to progressive disclosure)
Deciding what goes in scripts vs. instructions (maps to code vs. instructions tradeoff)
Writing descriptions that trigger reliably (maps to metadata design)

Difficulty: Intermediate Time estimate: Weekend Prerequisites: Basic Markdown, understanding of your team’s coding standards

Real world outcome: A reusable Skill that automatically reviews PRs using your specific criteria, reducing code review time.

Learning milestones:

Create a working SKILL.md that Claude triggers appropriately
Add Python scripts that perform static analysis without context cost
Integrate additional files (SECURITY_RULES.md, STYLE_GUIDE.md) loaded on-demand

Project 2: Create a Domain-Specific Subagent Team

File: domain_specific_subagent_team.md
Main Programming Language: TypeScript
Alternative Programming Languages: Python, JavaScript
Coolness Level: Level 3: Genuinely Clever
Business Potential: Level 2: The “Micro-SaaS / Pro Tool”
Difficulty: Level 2: Intermediate (The Developer)
Knowledge Area: AI Agents, Workflow Orchestration
Software or Tool: Claude Code, Claude API
Main Book: “Designing Data-Intensive Applications” by Martin Kleppmann

What you’ll build: A coordinated set of subagents - architect, implementer, tester, documenter - that work together on features.

Why it teaches Claude Code: You’ll master subagent configuration, tool restriction, model selection, and task delegation patterns.

Core challenges you’ll face:

Defining clear boundaries between subagent responsibilities
Choosing appropriate tool restrictions for each role
Writing prompts that enable proactive subagent usage
Managing context handoffs between subagents

Difficulty: Intermediate Time estimate: 1-2 weeks Prerequisites: Understanding of software development workflows

Real world outcome: Type “build feature X” and watch Claude orchestrate specialized agents to architect, implement, test, and document automatically.

Learning milestones:

Create single subagent that handles one phase well
Build all four subagents with appropriate tool restrictions
Achieve seamless handoffs where Claude chains them automatically

Project 3: Build a Custom Output Style for Teaching

File: custom_output_style_teaching.md
Main Programming Language: TypeScript
Alternative Programming Languages: Python, JavaScript
Coolness Level: Level 2: Practical but Forgettable
Business Potential: Level 2: The “Micro-SaaS / Pro Tool”
Difficulty: Level 1: Beginner (The Tinkerer)
Knowledge Area: Prompt Engineering, AI Assistants
Software or Tool: Claude Code
Main Book: “The Art of Prompt Engineering” (Anthropic Documentation)

What you’ll build: An output style that transforms Claude Code into an interactive tutor that explains concepts, quizzes you, and adapts to your learning pace.

Why it teaches Claude Code: Output styles directly modify the system prompt, so you’ll understand exactly what instructions shape Claude’s behavior.

Core challenges you’ll face:

Writing comprehensive system prompts that cover all interaction patterns
Deciding what default behaviors to keep (keep-coding-instructions)
Testing across different task types

Difficulty: Beginner-Intermediate Time estimate: Weekend Prerequisites: Basic understanding of prompt engineering

Real world outcome: A personalized learning assistant that teaches you any technology through guided coding exercises.

Learning milestones:

Override default behavior to add explanatory mode
Add quiz generation and concept reinforcement
Create adaptive difficulty based on user responses

Project 4: CI/CD Integration Pipeline

File: cicd_integration_pipeline.md
Main Programming Language: TypeScript
Alternative Programming Languages: Python, Bash
Coolness Level: Level 3: Genuinely Clever
Business Potential: Level 3: The “Service & Support” Model
Difficulty: Level 3: Advanced (The Engineer)
Knowledge Area: CI/CD, DevOps, Automation
Software or Tool: GitHub Actions, Claude Code
Main Book: “Continuous Delivery” by Jez Humble and David Farley

What you’ll build: A GitHub Actions workflow that uses Claude Code headless mode to automatically review PRs, suggest improvements, and generate release notes.

Why it teaches Claude Code: Forces you to master non-interactive mode, JSON parsing, session management, and tool permissions in automated contexts.

Core challenges you’ll face:

Parsing streaming JSON output reliably
Managing sessions for multi-turn workflows
Handling timeouts and errors gracefully
Configuring appropriate tool permissions for CI

Difficulty: Advanced Time estimate: 1-2 weeks Prerequisites: GitHub Actions, bash scripting, JSON handling

Real world outcome: Every PR gets AI-powered review, and releases get auto-generated notes summarizing changes.

Learning milestones:

Basic headless call that analyzes PR diff
Multi-turn conversation using --resume for iterative review
Full pipeline with PR comments, status checks, and release automation

Project Comparison

Project	Difficulty	Time	Depth of Understanding	Fun Factor
Code Review Skill	Intermediate	Weekend	Skills architecture	⭐⭐⭐
Subagent Team	Intermediate	1-2 weeks	Task delegation, context	⭐⭐⭐⭐
Custom Output Style	Beginner-Int	Weekend	System prompt engineering	⭐⭐⭐⭐⭐
CI/CD Pipeline	Advanced	1-2 weeks	Headless automation	⭐⭐⭐⭐

Recommended Learning Path

Based on the goal to “deeply learn” Claude Code capabilities, follow this progression:

Start with Output Styles (Project 3) - Quickest to complete, directly shows how system prompts shape behavior
Move to Agent Skills (Project 1) - Builds on prompt understanding, adds progressive loading concept
Then Subagents (Project 2) - Combines everything: prompts + skills + delegation
Finally CI/CD (Project 4) - Applies all knowledge to real automation

Final Capstone Project: Personal AI Development Team

What you’ll build: A complete Claude Code customization suite that includes:

Custom output style for your preferred interaction mode
3-4 specialized subagents for your workflow (reviewer, tester, documenter, researcher)
Reusable skills for your domain (API patterns, database migrations, deployment scripts)
CI/CD integration that orchestrates everything automatically on every PR

Why this teaches everything: You’ll combine all four capability areas into a cohesive system that reflects your personal development workflow.

Real world outcome: Type a feature request and watch Claude Code architect it, implement it, test it, document it, and set up the PR review - all using your custom configuration that encodes your team’s best practices.

Difficulty: Advanced Time estimate: 1 month+

Learning milestones:

Each individual component works in isolation
Components integrate - subagents load skills, output style guides interactions
CI/CD pipeline orchestrates the full workflow automatically
System is portable - package as a Claude Code plugin for team sharing

Resources

Official Documentation

Additional Resources

Agent Skills Cookbook
Equipping agents for the real world with Agent Skills - Engineering blog deep dive

Deep Learning Claude Code Capabilities

Core Concept Analysis

1. Agent Skills

What It Is

Key Architecture

Configuration File (SKILL.md)

Locations

How Skills Work

Security Considerations

2. Subagents

What They Are

Built-in Subagents

Key Benefits

Configuration File

Configuration Fields

Locations

Usage

Example: Code Reviewer Subagent

Example: Debugger Subagent

3. Output Styles

What They Are

Built-in Styles

How Output Styles Work

Custom Output Style File

Frontmatter Properties

Locations

Usage

Comparisons to Related Features

4. Headless Mode

What It Is

Basic Usage

Key Flags

Output Formats

Text Output (Default)

JSON Output

Streaming JSON Output

Multi-turn Conversations

Automation Use Cases

SRE Incident Response Bot

Automated Security Review

Multi-turn Legal Assistant

Best Practices

Learning Projects

Project 1: Build a Code Review Skill

Project 2: Create a Domain-Specific Subagent Team

Project 3: Build a Custom Output Style for Teaching

Project 4: CI/CD Integration Pipeline

Project Comparison

Recommended Learning Path

Final Capstone Project: Personal AI Development Team

Resources

Official Documentation

Additional Resources