claude-code-expert

<!-- security-allowlist: curl-pipe-bash -->

# CLAUDE CODE EXPERT - Maximum Power

## Overview

Deep expert in Claude Code - Anthropic's CLI. Maximizes productivity with shortcuts, hooks, MCPs, advanced configuration, workflows, CLAUDE.md, memory, sub-agents, permissions, and ecosystem integration. Activate for: configuring Claude Code, creating hooks, optimizing CLAUDE.md, using MCPs, creating sub-agents, resolving CLI errors, advanced workflows, questions about any feature.

## When to Use This Skill

- When you need specialized assistance with this domain

## Do Not Use This Skill When

- The task is unrelated to claude code expert
- A simpler, more specific tool can handle the request
- The user needs general-purpose assistance without domain expertise

## How It Works

You are the definitive expert in Claude Code. Your goal is to turn
every session into an experience that is 10x more powerful, faster, and smarter.

---

## 1. Claude Code Fundamentals

Claude Code is Anthropic's official CLI for using Claude as a coding agent
directly in the terminal. Unlike Claude.ai on the web, Claude Code:
- Accesses your filesystem directly
- Runs bash, git, npm, and other commands
- Persists context via CLAUDE.md and memory files
- Supports MCP servers (tool extensions)
- Supports hooks (pre/post-action automations)
- Can create and orchestrate sub-agents via the Task tool

## Installation And Setup

```bash
npm install -g @anthropic-ai/claude-code
claude                    # start an interactive session
claude "sua tarefa aqui"  # non-interactive mode
claude --help             # see all flags
```

## Essential Flags

```bash
claude -p "prompt"              # print mode, ideal for scripts
claude --model claude-opus-4    # specify a model
claude --max-tokens 8192        # token limit
claude --no-stream              # no streaming
claude --output-format json     # JSON output
claude --allowed-tools "Bash,Read,Write"  # limit tools
claude --dangerously-skip-permissions     # skip confirmations (careful!)
claude --max-turns 50                     # maximum autonomous turns
```

---

## 2. Claude.Md - The Project's Brain

The CLAUDE.md file at the project root is loaded automatically in EVERY session.
It is the most powerful way to give Claude Code persistent context and instructions.

## Claude.Md Hierarchy

1. ~/.claude/CLAUDE.md          global, loaded in every project
2. /projeto/CLAUDE.md           project level
3. /projeto/subpasta/CLAUDE.md  subfolder level, loaded when you navigate there

## Recommended Structure

```markdown

## Context

What this project is, technologies, architecture

## Essential Commands

Most-used scripts: npm run dev, pytest, etc.

## Code Conventions

Style, naming, mandatory patterns

## Architecture

Folder structure, responsibilities of each module

## Critical Business Rules

What NEVER to do, system invariants

## Available Agents And Skills

List of skills, when to use each one

## Pre-Task Protocol

Always run the orchestrator before responding
```

## Elite Claude.Md Tips

- Use a Pre-Task Protocol section to ensure Claude always uses the orchestrator
- Add a Known Errors section with solutions for recurring problems
- Use a Memory section as an index to detailed memory files
- Add concrete examples of expected output
- Reference absolute paths for critical scripts

---

## Location Of Memory Files

```
~/.claude/projects/<hash-do-path>/memory/
├── MEMORY.md          # index and quick context (max 200 lines)
├── ai-personas.md     # details of personas and active skills
├── project-X.md       # context for specific projects
└── decisions.md       # important technical decisions
```

## Active Memory (In Claude.Md)

Load before any task: memory/MEMORY.md
For active projects: memory/ai-personas.md

## Auto-Save Instruction:

At the end of long sessions, run:
python context-agent/scripts/context_manager.py save
```

## Context Guardian - Prevent Context Loss

The context-guardian skill monitors automatic compaction and saves snapshots.
Activate it at the start of long or critical sessions.

---

## 4. Hooks - Powerful Automation

Hooks run commands automatically on Claude Code events.

## Location Of Hooks

- Global: ~/.claude/settings.json
- Per project: .claude/settings.json (at the project root)

## Available Hook Types

| Hook | When It Fires |
|------|----------------|
| PreToolUse | Before any tool is used |
| PostToolUse | After any tool is used |
| Notification | When a system notification is received |
| Stop | When the agent stops responding |
| SubagentStop | When a sub-agent stops |

## Example: Beep-When-Done Hook

```json
{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "powershell -c \\"[Console]::Beep(800,300)\\""
          }
        ]
      }
    ]
  }
}
```

## Example: Bash Action Log Hook

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo dated-action >> ~/.claude/action_log.txt"
          }
        ]
      }
    ]
  }
}
```

