Claude Code Automation

Map of automation surfaces in Claude Code and which one to reach for. Internal-only — relies on what the user already has installed.

Decision matrix — which surface to use

Need	Surface	Lives in
Run shell command on every tool event	Hook	settings.json hooks:
Encapsulate domain knowledge + workflow	Skill	.claude/skills/<name>/SKILL.md
Deterministic multi-step flow the user invokes	Slash command	.claude/commands/<name>.md
Isolated worker spawned from main agent	Sub-agent	.claude/agents/<name>.md
Coordinated multi-agent pattern	Agent team	.claude/agent-teams/<name>.yaml
External tool surface (APIs, CLIs)	MCP server	.mcp.json or settings.json mcpServers:
Package the above for reuse	Plugin	plugins/<name>/.claude-plugin/plugin.json
Runs on a cron	Scheduled task (Desktop) or Routine (CLI)	Desktop MCP scheduled-tasks / ~/.claude/routines/
Non-interactive CI run	Headless mode	claude -p "..." --output-format stream-json
Programmatic embed	Agent SDK	@anthropic-ai/claude-agent-sdk (TS) or claude-agent-sdk (Python)
Structured cross-session chat	Channel	channels.json + channels-reference
Rich in-CLI UI	Fullscreen mode	claude --fullscreen or TUI extensions

Hooks — the three lifecycle events that matter most

• PreToolUse — veto or mutate a tool call. {"decision":"block","reason":"..."} blocks.
• PostToolUse — react to tool results (auto-format, audit logs).
• Stop / SubagentStop — cleanup when work concludes.

{
  "hooks": {
    "PreToolUse": [{
      "matcher": {"tool_name": "Bash"},
      "command": "bash .claude/hooks/protect-sensitive-files.sh"
    }]
  }
}

Skills vs commands vs sub-agents

• Skills are knowledge + procedure — auto-invoked by description match. Use for domain expertise.
• Commands are deterministic invokable flows — user types /name. Use for repeatable operations.
• Sub-agents are isolated workers — spawn for parallelism or to protect context window.

MCP — internal pattern

Prefer MCP tools over shell wrappers when available. Check tool surface first:

# From this session
mcp__harness__*           # Harness platform ops
mcp__kubernetes__*        # K8s resources
mcp__9c1c57f5_..._atlassian__*    # Jira + Confluence
mcp__384a610f_..._*       # M365: Outlook, SharePoint, Teams
mcp__MCP_DOCKER__azure_*  # Azure services
mcp__scheduled-tasks__*   # Desktop scheduled tasks

Plugins — what to bundle

A plugin is one coherent outcome: a marketplace item a user can install and get value from. Bundle:

• .claude-plugin/plugin.json — metadata.
• skills/ — auto-invoked knowledge.
• commands/ — user-invoked flows.
• agents/ — specialized workers.
• hooks/ — lifecycle scripts.
• rules/ — always-loaded instructions.
• README.md — what it does + install.

Register in marketplace: edit <marketplace>/.claude-plugin/marketplace.json, add a plugins[] entry.

Scheduled tasks (Desktop)

mcp__scheduled-tasks__create_scheduled_task
  name: "harness-daily-health"
  cron: "0 9 * * *"
  prompt: "Run /wa-pipeline status for all thelobbi pipelines and post to Slack"

Headless mode — CI pattern

claude -p "run /wa-report for work-unit-14" \
  --output-format stream-json \
  --allowed-tools "Read,Bash" \
  --max-turns 10

Use in Harness CI steps where Claude runs a specific flow without TTY.

Permissions — the four-mode model

Mode	When
default	Interactive — user approves novel calls
acceptEdits	File edits pre-approved, tools still ask
plan	Read-only — for analysis
bypassPermissions	CI / trusted automation only

Set in settings.json permissions.mode or per-invocation --permission-mode.

Memory (memory/ + MEMORY.md)

• MEMORY.md is the always-loaded index. ≤150 chars per entry, one line.
• Entries written to memory/<name>.md with frontmatter (type: user | feedback | project | reference).
• Never write memory content into MEMORY.md directly.

Checkpointing

File checkpointing preserves state across sessions. Enable via settings.json "checkpointing": { "enabled": true }. Use for long-running analyses that must survive restarts.

Common automation recipes

1. Auto-format on edit — PostToolUse hook on Edit/Write + per-language formatter.
2. Protect secrets — PreToolUse hook on Bash matching .env|*.pem|*.pfx|*.key patterns.
3. CI gatekeeper — headless Claude + --allowed-tools whitelist + stream-json output parsed by pipeline.
4. Daily report — scheduled task runs /wa-report + posts to Slack/Teams via MCP.
5. Work-unit close — SubagentStop hook emits audit event + triggers report generation.

Related

• skills/harness-automation — CI/CD side.
• skills/work-unit-protocol — the reporting contract this automates toward.
• rules/ultra-mode.md — constraints every automation respects.