claude-skill

What this skill does

# Claude Code Agent Skill

Operate Claude Code as a **managed coding agent** — from worktree setup through PR merge.

## Prerequisites

```bash
claude --version  # Verify installed
# Install: npm install -g @anthropic-ai/claude-code
tmux -V             # tmux required for full workflow
```

## CLI Quick Reference

| Flag | Effect |
|------|--------|
| `-p "prompt"` | Non-interactive one-shot, exits when done |
| `--dangerously-skip-permissions` | Skip all permission prompts (safe in containers/VMs) |
| `--permission-mode acceptEdits` | Auto-accept file edits, still prompt for shell commands |
| `--permission-mode plan` | Read-only analysis, no modifications |
| `--model <model>` | Model selection (e.g. `claude-sonnet-4-6`) |
| `--allowedTools "Bash,Read,Write,Edit"` | Restrict available tools |
| `--disallowedTools "Bash,Write"` | Block specific tools |
| `--append-system-prompt "..."` | Add custom instructions to system prompt |
| `--output-format json` | Structured JSON output with cost/duration metadata |
| `--output-format stream-json` | Streaming JSON (each message as it arrives) |
| `--continue` / `-c` | Continue most recent conversation |
| `--resume <id>` / `-r <id>` | Resume specific session by ID |
| `--mcp-config <file>` | Load MCP server configuration |
| `--verbose` | Enable verbose debug logging |

---

## Execution Modes

### Quick Mode — Small Tasks

For trivial fixes, one-file changes, or analysis. Use `-p` (non-interactive).

**Output capture:** Always redirect output to a log file so it's readable regardless
of PTY availability. Use `--output-format stream-json` for structured, parseable
progress events (each message arrives as a separate JSON line).

```bash
LOG_FILE="/tmp/claude-quick-${TASK_ID:-$$}.log"

# Via OpenClaw exec — use background=true + pty=true, NO hard timeout
# pty=true ensures claude CLI flushes output properly (no buffering issues)
# (hard timeout kills the process; instead we poll and extend)
# Redirect both stdout and stderr to log file via tee so output is always captured.
# In -p mode (non-interactive), | tee is safe — no TTY detection issues.
exec(command="claude -p 'fix the typo in README.md' --dangerously-skip-permissions --output-format stream-json 2>&1 | tee -a $LOG_FILE",
     workdir="/path/to/project", background=true, pty=true)
```

**PTY fallback:** If `pty=true` is unavailable (some containers, CI runners), the
command still works because `-p` mode is non-interactive — it doesn't rely on
`isatty(stdout)`. The `2>&1 | tee` ensures both stdout and stderr are captured
to the log file regardless of PTY status. Without PTY, you lose color output
but all content is preserved.

#### Adaptive Timeout (Poll-and-Extend)

**Do NOT use `timeout=` for claude tasks.** Instead, use background execution
with periodic polling. This prevents premature kills on long-running tasks:

1. Launch with `background=true` (no `timeout`)
2. Poll every ~5 min with `process(action="poll", sessionId=<id>, timeout=300000)`
3. If process is still running → check log file for new output
4. If process exited → check exit code and log file, done
5. Safety net: if no new output for 12 hours, ask user before killing
6. Safety net: if output is repeating (loop detection), ask user

**Persistent polling state:** Store polling metadata in the task registry so a
restarted orchestrator agent can resume monitoring without losing state:

```
Registry fields for Quick Mode tasks:
  "lastOutputHash": "<sha256 of last 20 lines>",
  "lastCheckedAt": <unix timestamp>,
  "silentRounds": <int>,
  "repeatingRounds": <int>
```