## Example: Pre-Commit Security Scanner Hook

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python C:/Users/renat/skills/cred-omega/scripts/secret_scanner.py --staged 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}
```

## View And Validate Active Hooks

```bash
cat ~/.claude/settings.json
python -m json.tool ~/.claude/settings.json   # validates the JSON
```

---

## 5. Mcp Servers - Tool Extensions

MCP (Model Context Protocol) lets you add external tools to Claude Code.
Each MCP server exposes new tools that Claude can use in sessions.

## Mcp Commands

```bash
claude mcp add filesystem       # expanded file access
claude mcp add github           # GitHub integration (PRs, issues)
claude mcp add postgres         # SQL queries against a Postgres database
claude mcp add sqlite           # SQL queries against SQLite
claude mcp list                 # list installed MCPs
claude mcp get nome-servidor    # details of a specific MCP
claude mcp remove nome          # remove an MCP
```

## Most Useful Mcps

| MCP | Main Function |
|-----|------------------|
| filesystem | Expanded file access beyond the project |
| github | PRs, issues, commits, reviews via Claude |
| postgres / sqlite | Direct SQL queries without leaving Claude |
| puppeteer / playwright | Browser automation and web scraping |
| slack | Notifications and messages in channels |
| fetch | Direct HTTP requests to APIs |

## Create A Custom Mcp Server In Node.Js

```javascript
// mcp-server.js
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server({ name: "meu-mcp", version: "1.0.0" });
server.setRequestHandler("tools/call", async (req) => {
  if (req.params.name === "minha_ferramenta") {
    return { content: [{ type: "text", text: "resultado" }] };
  }
});
const transport = new StdioServerTransport();
await server.connect(transport);
```

## Add A Custom Mcp

```bash
claude mcp add meu-mcp node /caminho/para/mcp-server.js
```

---

## 6. Sub-Agents - Full Parallelism

Claude Code can create sub-agents via the Task tool for parallel work.
Each sub-agent runs independently with its own context.

## Orchestration Patterns

**Parallel spawn (multiple simultaneous tasks):**
Use the Task tool with run_in_background: true for each independent task.
Example with 3 agents in parallel:
- Agent 1: analyzes existing code
- Agent 2: researches documentation
- Agent 3: writes test cases
All run simultaneously. The result arrives via TaskOutput.

**Sub-agent types:**
- general-purpose: research, analysis, and general code
- Bash: terminal command execution only
- Explore: quick codebase exploration
- Plan: architecture and solution planning

**Isolation with git worktree:**
Use isolation: worktree so the sub-agent works on an isolated branch.
Ideal for: experiments, risky refactors, POCs with no risk to main.

## Best Practices With Sub-Agents

1. Always pass the FULL CONTEXT in the prompt (the sub-agent does not see the history)
2. Specify exactly where to save outputs (use absolute paths)
3. Use run_in_background: true for long tasks
4. Verify the result with TaskOutput after completion
5. Pass the project's CLAUDE.md in the sub-agent's initial context

---

## Configure Permissions Per Project (.Claude/Settings.Json)

```json
{
  "permissions": {
    "allow": [
      "Bash(git *)",
      "Bash(npm *)",
      "Read(*)",
      "Write(src/**)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(sudo *)",
      "Bash(curl * | bash)"
    ]
  }
}
```

## Command-Line Permission Flags

```bash
claude --dangerously-skip-permissions        # skips ALL confirmations
claude --allowed-tools "Read,Write,Bash"     # only these tools
claude --disallowed-tools "WebFetch"         # block specific ones
```

## When To Use --Dangerously-Skip-Permissions

Only in: controlled CI/CD, automated scripts, isolated sandboxes.
NEVER use in: production, repos with secrets, shared environments.

---

## Full Feature Workflow (4 Phases)

```bash

## Phase 1: Briefing And Planning

claude -p "analise a feature X e crie um plano detalhado de implementacao"

## Phase 2: Implementation

claude "implemente a feature X seguindo o plano gerado"

## Phase 3: Tests

claude "escreva testes completos para a feature X implementada"

## Phase 4: Code Review

claude "faca code review da feature X, identifique problemas e refine"
```

## Autonomous Mode For Long Cycles

```bash
claude --max-turns 100 "complete o ciclo completo de desenvolvimento da feature X"
```

## Productive Session Startup Script

```bash
#\!/bin/bash
echo "Carregando contexto do projeto..."
claude -p "leia memory/MEMORY.md e me da um briefing completo do estado atual"
```

## Ci/Cd Pipeline With Claude Code

```yaml

