claude-code-skill

Claude Code — Repository Skill

Project Overview

Claude Code is Anthropic's CLI tool for interacting with Claude from the terminal. It supports file editing, shell commands, git workflows, code review, multi-agent coordination, IDE integration (VS Code, JetBrains), and Model Context Protocol (MCP).

Codebase: ~1,900 files, 512,000+ lines of TypeScript under src/.

Tech Stack

| Component | Technology |

|------------------|------------------------------------------------|

| Language | TypeScript (strict mode, ES modules) |

| Runtime | Bun (JSX support, bun:bundle feature flags) |

| Terminal UI | React + Ink (React for CLI) |

| CLI Parser | Commander.js (@commander-js/extra-typings) |

| API Client | @anthropic-ai/sdk |

| Validation | Zod v4 |

| Linter/Formatter | Biome |

| Analytics | GrowthBook (feature flags & A/B testing) |

| Protocol | Model Context Protocol (MCP) |

Architecture

Directory Map (src/)

| Directory | Purpose |

|------------------|-----------------------------------------------------------------|

| commands/ | ~50 slash commands (/commit, /review, /config, etc.) |

| tools/ | ~40 agent tools (Bash, FileRead, FileWrite, Glob, Grep, etc.) |

| components/ | ~140 Ink/React UI components for terminal rendering |

| services/ | External integrations (API, OAuth, MCP, LSP, analytics, plugins)|

| bridge/ | Bidirectional IDE communication layer |

| state/ | React context + custom store (AppState) |

| hooks/ | React hooks (permissions, keybindings, commands, settings) |

| types/ | TypeScript type definitions |

| utils/ | Utilities (shell, file ops, permissions, config, git) |

| screens/ | Full-screen UIs (Doctor, REPL, Resume, Compact) |

| skills/ | Bundled skills + skill loader system |

| plugins/ | Plugin system (marketplace + bundled plugins) |

| coordinator/ | Multi-agent coordination & supervisor logic |

| tasks/ | Task management (shell tasks, agent tasks, teammates) |

| context/ | React context providers (notifications, stats, FPS) |

| memdir/ | Persistent memory system (CLAUDE.md, user/project memory) |

| entrypoints/ | Initialization logic, Agent SDK, MCP entry |

| voice/ | Voice input/output (STT, keyterms) |

| vim/ | Vim mode keybinding support |

| schemas/ | Zod configuration schemas |

| keybindings/ | Keybinding configuration & resolver |

| migrations/ | Config migrations between versions |

| outputStyles/ | Output formatting & theming |

| query/ | Query pipeline & processing |

| server/ | Server/daemon mode |

| remote/ | Remote session handling |

Key Files

| File | Role |

|---------------------|-----------------------------------------------------|

| src/main.tsx | CLI entry point (Commander parser, startup profiling)|

| src/QueryEngine.ts| Core LLM API caller (streaming, tool-call loops) |

| src/Tool.ts | Tool type definitions & buildTool factory |

| src/tools.ts | Tool registry & presets |

| src/commands.ts | Command registry |

| src/context.ts | System/user context collection (git status, memory) |

| src/cost-tracker.ts| Token cost tracking |

Entry Points & Initialization Sequence

1. src/main.tsx — Commander CLI parser, startup profiling
2. src/entrypoints/init.ts — Config, telemetry, OAuth, MDM
3. src/entrypoints/cli.tsx — CLI session orchestration
4. src/entrypoints/mcp.ts — MCP server mode
5. src/entrypoints/sdk/ — Agent SDK (programmatic API)
6. src/replLauncher.tsx — REPL session launcher

Startup performs parallel initialization: MDM policy reads, Keychain prefetch, feature flag checks, then core init.

Patterns & Conventions

Tool Definition

Each tool lives in src/tools/{ToolName}/ and uses buildTool:

export const MyTool = buildTool({
  name: 'MyTool',
  aliases: ['my_tool'],
  description: 'What this tool does',
  inputSchema: z.object({
    param: z.string(),
  }),
  async call(args, context, canUseTool, parentMessage, onProgress) {
    // Execute and return { data: result, newMessages?: [...] }
  },
  async checkPermissions(input, context) { /* Permission checks */ },
  isConcurrencySafe(input) { /* Can run in parallel? */ },
  isReadOnly(input) { /* Non-destructive? */ },
  prompt(options) { /* System prompt injection */ },
  renderToolUseMessage(input, options) { /* UI for invocation */ },
  renderToolResultMessage(content, progressMessages, options) { /* UI for result */ },
})

