# Claude Code Skill

> Claude Code Expert — use when the user asks about Claude Code CLI features, configuration, hooks, skills/commands, MCP servers, IDE integrations, settings, keybindings, agents, slash commands, memory, CLAUDE.md, or any Claude Code workflow question.

- Skill: `sirhamza/claude-code-skill` (Agent Skill)
- Install (CLI): `npx skillmds@latest add sirhamza/claude-code-skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/sirhamza/claude-code-skill/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: SirHamza (https://skillmd.com/u/sirhamza)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/sirhamza/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)
```json
{
  "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
| Field | Purpose |
|---|---|
| `model` | Default model ID |
| `permissions.allow` | Auto-approve tool calls matching patterns |
| `permissions.deny` | Always block matching tool calls |
| `mcpServers` | MCP server definitions |
| `hooks` | Shell commands triggered on events |
| `env` | Environment variable overrides |
| `theme` | UI theme (`dark`, `light`, `system`) |

---

## 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
```yaml
---
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
| Variable | Meaning |
|---|---|
| `$ARGUMENTS` | All args passed to skill |
| `$ARGUMENTS[0]` | First argument |
| `$1`, `$2` | Shorthand index |
| `` !`shell cmd` `` | Inject shell output at load time |

### 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
| Event | Trigger |
|---|---|
| `PreToolUse` | Before any tool call |
| `PostToolUse` | After tool call completes |
| `Notification` | When Claude sends a notification |
| `Stop` | When Claude finishes a response |
| `UserPromptSubmit` | When user submits a message |

### Hook Configuration (`settings.json`)
```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
| Variable | Available in |
|---|---|
| `CLAUDE_TOOL_NAME` | Pre/PostToolUse |
| `CLAUDE_TOOL_INPUT` | PreToolUse (JSON string) |
| `CLAUDE_TOOL_OUTPUT` | PostToolUse (JSON string) |
| `CLAUDE_SESSION_ID` | All hooks |
| `CLAUDE_TOOL_INPUT_FILE_PATH` | PostToolUse Write/Edit |

### 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`
```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
| Type | Tools | Best For |
|---|---|---|
| `Bash` | Bash only | Git, CLI, terminal ops |
| `general-purpose` | All tools | Multi-step research |
| `Explore` | Read-only + search | Large codebase exploration |
| `Plan` | Read-only + search | Architecture planning |
| `claude-code-guide` | Fetch + search | Claude Code questions |
| `statusline-setup` | Read, Edit | Status line config |

### 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`
```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
| Key | Action |
|---|---|
| `Enter` | Submit message |
| `Shift+Enter` | Newline |
| `Ctrl+C` | Interrupt/cancel |
| `Ctrl+R` | Search history |
| `Tab` | Autocomplete |
| `↑` / `↓` | History navigation |
| `Escape` | Cancel current |

---

## 11. CLI Reference

### Startup Flags
```bash
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)
| Command | Action |
|---|---|
| `/help` | Show help |
| `/clear` | Clear conversation |
| `/compact` | Compress conversation history |
| `/resume [id]` | Resume session |
| `/memory` | Edit memory file |
| `/ide` | IDE connection setup |
| `/mcp` | MCP server status |
| `/status` | Show current config/session |
| `/cost` | Show token usage |
| `/bug` | Report a bug |
| `/doctor` | Diagnose config issues |
| `/<skill-name>` | Invoke a skill |

### 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
```bash
# 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
```bash
# 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
```markdown
# 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
```json
{
  "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
| Symptom | Fix |
|---|---|
| Skill not appearing in `/` menu | Check `user-invocable: true` and directory name matches |
| MCP server not connecting | Run `claude /mcp` to see server status and error logs |
| Hook not firing | Verify `matcher` regex matches tool name exactly |
| Session not resuming | Use `claude --list-sessions` to find valid session IDs |
| Permission denied on tool | Check `permissions.allow` pattern syntax |
| High token usage | Use `/compact`, background agents, or narrower tool permissions |

### Diagnostic Commands
```bash
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