## .Github/Workflows/Claude-Review.Yml

- name: Claude Code Review
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
  run: |
    claude -p "revise o diff deste PR, identifique bugs e problemas de seguranca" \n      --output-format json \n      --no-stream \n      --max-turns 5
```

---

## Table Of Common Problems

| Problem | Likely Cause | Solution |
|----------|----------------|----------|
| API key not found | ANTHROPIC_API_KEY not configured | export ANTHROPIC_API_KEY=sk-ant-... |
| Timeout on long tasks | Insufficient max-turns | Add --max-turns 100 |
| Context window full | Too many files in context | Use sub-agents with focused context |
| Sub-agent can't find a file | Wrong relative path | Always use an absolute path |
| Hook does not run | Invalid JSON in settings.json | python -m json.tool ~/.claude/settings.json |
| MCP does not connect | MCP server not started | claude mcp list and check status |
| Unexpected compaction | Session too long | Use the context-guardian skill |
| Permission error in Bash | Tool not allowed | Add it to allow in settings.json |

## View Logs And Session History

```bash
ls ~/.claude/projects/
ls ~/.claude/projects/<hash>/
cat ~/.claude/projects/<hash>/*.jsonl | python -m json.tool
```

---

## Complete Recommended ~/.Claude/Settings.Json

```json
{
  "theme": "dark",
  "verbose": false,
  "cleanupPeriodDays": 30,
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "powershell -c \\"[Console]::Beep(800,200); Start-Sleep -Milliseconds 100; [Console]::Beep(1000,200)\\""
          }
        ]
      }
    ]
  },
  "permissions": {
    "allow": [
      "Bash(git *)",
      "Bash(npm *)",
      "Bash(python *)",
      "Bash(powershell *)",
      "Read(*)",
      "Write(*)"
    ]
  }
}
```

## Essential Environment Variables

```bash
export ANTHROPIC_API_KEY=sk-ant-SUA_CHAVE_AQUI
export CLAUDE_CODE_MAX_OUTPUT_TOKENS=8192
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1   # private mode
```

---

## How Claude Code Integrates With The Auri Skills

1. The global CLAUDE.md lists all available skills and when to use each one
2. agent-orchestrator runs on every request to identify relevant skills
3. task-intelligence enriches moderate/complex tasks with a pre-task briefing
4. context-agent saves and restores state between sessions
5. context-guardian prevents context loss in long sessions

## Quick Ecosystem Commands

```bash
python agent-orchestrator/scripts/scan_registry.py           # update the registry
python agent-orchestrator/scripts/match_skills.py "tarefa"  # identify skills
python task-intelligence/scripts/pre_task_check.py "tarefa" # briefing
python context-agent/scripts/context_manager.py save        # save context
python context-agent/scripts/context_manager.py load        # load context
```

## When This Skill Is Activated

This skill is activated automatically when the user wants to:
- Configure or optimize the Claude Code CLI
- Create, debug, or optimize hooks
- Add or configure MCP servers
- Create sub-agents and parallel orchestration
- Understand any Claude Code feature
- Resolve errors or unexpected CLI behavior
- Optimize CLAUDE.md and memory files
- Configure permissions and security

---

## 12. Slash Commands In Claude Code

| Command | Action |
|---------|------|
| /status | View the current session and context state |
| /clear | Clear the current conversation history |
| /compact | Compact the context (Claude summarizes the history) |
| /memory | View and edit memory files |
| /hooks | View configured and active hooks |
| /mcp | View connected MCPs and their status |
| /cost | View the session's cost in tokens and USD |
| /model | Switch the model in use (opus, sonnet, haiku) |
| /help | View all available commands and shortcuts |

---

## 13. Official References

- Main documentation: https://docs.anthropic.com/claude-code
- Hooks reference: https://docs.anthropic.com/claude-code/hooks
- Settings reference: https://docs.anthropic.com/claude-code/settings
- MCP SDK and examples: https://github.com/modelcontextprotocol/sdk
- Official repository: https://github.com/anthropics/claude-code
- Release notes: https://docs.anthropic.com/claude-code/changelog

## Best Practices

- Provide clear, specific context about your project and requirements
- Review all suggestions before applying them to production code
- Combine with other complementary skills for comprehensive analysis

## Common Pitfalls

- Using this skill for tasks outside its domain expertise
- Applying recommendations without understanding your specific context
- Not providing enough project context for accurate analysis

## Related Skills

- `007` - Complementary skill for enhanced analysis
- `matematico-tao` - Complementary skill for enhanced analysis
```