Directory structure per tool: {ToolName}.ts or .tsx (main), UI.tsx (rendering), prompt.ts (system prompt), plus utility files.

Command Definition

Commands live in src/commands/ and follow three types:

• PromptCommand — Sends a formatted prompt with injected tools (most commands)
• LocalCommand — Runs in-process, returns text
• LocalJSXCommand — Runs in-process, returns React JSX

const command = {
  type: 'prompt',
  name: 'my-command',
  description: 'What this command does',
  progressMessage: 'working...',
  allowedTools: ['Bash(git *)', 'FileRead(*)'],
  source: 'builtin',
  async getPromptForCommand(args, context) {
    return [{ type: 'text', text: '...' }]
  },
} satisfies Command

Commands are registered in src/commands.ts and invoked via /command-name in the REPL.

Component Structure

• Functional React components with Ink primitives (Box, Text, useInput())
• Styled with Chalk for terminal colors
• React Compiler for optimized re-renders
• Design system primitives in src/components/design-system/

State Management

• AppState via React context + custom store (src/state/AppStateStore.ts)
• Mutable state object passed to tool contexts
• Selector functions for derived state
• Change observers in src/state/onChangeAppState.ts

Permission System

• Modes: default (prompt per operation), plan (show plan, ask once), bypassPermissions (auto-approve), auto (ML classifier)
• Rules: Wildcard patterns — Bash(git ), FileEdit(/src/)
• Tools implement checkPermissions() returning { granted: boolean, reason?, prompt? }

Feature Flags & Build

Bun's bun:bundle feature flags enable dead-code elimination at build time:

import { feature } from 'bun:bundle'
if (feature('PROACTIVE')) { /* proactive agent tools */ }

Notable flags: PROACTIVE, KAIROS, BRIDGE_MODE, VOICE_MODE, COORDINATOR_MODE, DAEMON, WORKFLOW_SCRIPTS.

Some features are also gated via process.env.USER_TYPE === 'ant'.

Naming Conventions

| Element | Convention | Example |

|-------------|---------------------|----------------------------------|

| Files | PascalCase (exports) or kebab-case (commands) | BashTool.tsx, commit-push-pr.ts |

| Components | PascalCase | App.tsx, PromptInput.tsx |

| Types | PascalCase, suffix with Props/State/Context | ToolUseContext |

| Hooks | use prefix | useCanUseTool, useSettings |

| Constants | SCREAMING_SNAKE_CASE | MAX_TOKENS, DEFAULT_TIMEOUT_MS|

Import Practices

• ES modules with .js extensions (Bun convention)
• Lazy imports for circular dependency breaking: const getModule = () => require('./heavy.js')
• Conditional imports via feature flags or process.env
• biome-ignore markers for manual import ordering where needed

Services

| Service | Path | Purpose |

|--------------------|-------------------------------|-----------------------------------|

| API | services/api/ | Anthropic SDK client, file uploads|

| MCP | services/mcp/ | MCP client, tool/resource discovery|

| OAuth | services/oauth/ | OAuth 2.0 auth flow |

| LSP | services/lsp/ | Language Server Protocol manager |

| Analytics | services/analytics/ | GrowthBook, telemetry, events |

| Plugins | services/plugins/ | Plugin loader, marketplace |

| Compact | services/compact/ | Context compression |

| Policy Limits | services/policyLimits/ | Org rate limits, quota checking |

| Remote Settings | services/remoteManagedSettings/ | Managed settings sync (Enterprise) |

| Token Estimation | services/tokenEstimation.ts | Token count estimation |

Configuration

Settings locations:

• Global: ~/.claude/config.json, ~/.claude/settings.json
• Project: .claude/config.json, .claude/settings.json
• System: macOS Keychain + MDM, Windows Registry + MDM
• Managed: Remote sync for Enterprise users

Guidelines

1. Read relevant source files before making changes — understand existing patterns first.
2. Follow the tool/command/component patterns above when adding new ones.
3. Keep edits minimal and focused — avoid unnecessary refactoring.
4. Use Zod for all input validation at system boundaries.
5. Gate experimental features behind bun:bundle feature flags or env checks.
6. Respect the permission system — tools that modify state must implement checkPermissions().
7. Use lazy imports when adding dependencies that could create circular references.
8. Update this file as project conventions evolve.