Claude Code Skill

Claude Code Expert

Overview

Advanced expertise in Claude Code — Anthropic's official agentic CLI. Covers configuration, extensibility, agentic workflows, IDE integrations, MCP servers, skills/commands, hooks, memory management, and production-grade automation patterns.

1. Core Architecture

• Interactive mode: claude — REPL session with full context persistence
• Non-interactive (pipe) mode: echo "task" | claude — single-shot, scriptable
• Print mode: claude -p "prompt" — one-shot, outputs to stdout, no session saved
• Resume session: claude --resume <session-id> — continue a prior conversation
• Session files: stored in ~/.claude/projects/<encoded-path>/*.jsonl
• Config hierarchy: project CLAUDE.md → personal ~/.claude/CLAUDE.md → settings.json
• Model selection: --model claude-opus-4-6 flag or model key in settings.json
• Max tokens / thinking: --max-tokens, --thinking flags for extended reasoning

2. Configuration Files

~/.claude/settings.json (Personal) / .claude/settings.json (Project)

{
  "model": "claude-opus-4-6",
  "theme": "dark",
  "autoUpdaterStatus": "enabled",
  "preferredNotifChannel": "terminal_bell",
  "permissions": {
    "allow": ["Bash(git:*)", "Read(**)", "Edit(**)"],
    "deny": ["Bash(rm -rf*)"]
  },
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-..."
  },
  "mcpServers": { ... },
  "hooks": { ... }
}

CLAUDE.md — Persistent System Instructions

• Auto-loaded as system prompt for every session in that project
• Supports @path/to/file imports to include other markdown files
• Chain: ~/.claude/CLAUDE.md (global) → .claude/CLAUDE.md (project) → subdirectory CLAUDE.md
• Use for: coding standards, project context, forbidden patterns, tool preferences

Key Settings Fields

3. Permission System

Permission Modes (startup flags)

• --dangerously-skip-permissions — skip all permission prompts (use in CI only)
• --allowedTools "Read,Edit,Bash(git:*)" — pre-approve specific tools
• --disallowedTools "Bash" — pre-block specific tools

Pattern Syntax for permissions.allow/deny

"Bash(git:*)"          → git subcommands only
"Bash(npm run *)"      → npm run scripts
"Read(**)"             → any file read
"Edit(src/**)"         → edits in src/ only
"WebFetch(https://api.example.com/*)"

Tool Names

Bash, Read, Write, Edit, Glob, Grep, WebFetch, WebSearch, Task, NotebookEdit, mcp__<server>__<tool>

4. Skills & Commands System

Directory Structure

~/.claude/skills/<skill-name>/SKILL.md   ← personal (all projects)
.claude/skills/<skill-name>/SKILL.md     ← project-scoped

SKILL.md Frontmatter Fields

---
name: my-skill
description: "When to invoke — be explicit: 'use when user asks about X'"
argument-hint: "[optional-arg]"
user-invocable: true          # shows in / menu
disable-model-invocation: false
allowed-tools: Read, Grep
model: claude-opus-4-6        # per-skill model override
context: fork                 # run in isolated subagent
agent: Explore                # subagent type (requires context: fork)
---

String Substitutions in SKILL.md

Invoking Skills

• /skill-name [args] — slash command in REPL
• Auto-triggered when description matches user intent
• claude /skill-name args — CLI invocation

5. Hooks System

Hooks run shell commands in response to Claude Code lifecycle events.

Hook Events

Hook Configuration (settings.json)

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo '[HOOK] About to run Bash' >&2"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{ "type": "command", "command": "prettier --write $CLAUDE_TOOL_INPUT_FILE_PATH" }]
      }
    ]
  }
}

Hook Environment Variables

Hook Exit Codes

• 0 — success, continue
• 1 — block the tool call (PreToolUse), log error (Post)
• Stdout → shown to Claude as context
• Stderr → shown to user only

6. MCP Servers

Configuration in settings.json

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"],
      "env": { "NODE_ENV": "production" }
    },
    "my-api": {
      "command": "python",
      "args": ["-m", "my_mcp_server"],
      "env": { "API_KEY": "..." }
    },
    "remote-sse": {
      "url": "https://mcp.example.com/sse",
      "headers": { "Authorization": "Bearer token" }
    }
  }
}

Transport Types

• stdio — subprocess via stdin/stdout (default when command is set)
• sse — HTTP Server-Sent Events (set url instead of command)
• http — streamable HTTP (newer, preferred for remote)

MCP Tool Naming

Tools appear as mcp__<server-name>__<tool-name> in permission rules.

CLI Flags

• --mcp-server name=command — inline server definition
• --no-mcp — disable all MCP servers for session

7. Memory System

Auto Memory (MEMORY.md pattern)

• ~/.claude/projects/<encoded-cwd>/memory/MEMORY.md — session-persistent notes
• Loaded into system prompt automatically (first 200 lines)
• Topic files: memory/debugging.md, memory/patterns.md, etc.

Explicit Memory Commands

• /memory — open memory file for editing
• Reference via @memory/topic.md in CLAUDE.md

Session Files

• Location: ~/.claude/projects/<encoded-cwd>/*.jsonl
• Resume: claude --resume (latest) or claude --resume <id>
• List: claude --list-sessions

8. Subagents (Task Tool)

Available Agent Types

Task Tool Parameters

subagent_type: "Explore"
prompt: "Detailed task description..."
run_in_background: true   # async, returns output_file path
resume: "<agent-id>"      # continue prior agent session
model: "haiku"            # override model for cost/speed
max_turns: 10

When to Use Subagents

• Parallel independent searches → multiple Task calls in one message
• Large codebase (8+ files) → Explore agent
• Protect context window from large outputs → background agent
• Architecture decisions → Plan agent

9. IDE Integrations

VS Code Extension

• Install: claude command → /ide → VS Code
• Features: inline diff, diagnostic context, file references with @filename
• Keybinding: Ctrl+Esc (toggle), Ctrl+Shift+C (new session)

JetBrains Plugin

• IntelliJ, PyCharm, WebStorm, etc.
• Install via JetBrains Marketplace: "Claude Code"
• Same diff/diagnostic integration as VS Code

Cursor / Windsurf

• Works via terminal pane — no special integration needed

Diff Workflow

• Claude proposes edits → IDE shows diff panel → user accepts/rejects per-file

10. Keybindings

Config File: ~/.claude/keybindings.json

[
  { "key": "ctrl+shift+r", "command": "claude.restartSession" },
  { "key": "ctrl+enter",   "command": "claude.submitMessage" },
  {
    "key": "ctrl+k ctrl+c",
    "command": "claude.runSkill",
    "args": { "skill": "commit" }
  }
]

Default Keybindings

11. CLI Reference

Startup Flags

claude                              # interactive REPL
claude -p "task"                    # print mode (non-interactive)
claude --model claude-opus-4-6      # model override
claude --resume                     # resume latest session
claude --resume <session-id>        # resume specific session
claude --allowedTools "Read,Edit"   # pre-approve tools
claude --dangerously-skip-permissions  # skip all prompts (CI)
claude --no-mcp                     # disable MCP servers
claude --max-tokens 8192
claude --thinking                   # enable extended thinking
claude --output-format json         # structured JSON output
claude --verbose                    # debug logging

Slash Commands (REPL)

File References

• @filename — attach file content to message
• @directory/ — attach all files in directory
• Drag-and-drop files into terminal → auto-attached

12. Advanced Patterns

CI/CD Non-Interactive Usage

# GitHub Actions
- name: Claude Code Review
  run: |
    echo "${{ github.event.pull_request.body }}" | \
    claude -p "Review this PR for security issues" \
      --allowedTools "Read,Glob,Grep" \
      --output-format json

Piping & Scripting

# Feed context, get structured output
cat error.log | claude -p "Analyze this error and suggest a fix" --output-format json

# Multi-file context
{ cat src/auth.py; echo "---"; cat tests/test_auth.py; } | \
  claude -p "Find bugs in the auth implementation"

CLAUDE.md Best Practices

# Project: MyApp

## Tech Stack
- Python 3.12, FastAPI, PostgreSQL, Redis
- Testing: pytest + pytest-asyncio
- Linting: ruff + mypy strict

## Conventions
- All endpoints must have Pydantic request/response models
- Use `async def` for all route handlers
- Never commit secrets — use environment variables

## Forbidden
- Never use `os.system()`, use `subprocess.run()`
- Never `import *`

@.claude/architecture.md
@.claude/api-contracts.md

Parallel Tool Calls Pattern

When Claude should call multiple tools simultaneously:

• Independent searches → all in one response turn
• Background agents → run_in_background: true + TaskOutput to retrieve
• Reduces latency significantly for research tasks

Context Window Management

• /compact — summarize and compress history mid-session
• Use Explore subagent for large codebases (protects main context)
• --max-tokens controls response length, not context window
• Session .jsonl files are the full context; large projects accumulate quickly

13. Plugins System

Plugin Locations

~/.claude/plugins/               ← personal plugins
.claude/plugins/                 ← project plugins

Plugin Structure

my-plugin/
├── plugin.json      # manifest
├── skills/
│   └── my-skill/
│       └── SKILL.md
├── hooks/
│   └── pre-tool.sh
└── mcpServers/
    └── server.json

plugin.json Manifest

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "What this plugin provides",
  "skills": ["my-skill"],
  "mcpServers": { ... }
}

14. Security Best Practices

• Use permissions.deny to block destructive Bash patterns: "Bash(rm -rf*)"
• Avoid --dangerously-skip-permissions outside isolated CI environments
• Store API keys in environment variables, not settings.json committed to git
• Use project-scoped settings.json for team sharing; personal for secrets
• Hook scripts should be idempotent and fail-safe (non-zero exit blocks tool)
• Audit PreToolUse hooks before trusting in shared repos — they run on your machine
• MCP servers run as subprocesses with your user permissions — vet before installing

15. Debugging & Troubleshooting

Common Issues

Diagnostic Commands

claude /doctor        # config validation
claude /status        # current session + model info
claude /mcp           # MCP server connection status
claude --verbose      # debug output for all tool calls

Core Competency Summary

• Configure Claude Code for team projects with CLAUDE.md + settings.json
• Build expert-level skills with frontmatter, substitutions, and forked subagents
• Design hooks for automated linting, formatting, and security checks
• Integrate MCP servers (local stdio + remote SSE/HTTP)
• Orchestrate parallel subagent workflows for large codebases
• Manage sessions, memory, and context window efficiently
• Secure Claude Code deployments in CI/CD pipelines
• Debug configuration, permissions, and MCP connectivity issues