# Xobotyi Cc Foundry Claude Code Sdk

> Claude Code SDK

- Skill: `tomevault-io/xobotyi-cc-foundry-claude-code-sdk` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/xobotyi-cc-foundry-claude-code-sdk`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/xobotyi-cc-foundry-claude-code-sdk/raw
- Safety review: pending (external: skill-scanner PASS, skillspector WARNING)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/xobotyi-cc-foundry-claude-code-sdk

---


# Claude Code SDK

Authoritative reference for Claude Code extensibility and configuration. Use this skill when building, configuring, or
debugging any Claude Code extension mechanism.

## References

- **Skills** — [`${CLAUDE_SKILL_DIR}/references/skills.md`] Frontmatter fields, invocation control matrix, string
  substitutions, dynamic context injection, subagent execution, nested discovery, sharing
- **Subagents** — [`${CLAUDE_SKILL_DIR}/references/subagents.md`] Built-in agents table, frontmatter fields, permission
  modes, tool control, preloading skills, persistent memory, worktree isolation, CLI-defined agents, @-mention
  invocation, --agent session mode, MCP scoping, effort/background fields, teams
- **Plugins** — [`${CLAUDE_SKILL_DIR}/references/plugins.md`] Plugin manifest schema, component paths,
  CLAUDE_PLUGIN_DATA persistent directory, marketplace schema, official marketplace, LSP server configs, caching,
  validation, CLI commands
- **Hooks** — [`${CLAUDE_SKILL_DIR}/references/hooks.md`] All 22 event details (input fields, output schemas, exit code
  behavior), matcher patterns, hook types (command/http/prompt/agent), async hooks, decision control patterns, security
- **MCP** — [`${CLAUDE_SKILL_DIR}/references/mcp.md`] Server installation (HTTP/SSE/stdio), scopes, OAuth
  authentication, environment variable expansion, managed MCP config, tool search, plugin-provided servers
- **Memory** — [`${CLAUDE_SKILL_DIR}/references/memory.md`] CLAUDE.md hierarchy and loading, @import syntax, auto memory
  (storage, /memory command, settings), path-specific rules with globs, claudeMdExcludes, organization-level management
- **Model config** — [`${CLAUDE_SKILL_DIR}/references/model-config.md`] Model aliases (including opus[1m]/sonnet[1m]),
  effort levels (low/medium/high/max), extended context (1M), opusplan mode, availableModels/modelOverrides, custom
  model option, third-party provider pinning, prompt caching env vars
- **Output styles** — [`${CLAUDE_SKILL_DIR}/references/output-styles.md`] Built-in styles, frontmatter fields,
  keep-coding-instructions flag, comparison with CLAUDE.md/agents/skills
- **Settings** — [`${CLAUDE_SKILL_DIR}/references/settings.md`] Scope hierarchy, permission rule syntax, sandbox config,
  worktree settings, attribution settings, common settings table (50+ keys), hook configuration controls, file
  suggestion settings, environment variables
- **Status line** — [`${CLAUDE_SKILL_DIR}/references/statusline.md`] Configuration, JSON input schema with all fields,
  ANSI colors, clickable links, caching, plugin delivery
- **Best practices** — [`${CLAUDE_SKILL_DIR}/references/best-practices.md`] Context management, verification patterns,
  explore-plan-code workflow, CLAUDE.md authoring, session management, automation/scaling

Read the relevant reference before making detailed changes. The rules below cover the decision framework; references
provide field-level schemas and implementation details.

## Concepts

<concepts>
**Skill** — Prompt template in `SKILL.md` that extends Claude's capabilities. Loaded on-demand when description matches
user request. Can include `references/` for detailed content. Invoked with `/skill-name` or automatically. Frontmatter
controls invocation, tool access, model, effort level, execution context (`fork` for subagent), and scoped hooks.

**Plugin** — Distributable package containing skills, agents, hooks, MCP servers, LSP servers, output styles, and
default settings. Has optional `.claude-plugin/plugin.json` manifest. Installed from marketplace or local path. Skills
namespaced as `/plugin:skill`. Two path variables: `${CLAUDE_PLUGIN_ROOT}` (install dir, changes on update) and
`${CLAUDE_PLUGIN_DATA}` (persistent data dir, survives updates).

**Hook** — Deterministic automation triggered at 22 lifecycle events (tool use, session start/end, permission request,
subagent lifecycle, teammate/task events, compaction, worktree, elicitation, instructions loading). Four types: command
(shell), http (POST to URL), prompt (LLM decision), agent (multi-turn verification). Configured in settings, plugin, or
skill/agent frontmatter.

**MCP Server** — External tool/resource provider via Model Context Protocol. Connects Claude to databases, APIs,
services. Supports stdio, HTTP, SSE transports and OAuth authentication. Configured per-project, per-user, via plugin,
or scoped to a specific subagent via inline definition.

**Output Style** — Persona/behavior modifier via system prompt changes. Affects how Claude responds without changing
capabilities. Built-in: Default, Explanatory, Learning. Custom styles exclude coding instructions unless
`keep-coding-instructions: true`.

**CLAUDE.md** — Project memory file providing persistent context about codebase, conventions, instructions. Hierarchy:
managed > user > project. Loaded automatically at session start. Supports `@path` imports (max depth 5). Modular rules
in `.claude/rules/*.md` with optional `paths:` frontmatter for file-scoped loading. Auto memory (`MEMORY.md`) stores
Claude's own learnings per project (first 200 lines loaded each session).

**Subagent** — Isolated context for delegated tasks. Built-in types: Explore (haiku, read-only), Plan (inherited model,
read-only), general-purpose (inherited model, all tools). Custom agents in `.claude/agents/`. Supports persistent
memory, worktree isolation, effort override, background execution, scoped MCP servers, and tool restrictions via `tools`
or `disallowedTools`. Invocable via delegation, @-mention, or `--agent` flag (session-wide). Subagents cannot spawn
other subagents. Agent teams coordinate multiple agents across separate sessions.

**Settings** — Configuration hierarchy controlling permissions, model, hooks, behavior, sandbox, plugins, and more.
Scopes: managed > CLI args > local > project > user. Managed settings support server-managed, MDM/plist/registry, and
file-based delivery.

</concepts>

## Choosing the Right Extension Mechanism

Use these rules when deciding how to extend Claude Code. Each mechanism serves a different purpose; choosing wrong
causes friction or failure.

### Skills vs Subagents vs Hooks vs MCP vs CLAUDE.md

- **Use CLAUDE.md** for persistent project context that applies to every session: coding conventions, repo structure,
  build commands, team practices. It loads automatically — no invocation needed. Keep it concise; bloated CLAUDE.md
  causes instruction drift.

- **Use skills** for reusable domain expertise or workflows that load on-demand. Skills load only when relevant, keeping
  context clean when not needed. Two content patterns:
  - **Reference content** — knowledge Claude applies alongside conversation (conventions, patterns, style guides). Runs
    inline, auto-triggered.
  - **Task content** — step-by-step actions (deploy, commit, generate). Runs in subagent (`context: fork`), manual
    invocation (`disable-model-invocation: true`).

- **Use subagents** for isolated delegated work with tool restrictions or when output is verbose and should not consume
  main context. Custom agents in `.claude/agents/` get their own system prompt, tool set, and permissions. Subagents
  cannot spawn other subagents.

- **Use hooks** for deterministic automation that must always happen — formatting after edits, blocking writes to
  protected paths, injecting context at session start. Unlike CLAUDE.md instructions (advisory), hooks are guaranteed to
  run.

- **Use MCP servers** for connecting to external services: databases, APIs, issue trackers. MCP is the integration layer
  — use it when Claude needs tools or resources from outside the local environment.

- **Use output styles** when you need to change how Claude communicates (tone, format, persona) without changing its
  capabilities. Styles modify the system prompt and are always active once selected.

- **Use plugins** to package and distribute any combination of the above as a single installable unit.

### Skill Content Design

When creating a skill, the content pattern determines frontmatter:

- **Reference content** (conventions, patterns) — `context`: inline, `disable-model-invocation`: `false`. Trigger: auto
  or manual.
- **Task content** (deploy, generate, commit) — `context`: `fork`, `disable-model-invocation`: `true`. Trigger: manual
  only.

Reference content runs inline so Claude uses it alongside conversation context. Task content runs in a subagent — the
skill content becomes the subagent's prompt, and it has no access to conversation history.

### Skill Invocation Control

- **(default)** — user: yes, Claude: yes. Description always loaded; full skill when invoked.
- **`disable-model-invocation: true`** — user: yes, Claude: no. Neither description nor full skill loaded.
- **`user-invocable: false`** — user: no, Claude: yes. Description always loaded; full skill when invoked.

`user-invocable: false` hides from `/` menu but does not block the Skill tool. To block programmatic invocation
entirely, use `disable-model-invocation: true`.

Skill descriptions have a character budget: 2% of context window (fallback 16,000 chars). Run `/context` to check for
excluded skills.

### Subagent Selection

- **Read-only codebase exploration** — built-in `Explore` agent (haiku)
- **Plan mode research** — built-in `Plan` agent (inherited model)
- **Complex multi-step task with tools** — built-in `general-purpose` agent
- **Specialized role with custom system prompt** — custom agent in `.claude/agents/`
- **Skill that runs in isolation** — skill with `context: fork` + `agent` field
- **Session-wide agent mode** — `claude --agent <name>` or `agent` setting in `.claude/settings.json`

Skills with `context: fork` write the task in the skill and pick an agent type. Custom subagents get their own system
prompt and load skills as reference content. Use custom subagents when the agent needs a persistent identity, tool
restrictions, or persistent memory across sessions.

Invocation methods: automatic delegation (Claude decides), @-mention (guarantees specific agent), `--agent` flag
(session-wide). Restrict which agents can be spawned with `Agent(type1, type2)` in `tools` or deny with `Agent(name)` in
`permissions.deny`.

### Hook Type Selection

- **`command`** — deterministic check (lint, validate, format). Timeout: 600s. Supports `async: true` for background.
- **`http`** — POST event JSON to a URL. Non-2xx = non-blocking error. Block via 2xx + JSON decision body. Supports
  header env var interpolation with `allowedEnvVars`.
- **`prompt`** — LLM judgment on hook input data alone. Timeout: 30s. Returns `{ok, reason}` JSON.
- **`agent`** — LLM judgment that needs file inspection or commands. Timeout: 60s. Same response schema as prompt.

Command hooks are the default. Use http hooks for external service integration. Use prompt hooks when the decision
requires understanding intent (not just pattern matching). Use agent hooks when verification requires reading files or
running commands. Not all events support all types — prompt/agent hooks are limited to 8 events (PreToolUse,
PostToolUse, PostToolUseFailure, PermissionRequest, UserPromptSubmit, Stop, SubagentStop, TaskCompleted).

All matching hooks run in parallel (identical handlers deduplicated). Exit code 2 blocks the operation (for blocking
events).

### Settings Scope Selection

- **Organization policy (cannot override)** — Managed scope. Location: system paths
- **Personal preferences across projects** — User scope. Location: `~/.claude/settings.json`
- **Team-shared project config** — Project scope. Location: `.claude/settings.json`
- **Personal project-specific config** — Local scope. Location: `.claude/settings.local.json`

Precedence: managed > CLI args > local > project > user. Permission evaluation order: deny > ask > allow (first match
wins).

## Quick Reference

### Skill Locations

- **Enterprise** — managed settings
- **Personal** — `~/.claude/skills/<name>/SKILL.md`
- **Project** — `.claude/skills/<name>/SKILL.md`
- **Plugin** — `<plugin>/skills/<name>/SKILL.md`

### Plugin Layout

```
plugin-name/
├── .claude-plugin/
│   └── plugin.json        # Manifest (optional)
├── skills/
│   └── skill-name/
│       ├── SKILL.md
│       └── references/
├── agents/                # Custom subagents
├── hooks/
│   └── hooks.json
├── output-styles/
├── settings.json            # Default settings (agent key only)
├── .mcp.json
├── .lsp.json
└── README.md
```

### Hook Events (22)

- `SessionStart` — session begins/resumes. Cannot block. Command only.
- `InstructionsLoaded` — CLAUDE.md or rules file loaded into context. Cannot block. Command only.
- `UserPromptSubmit` — before prompt processing. Can block.
- `PreToolUse` — before tool executes. Can block. Supports `updatedInput`.
- `PermissionRequest` — permission dialog shown. Can block. Supports `updatedPermissions`.
- `PostToolUse` — after tool success. Cannot block (but `decision: "block"` feeds reason to Claude).
- `PostToolUseFailure` — after tool failure. Cannot block.
- `Notification` — notification sent. Cannot block. Command only.
- `SubagentStart` — subagent spawned. Cannot block. Command only.
- `SubagentStop` — subagent finishes. Can block.
- `Stop` — Claude finishes responding. Can block.
- `StopFailure` — turn ended due to API error. Cannot block. Output ignored. Command only.
- `TeammateIdle` — teammate going idle. Can block.
- `TaskCompleted` — task marked complete. Can block.
- `ConfigChange` — config file changes. Can block (except `policy_settings`).
- `WorktreeCreate` — worktree being created. Replaces default git behavior. Must print path. Command only.
- `WorktreeRemove` — worktree being removed. Cannot block. Command only.
- `PreCompact` — before compaction. Cannot block. Command only.
- `PostCompact` — after compaction completes. Cannot block. Command only.
- `Elicitation` — MCP server requests user input. Can block. Command only.
- `ElicitationResult` — after user responds to MCP elicitation. Can block. Command only.
- `SessionEnd` — session terminates. Cannot block. Command only. Timeout: 1.5s default.

### Settings Scopes

- **Managed** — system path. Shared org-wide.
- **User** — `~/.claude/settings.json`. Not shared.
- **Project** — `.claude/settings.json`. Shared via Git.
- **Local** — `.claude/settings.local.json`. Not shared.

### Memory Hierarchy

- **Managed policy** — system paths. Shared org-wide. Cannot be excluded.
- **User instructions** — `~/.claude/CLAUDE.md`. Personal, all projects.
- **User rules** — `~/.claude/rules/*.md`. Personal, all projects.
- **Project instructions** — `./CLAUDE.md` or `.claude/CLAUDE.md`. Team via VCS.
- **Project rules** — `.claude/rules/*.md`. Team via VCS. Supports `paths:` frontmatter for file-scoped loading.
- **Auto memory** — `~/.claude/projects/<project>/memory/`. Personal, per project. First 200 lines of `MEMORY.md` loaded
  each session.

More specific memory takes precedence. CLAUDE.md in parent directories loads automatically; child directories load on
demand when working in those paths. Use `@path` in CLAUDE.md to import files (max depth 5). Use `claudeMdExcludes` in
settings to skip irrelevant CLAUDE.md files in monorepos.

## Related Skills

This skill provides the SDK reference (what exists, how it works). The engineering skills provide design guidance (how
to build it well):

- `prompt-engineering` — instruction design techniques for any AI artifact
- `skill-engineering` — SKILL.md design, description formulas, content architecture
- `subagent-engineering` — agent prompt design, tool scoping, team coordination
- `output-style-engineering` — persona definition, tone examples, behavioral rules

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/xobotyi) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->