Acasă Explorează Ajutor
Autentificare
logic855
/
claude-mods
oglindă de https://github.com/0xDarkMatter/claude-mods.git
1
0
Bifurcare 0
Fisiere Probleme 0 Wiki
Ramură: main
Ramuri Etichete
claude-mods
/
skills
/
claude-code-ops
/
SKILL.md

SKILL.md 9.8 KB
Permalink Istoric Crud

name: claude-code-ops description: "Claude Code internals - hooks, skills, subagents, headless mode, and debugging, current as of June 2026. Use for: hooks, hook events, hook not firing, PreToolUse, PostToolUse, SessionStart, Stop hook, hook script, stdin JSON contract, tool validation, audit logging, skill frontmatter, SKILL.md, skill not loading, skill not triggering, disable-model-invocation, context fork, dynamic context injection, skill description budget, headless, claude -p, CLI automation, --print, output-format, stream-json, json-schema structured output, CI/CD scripting, bare mode, background agents, debug, troubleshoot, not working, agent not found, plugin not loading, claude plugin validate, /doctor, --safe-mode, MCP server not connecting, settings precedence, extension architecture, which extension type, agent vs skill vs command vs hook, where to put a skill, extension scope, plugin design, authoring an agent, writing a skill description." when_to_use: "Use for questions about Claude Code itself — e.g. 'my hook isn't firing', 'why won't this skill trigger', 'run claude headless in CI', 'plugin fails to validate', 'which settings file wins', 'should this be an agent or a skill', 'how do I design this extension'." license: MIT compatibility: "Claude Code CLI v2.1.x (June 2026 docs)" allowed-tools: "Bash Read Grep" metadata: author: claude-mods

related-skills: "mcp-ops, setperms, dsp-launch"

Claude Code Internals

One skill for the machinery of Claude Code itself: the hook system, the skill format, headless/programmatic use, and debugging your configuration. Replaces the former claude-code-hooks / claude-code-headless / claude-code-debug skills, refreshed against the June 2026 docs.

Written against Claude Code ~v2.1.17x. These surfaces move fast — when precision matters, confirm against the live docs (links per section). Two contracts from older guides are dead: the $TOOL_INPUT env-var hook contract (hooks read stdin JSON now) and standalone command files as a separate system (commands merged into skills).

Route to the Right Reference

You're doing Load
Writing/fixing a hook; event contracts; blocking tools; audit logging references/hooks-reference.md
Authoring a skill; frontmatter fields; $ARGUMENTS; !`cmd` injection; triggering problems references/skills-reference.md
claude -p; CI scripts; output parsing; stream-json; structured output; background agents references/headless-reference.md
Anything configured isn't taking effect; plugin validation; /doctor references/debugging-reference.md
Designing a new extension — which surface to build, where to scope it, how to author the description/prompt references/extension-architecture.md

Resources

Resource Use
scripts/validate-hooks-json.py Lint a hooks.json (or a settings.json "hooks" block) against the 30-event contract before trusting it
assets/hooks.json.template Starter hooks.json — one of each common pattern (PreToolUse Bash, PostToolUse Edit\|Write, SessionStart), ${CLAUDE_PLUGIN_ROOT}-rooted

Validate a hooks file (offline, structural — catches the unknown-event and matcher-as-array footguns the docs warn about):

# Lint this repo's own plugin hooks file (default target if no path given):
python skills/claude-code-ops/scripts/validate-hooks-json.py hooks/hooks.json
# → exit 0 clean, 10 findings (lists them), 4 malformed JSON, 3 not-found.
# Machine-readable for CI:
python skills/claude-code-ops/scripts/validate-hooks-json.py --json hooks/hooks.json | jq '.data[]'
# --strict makes portability warnings (unrooted command paths) count as findings.

Start a new hooks file from assets/hooks.json.template — copy it, strip the // comment lines (the live hooks.json must be strict JSON), then validate the result with the script above.

Mental Model

  • Skills = prompt content loaded on demand (descriptions always in context, body on invoke). Guidance, not guarantees.
  • Hooks = deterministic shell/HTTP/MCP/model handlers on lifecycle events. Guarantees: use hooks (or permissions) for "must never happen", skills/CLAUDE.md for "we do it this way".
  • Subagents = isolated context windows with their own system prompt, tools, model, permissions.
  • Headless = the same agent loop driven by claude -p (Agent SDK under the CLI).
  • Plugins = a directory bundling all of the above (skills/, agents/, hooks/hooks.json, .mcp.json), manifest at .claude-plugin/plugin.json.