```
Poll loop (agent behavior, not a script):

  poll_interval = 5 min (300000 ms)
  max_silent_rounds = 144  (= 12 hours with no new output → ask user)
  max_repeating_rounds = 12 (= 1 hour of identical output → likely stuck)

  # Restore state from registry if resuming after agent restart
  silent_rounds = registry[task_id].silentRounds ?? 0
  repeating_rounds = registry[task_id].repeatingRounds ?? 0
  last_output_hash = registry[task_id].lastOutputHash ?? ""

  repeat:
    result = process(action="poll", sessionId=<id>, timeout=300000)
    if result.completed:
      → check exit code, read $LOG_FILE, report result
      → break
    else:
      # Read latest output directly from the log file
      new_output = tail -20 "$LOG_FILE"
      new_hash = sha256(new_output)

      if new_hash != last_output_hash and new_output != "":
        if last_output_hash != "" and output_looks_similar(new_output, last_output):
          repeating_rounds += 1   # output changing but repetitive (loop)
          silent_rounds = 0
        else:
          silent_rounds = 0       # genuinely new output, keep going
          repeating_rounds = 0
        last_output_hash = new_hash
      else:
        silent_rounds += 1

      # Persist state to registry (survives agent restart)
      update_registry(task_id, {
        lastOutputHash: new_hash,
        lastCheckedAt: now(),
        silentRounds: silent_rounds,
        repeatingRounds: repeating_rounds
      })

      if silent_rounds >= max_silent_rounds:
        → notify user: "Claude has been silent for 12 hours, kill or keep waiting?"
        → wait for user decision
      if repeating_rounds >= max_repeating_rounds:
        → notify user: "Claude appears stuck in a loop (1h of repeated output), kill or keep waiting?"
        → wait for user decision
```

This way tasks that need 5 min or several hours both work without premature kills.

### Full Mode — Features, Bugfixes, Refactors

For non-trivial tasks, use the **full workflow** below. This gives you:
- **Isolated worktree** — no conflicts with other work
- **tmux session** — mid-task steering without killing the agent
- **Task tracking** — know what's running at all times
- **Quality gates** — Definition of Done checklist
- **Smart retries** — don't waste tokens on repeated failures

---

## Full Workflow: Task → Merged PR

### Step 1: Create Worktree

Isolate each task in its own worktree and branch:

```bash
TASK_ID="feat-custom-templates"
BRANCH="feat/$TASK_ID"
REPO_ROOT=$(git rev-parse --show-toplevel)
WORKTREE="/tmp/worktrees/$TASK_ID"

git worktree add -b "$BRANCH" "$WORKTREE" origin/main
cd "$WORKTREE"

# Install dependencies (adapt to your stack)
pnpm install   # or: npm install / go mod tidy / pip install -r requirements.txt
```

### Step 2: Launch Agent in tmux

Start Claude Code in **interactive mode** (no `-p`) so you can steer mid-task.
**Important:** Use `tmux pipe-pane` to log output — do NOT use `| tee` because it
turns stdout into a pipe, which breaks interactive mode (claude detects `!isatty(stdout)`
and may disable interactive features, breaking `send-keys` steering).

**Critical:** Set up `pipe-pane` BEFORE sending the command. Otherwise early output
(startup messages, fast crashes) is lost.

```bash
LOG_FILE="/tmp/worktrees/$TASK_ID/claude-output.log"
MAX_LOG_SIZE=$((100 * 1024 * 1024))  # 100 MB safety cap

# 1. Create session with an idle shell first
tmux new-session -d -s "$TASK_ID" -c "$WORKTREE"

# 2. Start pipe-pane BEFORE the command runs — captures ALL output from the start
#    Strip ANSI escape codes so log files are clean and grep-parseable
tmux pipe-pane -t "$TASK_ID" -o "sed 's/\x1b\[[0-9;]*[a-zA-Z]//g' >> $LOG_FILE"

# 3. NOW send the command — all output is captured
tmux send-keys -t "$TASK_ID" "claude --dangerously-skip-permissions \
  'Your detailed prompt here.

When completely finished:
1. Commit all changes with descriptive messages
2. Push the branch: git push -u origin $BRANCH
3. Create PR: gh pr create --fill
4. Notify: openclaw system event --text \"Done: $TASK_ID\" --mode now'" Enter
```

**Log file management:** For very long-running tasks, the log file can grow large.
Monitor its size and rotate if needed:
```bash
LOG_SIZE=$(stat -c%s "$LOG_FILE" 2>/dev/null || echo 0)
if [ "$LOG_SIZE" -gt "$MAX_LOG_SIZE" ]; then
  mv "$LOG_FILE" "${LOG_FILE}.old"
  # pipe-pane will create a new file on next wr