Claude Code Delegation Skill
Relevant source files
The following files were used as context for generating this wiki page:
The Claude Code Delegation Skill is a specialized capability within the pi-digby agent that allows it to offload complex coding tasks to a headless session of Claude Code. It is designed to handle implementation tasks such as bug fixes, feature development, or refactoring in external repositories by automating the cloning, prompting, and execution of the claude CLI in a non-interactive mode.
This skill operates within the broader "Skills" architecture of the project, which allows the agent to create and use custom CLI tools stored in defined workspace or channel-specific directories. The delegation skill specifically leverages isolated worktrees to ensure that multiple coding tasks do not interfere with one another.
Sources: skills/claude-code/SKILL.md:1-12, src/agent/prompt.ts:75-98
System Architecture
The delegation skill follows a structured workflow that involves environment preparation, external process execution, and result reporting.
Execution Flow
The following diagram illustrates the lifecycle of a delegated coding task:
The process begins by creating a unique directory for the task. If a repository is involved, the agent uses the GitHub CLI (gh) to clone or update the codebase before initiating the Claude Code session.
Sources: skills/claude-code/SKILL.md:20-75, src/agent/prompt.ts:183-195
Skill Management and Loading
Skills are loaded dynamically from the file system. The loadSkills function merges global skills with channel-specific ones, allowing for overrides.
| Component | Path | Description |
|---|---|---|
| Global Skills | {workspacePath}/skills/ | Tools available across all Slack channels. |
| Channel Skills | {channelPath}/skills/ | Tools restricted to a specific conversation context. |
| Skill Metadata | SKILL.md | Contains YAML frontmatter (name, description) and instructions. |
Sources: src/agent/skills.ts:16-40, src/agent/prompt.ts:80-90
Implementation Details
Claude Code Execution Command
The skill executes Claude Code using specific flags to ensure it operates correctly in a headless container environment.
claude -p \
--dangerously-skip-permissions \
--output-format json \
--max-budget-usd 5 \
"$(cat "$TASK_DIR/prompt.md")" \
> "$TASK_DIR/result.json" 2> "$TASK_DIR/stderr.log"
Sources: skills/claude-code/SKILL.md:46-54
Key CLI Flags
--print(-p): Runs in non-interactive mode to completion.--dangerously-skip-permissions: Prevents the CLI from pausing for manual confirmation in the headless environment.--output-format json: Ensures structured data is returned for the agent to parse.--max-budget-usd: Implements a cost cap (default $5) to prevent runaway LLM usage.
Sources: skills/claude-code/SKILL.md:56-61
Authentication and Persistence
Claude Code requires a long-lived token to operate. In the pi-digby architecture, this is handled through persistent storage volumes.
Persistent Storage Layout
The system uses EFS (Elastic File System) mounted at /data to ensure that configuration and authentication tokens survive container restarts.
A symbolic link is created during startup from the home directory to the EFS mount to preserve authentication state.
Sources: entrypoint.sh:5-10, skills/claude-code/SKILL.md:84-86, CLAUDE.md:12-16
Authentication Setup
Because claude setup-token requires interactive browser authentication, the agent cannot perform initial setup. It directs the user to run an ECS exec command:
aws ecs execute-command --cluster pi-digby --task <id> --container pi-digby --interactive --command "claude setup-token"
Sources: skills/claude-code/SKILL.md:89-105
Cost and Steering
The skill includes built-in mechanisms for cost control and iterative improvement.
- Budgeting: Tasks are categorized by complexity. Bug fixes typically use a $2 budget, while complex refactors may go up to $10. Users must be consulted before exceeding the $10 threshold.
- Steering: If the initial output is not satisfactory, the agent can update
prompt.mdand re-run Claude Code with the--continueflag to resume the session and apply adjustments.
Sources: skills/claude-code/SKILL.md:63-82
Summary
The Claude Code Delegation Skill transforms pi-digby from a simple chat interface into an autonomous coding agent. By leveraging isolated worktrees in the /tasks/ directory and maintaining persistent authentication via EFS, the system can safely execute complex, multi-turn coding operations in external repositories while providing structured feedback and PR links to the end user.
Sources: skills/claude-code/SKILL.md:107-110, CLAUDE.md:12-16