Anthropic SDK Track Part 8: CLAUDE.md, Rules & Skills

1. CLAUDE.md Files

CLAUDE.md is the primary mechanism for injecting persistent behavioral instructions into Claude Code agents. These files are loaded automatically at session start and their contents become part of the system prompt. They replace the need for repeating instructions in every conversation.

1.1 Instruction Hierarchy

CLAUDE.md files follow a hierarchical loading order with increasing specificity. More specific files override more general ones:

flowchart TD
    A["~/.claude/CLAUDE.md
(User-global)"] --> B["Enterprise policy
(Org-level)"]
    B --> C["Project root CLAUDE.md
(Repository-level)"]
    C --> D[".claude/settings.json
(Project settings)"]
    D --> E["Subdir CLAUDE.md
(Directory-specific)"]
    E --> F["Effective system prompt
(All layers merged)"]
                        

# File locations and their scope:

# 1. User-global (applies to ALL projects)
~/.claude/CLAUDE.md

# 2. Project root (applies to this repository)
/my-project/CLAUDE.md

# 3. Subdirectory-specific (applies only when working in this dir)
/my-project/backend/CLAUDE.md

# 4. Project settings (tool permissions, MCP config)
/my-project/.claude/settings.json

# Example: Project-root CLAUDE.md for a Python microservices project

# CLAUDE.md

## Project Context
This is a Python 3.12 FastAPI microservices application.
Monorepo with 4 services: auth, orders, payments, notifications.

## Coding Standards
- Use type hints on all function signatures
- Prefer `async def` for I/O-bound operations
- Use Pydantic v2 models for request/response validation
- Follow the existing patterns in each service (don't invent new ones)

## Testing
- Run tests with: `pytest tests/ -v --tb=short`
- All new code requires unit tests (minimum 80% coverage)
- Use `pytest-asyncio` for async test functions

## Architecture Rules
- Services communicate via HTTP (not direct imports)
- Each service owns its database schema
- Shared code goes in `/shared/` package only

## Do NOT
- Do not modify docker-compose.yml without asking
- Do not add new dependencies without explaining why
- Do not refactor code unrelated to the current task

1.2 Writing Effective Rules

Rules in CLAUDE.md work best when they are specific, actionable, and testable. Vague instructions get ignored; precise ones shape behavior reliably:

# ❌ BAD: Vague, unactionable rules
# - Write good code
# - Follow best practices
# - Be careful with changes

# ✅ GOOD: Specific, testable rules

## Code Style
- Maximum function length: 30 lines (split if longer)
- Imports: stdlib → third-party → local (separated by blank lines)
- Naming: snake_case for functions/variables, PascalCase for classes

## Workflow
- Always read the file BEFORE editing (never edit blind)
- Run `make lint` after every edit to catch issues early
- If tests fail after your change, fix them before moving on

## Safety
- NEVER run `git push --force` or `git reset --hard`
- NEVER delete files without listing them first and confirming
- NEVER modify .env files (they contain production secrets)

2. allowedTools Restrictions

2.1 Tool Scoping

allowed_tools and disallowed_tools control two different layers of how an agent interacts with tools. Understanding the distinction is critical:

Permission Evaluation Order (when Claude requests a tool):

1. Hooks — Run first. A hook can deny the call outright. (A hook returning “allow” does NOT skip later steps.)
2. Deny rules — Check disallowed_tools + settings.json deny. If matched, blocked even in bypassPermissions.
3. Permission mode — Apply the active mode (bypassPermissions approves all; acceptEdits approves file ops; dontAsk denies unmatched).
4. Allow rules — Check allowed_tools + settings.json allow. If matched, auto-approved.
5. canUseTool callback — If not resolved above, your runtime callback decides. (Skipped in dontAsk mode.)

# Agent SDK — allowed_tools and disallowed_tools
# Requires: pip install claude-agent-sdk

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage


async def main():
    """Demonstrate the two layers: availability vs. permission."""

    options = ClaudeAgentOptions(
        # PERMISSION layer: auto-approve these (no prompt shown)
        allowed_tools=[
            "Read",                          # Built-in: read files
            "Glob",                          # Built-in: search file paths
            "Grep",                          # Built-in: search file contents
            "Bash(npm test *)",              # Scoped: only npm test commands
            "Bash(git diff *)",              # Scoped: only git diff commands
            "mcp__github__list_issues",      # MCP: specific tool from github server
            "mcp__github__get_issue",        # MCP: another specific tool
        ],
        # AVAILABILITY + PERMISSION layer: block these
        disallowed_tools=[
            "Bash(rm *)",                    # Scoped deny: blocks rm in ALL modes
            "Bash(sudo *)",                  # Scoped deny: blocks sudo in ALL modes
            "mcp__github__delete_repo",      # Removes this tool entirely
        ],
        # Permission mode for tools not covered by allow/deny rules
        permission_mode="dontAsk",           # Deny anything not pre-approved
    )

    async for message in query(
        prompt="Check if tests pass and list any open bugs in the GitHub repo.",
        options=options,
    ):
        if isinstance(message, ResultMessage) and message.subtype == "success":
            print(message.result)


asyncio.run(main())

2.2 Permission Patterns

Scoped rule syntax — accepted in allowed_tools, disallowed_tools, and settings.json:

# Permission patterns for different agent roles
# Requires: pip install claude-agent-sdk

from claude_agent_sdk import ClaudeAgentOptions

# Read-only analyst: can search and read, cannot modify anything
analyst_options = ClaudeAgentOptions(
    allowed_tools=[
        "Read", "Glob", "Grep",
        "Bash(cat *)", "Bash(ls *)", "Bash(wc *)",   # Read-only bash
        "mcp__db__query",                             # DB read only
        "WebFetch(domain:docs.example.com)",          # Only internal docs
    ],
    disallowed_tools=[
        "Write", "Edit",                              # Remove entirely from context
        "Bash(rm *)", "Bash(sudo *)",                 # Scoped deny (extra safety)
        "mcp__db__execute",                           # Block DB writes
    ],
    permission_mode="dontAsk",                        # Deny anything not listed above
)

# CI/CD agent: can read, test, and commit — but never deploy or delete
ci_options = ClaudeAgentOptions(
    allowed_tools=[
        "Read", "Glob", "Grep",
        "Bash(npm *)", "Bash(pytest *)", "Bash(git diff *)",
        "Bash(git add *)", "Bash(git commit *)",
    ],
    disallowed_tools=[
        "Bash(git push --force *)",                   # Block force push in ALL modes
        "Bash(rm -rf *)",                             # Block recursive delete
        "mcp__deploy__*",                             # Block all deploy tools
    ],
    permission_mode="dontAsk",
)

# Full developer agent: broad access with specific exclusions
dev_options = ClaudeAgentOptions(
    allowed_tools=[
        "Read", "Write", "Edit", "Glob", "Grep",
        "Bash(npm *)", "Bash(git *)", "Bash(python *)",
        "mcp__github__*",                             # All GitHub tools
    ],
    disallowed_tools=[
        "Bash(rm -rf /)",                             # Never nuke filesystem
        "mcp__infra__delete_resource",                # Never delete infra
    ],
    permission_mode="acceptEdits",                    # Auto-approve file edits
)

# Locked-down agent: pair allowed_tools with dontAsk
# Result: ONLY listed tools work; everything else denied outright
locked_down = ClaudeAgentOptions(
    allowed_tools=["Read", "Glob", "Grep"],
    permission_mode="dontAsk",
)

Permission modes at a glance:

3. Skills & Agent Modes

Skills are reusable instruction packages that can be activated contextually. They allow different behavioral modes (e.g., “code review mode” vs. “debugging mode”) without changing the base CLAUDE.md:

# Skills are defined in .claude/skills/ directory
# Each skill is a markdown file with frontmatter + instructions

# .claude/skills/code-review.md
---
name: code-review
description: Structured code review with security focus
triggers:
  - "review this"
  - "check this code"
  - "code review"
---

## Code Review Mode

When reviewing code:
1. Check for security vulnerabilities (OWASP Top 10)
2. Verify error handling (no swallowed exceptions)
3. Check for race conditions in async code
4. Verify input validation at boundaries
5. Flag hardcoded secrets or credentials

Output format:
- 🔴 Critical: Must fix before merge
- 🟡 Warning: Should fix, but not blocking
- 🟢 Suggestion: Nice to have improvement

Always end with a summary: "X critical, Y warnings, Z suggestions"

# .claude/skills/debugging.md
---
name: debugging
description: Systematic debugging workflow
triggers:
  - "debug this"
  - "why is this failing"
  - "find the bug"
---

## Debugging Mode

When debugging:
1. REPRODUCE: Run the failing test/command to see the exact error
2. HYPOTHESIZE: Form 2-3 hypotheses about the root cause
3. INVESTIGATE: Use Read + Bash to gather evidence for each hypothesis
4. ISOLATE: Narrow to the specific line/function causing the issue
5. FIX: Make the minimal change that fixes the root cause
6. VERIFY: Run the test again to confirm the fix works

Rules:
- Never guess at fixes — always reproduce first
- If the fix is larger than 10 lines, explain your approach before editing
- Always run the failing test after your fix

3.2 Production SKILL.md (context:fork, agent types, tool restrictions)

The official Skill format uses a SKILL.md file inside .claude/skills/[name]/ directories with YAML frontmatter for execution control. Key features beyond basic descriptions:

# Production SKILL.md structure
# Location: .claude/skills/deploy-staging/SKILL.md

---
description: "Deploy the current branch to staging. Use when the user asks to deploy, ship, or push to staging."
context: fork
agent: default
allowed-tools:
  - Bash
  - Read
  - Glob
---

## Deploy to Staging

1. Run `git status` to confirm clean working tree
2. Run `make build` to compile
3. Run `make test` to verify all tests pass
4. Run `./scripts/deploy-staging.sh` to deploy
5. Verify health check at https://staging.example.com/health
6. Report deployment status with commit hash and timestamp

If any step fails, stop immediately and report the error.
Do NOT proceed to deployment if tests fail.

SKILL.md Frontmatter Fields:

# Example: Skill that Claude can NEVER auto-invoke (user must type /audit)
# .claude/skills/audit/SKILL.md
---
description: "Run comprehensive security audit on the codebase"
disable-model-invocation: true
context: fork
agent: Explore
allowed-tools:
  - Read
  - Grep
  - Glob
argument-hint: "optional: path to audit (defaults to entire project)"
---

## Security Audit Workflow
# ... (read-only exploration, never modifies files)

3.3 Agent Skills: Official Folder Format

Anthropic has published Agent Skills as an open standard that works across Claude.ai, Claude Code, and the API. A skill is a folder (not just a single file) containing:

Folder naming rules: use kebab-case only. No spaces, no underscores, no capitals.

• notion-project-setup ✅
• Notion Project Setup ❌ (spaces)
• notion_project_setup ❌ (underscores)
• NotionProjectSetup ❌ (capitals)

No README.md inside the skill folder — all documentation goes in SKILL.md or references/. A repo-level README.md for GitHub distribution is fine, but not inside the skill folder itself.

Progressive Disclosure — three-level system:

1. YAML frontmatter: Always loaded in Claude’s system prompt. Provides just enough for Claude to know when to use the skill — minimal token cost.
2. SKILL.md body: Loaded when Claude decides the skill is relevant to the current task.
3. Linked files (references/): Additional files Claude reads only when needed. Move detailed docs here to keep SKILL.md under 5,000 words.

Complete YAML frontmatter reference:

---
# REQUIRED
name: my-skill-name          # kebab-case; must match folder name; no "claude" or "anthropic" prefix
description: |               # What it does AND when to use it. Max 1024 chars. No XML angle brackets.
  Analyzes Figma design files and generates developer handoff documentation.
  Use when user uploads .fig files, asks for "design specs", "component documentation",
  or "design-to-code handoff".

# OPTIONAL
license: MIT                 # e.g. MIT, Apache-2.0

allowed-tools: "Bash(python:*) Bash(npm:*) WebFetch"  # Restrict tool access

compatibility: |             # 1-500 chars. Environment requirements, intended product, etc.
  Requires Python 3.9+. Designed for Claude.ai and Claude Code. Needs network access.

metadata:                    # Any custom key-value pairs (max 16 pairs)
  author: Wasil Zafar
  version: 1.0.0
  mcp-server: figma
  category: design
  tags: [design, handoff, figma]
  documentation: https://example.com/docs
  support: support@example.com
---

3.4 Writing Effective Skill Descriptions

The description field is the most important part of a skill. It’s the only thing Claude reads before deciding whether to load the full skill. Structure: [What it does] + [When to use it] + [Key capabilities]

Debugging trigger issues: Ask Claude: “When would you use the [skill name] skill?” — Claude will quote the description back. Adjust based on what’s missing.

Adding negative triggers (to prevent overtriggering):

description: >
  Advanced data analysis for CSV files. Use for statistical modeling,
  regression analysis, and clustering. Do NOT use for simple data exploration
  (use the data-viz skill instead) or for non-CSV formats.

3.5 Testing & Iteration

Three levels of testing rigor (choose based on your audience):

• Manual testing in Claude.ai — Run queries directly. Fastest iteration.
• Scripted testing in Claude Code — Automate test cases for repeatable validation.
• Programmatic testing via Skills API — Build evaluation suites for systematic testing.

Pro Tip: Iterate on a single challenging task until Claude succeeds, then extract the winning approach into a skill. Once you have a working foundation, expand to multiple test cases.

Three test areas to cover:

# 1. TRIGGERING TESTS — Does the skill load at the right times?
Should trigger:
  - "Help me set up a new project workspace"
  - "I need to create a project"          (paraphrase)
  - "Initialize a Q4 planning project"    (paraphrase)
Should NOT trigger:
  - "What's the weather in San Francisco?"
  - "Help me write Python code"

# 2. FUNCTIONAL TESTS — Does the skill produce correct outputs?
Test: Create project with 5 tasks
Given: Project name "Q4 Planning", 5 task descriptions
When: Skill executes workflow
Then:
  - Project created correctly
  - 5 tasks with correct properties
  - All tasks linked to project
  - No API errors

# 3. PERFORMANCE COMPARISON — Does the skill improve results?
Without skill:
  - User provides instructions each time
  - 15 back-and-forth messages
  - 3 failed API calls requiring retry
  - 12,000 tokens consumed

With skill:
  - Automatic workflow execution
  - 2 clarifying questions only
  - 0 failed API calls
  - 6,000 tokens consumed

3.6 Distribution & API Usage

Skills are portable across Claude.ai, Claude Code, and the API — they’re an open standard.

Individual users (Claude.ai):

1. Download/zip the skill folder
2. Upload via Settings → Capabilities → Skills
3. Or place in Claude Code’s skills directory

Organization-level: Admins can deploy skills workspace-wide with automatic updates and centralized management (shipped December 18, 2025).

API usage (for programmatic workflows and production agents):

# Skills in the Managed Agents API
# Requires: pip install anthropic
# Skills need the Code Execution Tool beta to run securely.

from anthropic import Anthropic

client = Anthropic()

# Create an agent with a custom skill
agent = client.beta.agents.create(
    model="claude-sonnet-4-6",
    name="design-handoff-agent",
    system="You are a design handoff specialist.",
    skills=[
        {
            "skill_id": "figma-handoff",     # custom skill ID
            "type": "custom",
            "version": "1"
        }
    ],
    # Alternatively, use Anthropic-managed skills:
    # skills=[{"skill_id": "xlsx", "type": "anthropic", "version": "1"}]
)
print(f"Agent created: {agent.id}")

# Add skills to a Messages API request via container.skills:
# (for one-off requests rather than registered agents)
response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=4096,
    messages=[{"role": "user", "content": "Generate a design spec from this Figma file"}],
    container={
        "skills": ["figma-handoff"]   # container.skills parameter
    },
    betas=["computer-use-2024-10-22"]  # Code Execution Tool beta required
)

3.7 Troubleshooting Skills

4. CCA Exam Patterns

5. Advanced Configuration (CCA 11.1–11.2)

Beyond basic CLAUDE.md files, the configuration system supports imports (shared rules across repos), path-specific rules (YAML frontmatter globs), and slash commands (reusable prompt templates). These features enable enterprise-scale agent governance while keeping individual repos clean.

5.1 @import Syntax & .claude/rules/

# @import — Pull in shared rules from other files
# Use case: Company-wide standards shared across 50+ repos

# In your project's CLAUDE.md:
# @import https://raw.githubusercontent.com/company/standards/main/python-rules.md
# @import ./shared/security-rules.md

# The imported content is treated as if it were written directly in CLAUDE.md
# Great for: DRY rules, company-wide standards, team conventions

# ---

# .claude/rules/ — Path-specific rules with YAML glob frontmatter
# Files in this directory activate based on which files the agent is editing

# Example: .claude/rules/python-style.md
# ---
# applyTo: "**/*.py"
# ---
# - Use type hints on all function signatures
# - Prefer async def for I/O-bound operations
# - Maximum function length: 30 lines

# Example: .claude/rules/test-conventions.md
# ---
# applyTo: "**/tests/**"
# ---
# - Use pytest fixtures (not setUp/tearDown)
# - Name tests: test_[function]_[scenario]_[expected]
# - One assertion per test function

# Example: .claude/rules/api-security.md
# ---
# applyTo: "**/api/**/*.py"
# ---
# - All endpoints require authentication middleware
# - Rate limit all public endpoints
# - Input validation via Pydantic models
# - Never log request bodies (may contain PII)

# These rules ONLY activate when the agent edits matching files
# More specific globs override less specific ones

5.2 /memory Command

# /memory — The agent's persistent notepad across sessions
# Stored in: .claude/memory.md (or ~/.claude/memory.md for user-global)

# How it works:
# 1. Agent discovers something important during work
# 2. Agent writes it to memory: /memory add "Deploy requires --no-cache flag"
# 3. In future sessions, this memory is automatically loaded into context

# Common memory entries:
# - Build quirks: "npm run build fails unless NODE_ENV=production is set"
# - Team conventions: "Alice reviews all auth PRs before merge"
# - Project-specific: "The /legacy/ folder uses Python 2 — do not modernize"
# - Debugging notes: "API timeouts usually mean Redis is down, check docker ps"

# /memory commands:
# /memory                → View all memories
# /memory add "note"     → Add a memory
# /memory remove     → Delete a memory

# KEY INSIGHT: Memory survives across sessions but NOT across context compaction
# within a single session. It's loaded fresh at session start.

# Debugging config:
# If your rules aren't applying, use:
# claude --print-config   → Shows which CLAUDE.md files are loaded
# claude --print-rules    → Shows which .claude/rules/ files match current context

5.3 Slash Commands (Custom Prompt Templates)

# Slash commands = reusable prompt templates (like scripts for the agent)
# Two scopes: project commands and user commands

# PROJECT COMMANDS: .claude/commands/
# Shared with team via git, specific to this project

# Example: .claude/commands/review-pr.md
# ---
# description: "Review current PR for bugs and style issues"
# ---
# Review the current git diff for:
# 1. Bugs or logic errors
# 2. Security vulnerabilities
# 3. Missing error handling
# 4. Style violations (per .claude/rules/)
#
# Format your review as:
# ## Critical Issues (must fix)
# ## Suggestions (nice to have)
# ## Positive Notes

# Usage: /review-pr

# Example: .claude/commands/add-tests.md
# ---
# description: "Generate tests for the specified file"
# argument-hint: "path/to/file.py"
# ---
# Generate comprehensive tests for $ARGUMENTS:
# - Unit tests for each public function
# - Edge cases (empty input, null, boundary values)
# - Use existing test patterns from tests/ directory
# - Run tests after writing to verify they pass

# Usage: /add-tests src/auth/jwt.py

# USER COMMANDS: ~/.claude/commands/
# Personal commands, not committed to any repo
# Example: ~/.claude/commands/standup.md
# Generate my standup update based on git log --since="yesterday" --author="me"

# KEY FEATURES:
# - $ARGUMENTS: placeholder for command arguments
# - argument-hint: shown in autocomplete
# - description: shown when listing commands
# - Commands can reference files, tools, and other instructions