Hooks in 30 Seconds

Configure under the "hooks" key in ~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json, plugin hooks/hooks.json, or skill/agent frontmatter:

{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/check.sh" }] }
    ]
  }
}

Contract: JSON payload on stdin → respond with exit code (0 ok, 2 block + stderr feedback) and optional stdout JSON (continue, systemMessage, hookSpecificOutput.permissionDecision/updatedInput/additionalContext/...).

Events (full catalog + per-event schemas in the reference): SessionStart, SessionEnd, Setup, UserPromptSubmit, UserPromptExpansion, PreToolUse, PermissionRequest, PermissionDenied, PostToolUse, PostToolUseFailure, PostToolBatch, Stop, StopFailure, SubagentStart, SubagentStop, TaskCreated, TaskCompleted, TeammateIdle, Notification, MessageDisplay, ConfigChange, CwdChanged, FileChanged, PreCompact, PostCompact, InstructionsLoaded, WorktreeCreate, WorktreeRemove, Elicitation, ElicitationResult.

Hook types: command (sync/async/asyncRewake), http, mcp_tool, prompt, agent. Matchers are case-sensitive strings ("Edit|Write", regex allowed); if filters add permission-rule conditions like Bash(git *).

Skills in 30 Seconds

.claude/skills/<name>/SKILL.md (project) or ~/.claude/skills/<name>/SKILL.md (personal). Frontmatter fields beyond name/description: when_to_use, argument-hint, arguments, disable-model-invocation, user-invocable, allowed-tools, disallowed-tools, model, effort, context: fork + agent, hooks, paths, shell.

  • Substitutions: $ARGUMENTS, $ARGUMENTS[N], $N (0-based!), $name, ${CLAUDE_SKILL_DIR}, ${CLAUDE_SESSION_ID}, ${CLAUDE_EFFORT}.
  • !`command` runs at load time and inlines output (dynamic context injection).
  • Body persists all session; keep SKILL.md < 500 lines, details in supporting files.
  • Description + when_to_use capped at 1,536 chars in the listing; listing budget = 1% of context window — /doctor reports overflow.

Headless in 30 Seconds

claude --bare -p "query" --allowedTools "Read,Grep" --output-format json | jq -r '.result'
  • --bare for reproducible CI runs (skips hooks/skills/plugins/MCP/CLAUDE.md; auth via ANTHROPIC_API_KEY or claude setup-token).
  • --output-format json → .result, .session_id, .is_error, .total_cost_usd, .num_turns; add --json-schema '<schema>' → .structured_output.
  • stream-json (+ --verbose --include-partial-messages) for token streaming; system/init event lists loaded plugins/plugin_errors (assert in CI).
  • Multi-turn: --continue, --resume <id|name>, --fork-session; caps: --max-turns, --max-budget-usd.
  • Fire-and-forget: claude --bg "task", then claude agents --json / logs / attach / stop.

Debugging Decision Tree

Something configured isn't working
├─ What loaded? /context → then /memory /skills /agents /hooks /mcp /permissions
├─ Config valid? /doctor (invalid keys, schema errors, skill budget overflow)
├─ Which scope won? /status  (managed > local > project > user; flags/env on top)
├─ Watch it live: claude --debug hooks | --debug mcp | --debug "api,hooks"
└─ Bisect: claude --safe-mode (customizations off)
   └─ still broken → CLAUDE_CONFIG_DIR=/tmp/clean claude  (nothing loads)

Fast classics: hooks belong in settings.json not ~/.claude.json; matcher is a case-sensitive string, not an array; skills need a folder + SKILL.md; .mcp.json at repo root; settings.local.json overrides settings.json; agent files on disk load at session start; claude plugin validate --strict in CI.

Subagents (quick facts)

Markdown + YAML frontmatter in .claude/agents/ / ~/.claude/agents/ / plugin agents/ / --agents '<json>'. Required: name (the identity — filename doesn't matter), description. Optional: tools, disallowedTools, model (default inherit), permissionMode, maxTurns, skills (preloads full skill content), mcpServers, hooks, memory (user|project|local), background, effort, isolation: worktree, color, initialPrompt. Plugin agents ignore hooks/mcpServers/permissionMode. Built-in Explore/Plan skip CLAUDE.md. The Task tool was renamed Agent (v2.1.63; Task(...) rules still alias).

Official Docs (verify here when it matters)