AI Agent Skill: docktree

Relevant source files

The following files were used as context for generating this wiki page:

• skills/docktree/SKILL.md
• internal/cli/help_doc.go
• internal/cli/types.go
• README.md
• skills/README.md
• internal/cli/render.go

The docktree AI Agent Skill is a specialized instruction set designed to enable coding agents (such as Claude Code, Codex, and Cursor) to effectively interact with the Docktree CLI. It provides the necessary context for agents to run Docker Compose services in isolated git worktrees, preventing port and container name collisions while coordinating shared platform services.

This skill ensures that agents understand the CLI's specialized output formats, specifically the machine-readable JSON envelope used for native commands, and the distinct separation between standard output (JSON) and standard error (Docker progress). By leveraging this skill, agents can autonomously spin up isolated environments, retrieve allocated ports, and manage the lifecycle of worktree-specific infrastructure.

Sources: skills/docktree/SKILL.md:1-12, README.md:46-52, skills/README.md:1-5

CLI Interaction Architecture

The skill defines a rigorous interaction model where the agent acts as a controller for the docktree binary. The CLI serves as the "source of truth," and the agent must use specific flags to ensure reliable machine-to-machine communication.

Communication Flow

Agents are instructed to always prioritize structured data. The primary mechanism for this is the global --json flag, which must be placed before the subcommand. This transforms the human-readable TUI output into a predictable JSON schema.

The diagram shows the branching logic an agent follows based on whether a command is "Native" (Docktree-specific logic) or "Passthrough" (direct Docker Compose wrapper).
Sources: skills/docktree/SKILL.md:18-35, internal/cli/help_doc.go:21-25

Standard Streams Management

A critical component of the skill is the handling of stdout and stderr. To prevent JSON parsing errors, agents must avoid merging these streams because Docker's progress UI (which is not JSON) is emitted to stderr.

Stream	Content Type	Agent Action
Stdout	Structured JSON	Parse as primary result
Stderr	Progress UI / Human Logs	Redirect to /dev/null or log file

Sources: skills/docktree/SKILL.md:43-52

Data Models and Schemas

Native commands return specific JSON structures defined in the internal/cli/types.go file. These structures allow the agent to inspect the state of the worktree environment.

Help and Metadata

Agents can discover CLI capabilities dynamically using the HelpDoc structure.

type HelpDoc struct {
    Command     string       `json:"command"`
    Synopsis    string       `json:"synopsis,omitempty"`
    Usage       []string     `json:"usage,omitempty"`
    Options     []HelpOption `json:"options,omitempty"`
    Subcommands []HelpCmd    `json:"subcommands,omitempty"`
}

Sources: internal/cli/help_doc.go:10-21

Execution Results

When an agent invokes up or status, it receives comprehensive environment data.

Field	Description	Source
instance	Metadata about the worktree (branch, project name)	internal/cli/types.go:22
ports	Array of host_port and container_port mappings	internal/cli/types.go:27
shared_services	List of services running in the platform tier	internal/cli/types.go:29
hint	Contextual advice (e.g., suggesting shared.services config)	internal/cli/types.go:36

Common Agent Workflows

The skill outlines specific sequences of commands for common development tasks.

Starting a Worktree Environment

1. Check Status: Invoke docktree --json status to see if the project is already active.
2. Initialize/Start: Invoke docktree --json up 2>/dev/null.
3. Discovery: Parse the UpResult JSON to find URLs for the started services.

This sequence illustrates the standard procedure for an agent to ensure an environment is active and accessible.
Sources: skills/docktree/SKILL.md:61-80

Error Handling

The skill defines a standard error envelope that agents must handle when the exit code is non-zero.

{
  "error": "config",
  "message": "no compose files found in /repo",
  "details": null
}

Exit codes include: 0 (OK), 2 (Usage), 3 (Config), 4 (Docker), 5 (Noop), and 6 (Conflict).
Sources: skills/docktree/SKILL.md:55-59, internal/cli/render.go:785-800

Implementation Details

The skill is distributed via npx skills and is part of the Bnjoroge1/Docktree repository. It identifies itself through a SKILL.md file which contains the "allowed-tools" (Bash) and "description" triggers such as "isolated docker per branch" or "docktree up".

• Global Flag Requirement: --json must always precede the subcommand (e.g., docktree --json ports --all).
• Tooling: The agent uses Bash(docktree:*) to execute commands.
• Scope: The skill focuses on CLI invocation and lifecycle management; it explicitly excludes direct editing of docktree.yml (deferred to the docktree-init skill).

Sources: skills/docktree/SKILL.md:1-12, skills/README.md:10-20