Agent Bootstrap

Agent Bootstrap: Declarative Environment Setup

You bootstrap the agentic development environment by reading agent.toml and configuring the current tool (Claude Code, OpenCode, etc.) accordingly.

Usage

/agent-bootstrap           # Validate environment and configure tool
/agent-bootstrap --verify  # Run all verification checks
/agent-bootstrap --check   # Dry run: report what would be configured

Core Principle

Self-bootstrap without external dependencies. The manifest (agent.toml) + this skill = complete environment setup. No curl|bash, no package managers, no external tools.

Quick Reference

Use this skill when:

• Starting work in a new repository
• Environment feels misconfigured
• Checks are failing unexpectedly
• Setting up a new machine

What this skill does:

• Reads agent.toml from repository root
• Validates environment (required vars, commands, runtimes)
• Configures plugins for the current tool
• Generates MCP server config
• Reports status (or runs verification checks with --verify)

The States

State AB0: No Manifest

Symptoms:

• No agent.toml in repository root
• User asks to bootstrap but no manifest exists

Key Questions:

• Should we create a starter agent.toml?
• What environment requirements does this project have?

Interventions:

• Offer to create a minimal agent.toml based on detected project type
• Check for common patterns (Cargo.toml → Rust, package.json → Node, etc.)
• Link to docs/agent-toml-spec.md if it exists

State AB1: Manifest Found, Validation Needed

Symptoms:

• agent.toml exists at repository root
• Environment not yet validated
• User invoked /agent-bootstrap

Key Questions:

• Are all required environment variables set?
• Are all required commands in PATH?
• Do runtime versions meet constraints?

Interventions:

• Parse agent.toml using TOML parser
• Check each required_env variable
• Check each required_commands command
• Check runtime versions against constraints
• Report any failures with actionable guidance

State AB2: Environment Valid, Configuration Needed

Symptoms:

• Environment validation passed
• Tool configuration not yet applied
• Plugins, MCP servers, or hooks need setup

Key Questions:

• Which plugins need to be enabled?
• What MCP servers should be configured?
• Which hooks should be applied?

Interventions:

• For Claude Code:
• Update .claude/settings.json with enabled plugins
• Generate .mcp.json from MCP server definitions
• Note: Hooks require user to copy to their settings (tool-specific)
• Report configuration changes made

State AB3: Configured, Verification Mode

Symptoms:

• User invoked /agent-bootstrap --verify
• Need to run verification checks

Key Questions:

• Which checks should run (based on trigger)?
• Did all checks pass?

Interventions:

• Run all [[verification.checks]] with trigger = "stop" or trigger = "explicit"
• Report pass/fail status for each
• If any fail, report the failure and suggest fixes
• Block completion if running as stop hook

Execution Process

Phase 1: Parse Manifest

# Read agent.toml from repository root

Parse the TOML file and extract:

• [manifest] - version check (1.1 for remote skill support)
• [environment] - validation requirements
• [[skills]] - skill definitions (local and remote)
• [[plugins.*]] - plugin configuration
• [[mcp.servers]] - MCP server definitions
• [[hooks.*]] - hook definitions
• [[verification.checks]] - verification checks

Phase 1.5: Install Remote Skills

For each skill with a source field (rather than path), install from remote:

Source Format Detection:

| Pattern | Type | Installation |

|---------|------|--------------|

| owner/repo@skill | GitHub | npx skills add owner/repo@skill -g -y |

| owner/repo@skill + version | GitHub pinned | npx skills add owner/repo@skill#version -g -y |

| skills.sh/name | Registry | npx skills add name -g -y |

| https://.../raw/.../skill | Raw URL | Fetch SKILL.md directly to ~/.claude/skills/ |

| https://....git@skill | Git URL | npx skills add <url> -g -y |

Installation Process:

• Check if skill already installed: ls ~/.claude/skills/skill-name/SKILL.md
• If not installed, determine source type and run appropriate command
• Verify installation succeeded

Report Format:

Installing remote skills...

[1/34] gitea-workflow
  Source: jwynia/agent-skills@gitea-workflow
  ✓ Installed

[2/34] code-review
  Source: jwynia/agent-skills@code-review
  ✓ Already installed

[3/34] custom-skill
  Source: https://gitea.example.com/.../raw/.../custom-skill
  ✗ Failed: Connection refused

Remote skills: 32/34 installed, 1 already present, 1 failed

Raw URL Installation (for Gitea/GitLab):

When source starts with https:// and contains /raw/:

# Create skill directory
mkdir -p ~/.claude/skills/skill-name

# Fetch SKILL.md directly
curl -sSL "https://gitea.example.com/.../raw/.../skill-name/SKILL.md" \
  -o ~/.claude/skills/skill-name/SKILL.md

# Verify file was created
test -f ~/.claude/skills/skill-name/SKILL.md

Skills with version field:

When a skill has both source and version:

[[skills]]
name = "code-review"
source = "jwynia/agent-skills@code-review"
version = "v1.2.0"

Append version as git ref: npx skills add jwynia/agent-skills@code-review#v1.2.0 -g -y

Phase 2: Validate Environment

For each requirement, check and report:

Environment Variables:

✓ GITHUB_TOKEN is set
✗ TAVILY_API_KEY is not set
  → Set this variable for web search functionality

Commands:

✓ git (found at /usr/bin/git)
✓ cargo (found at /home/user/.cargo/bin/cargo)
✗ node not found in PATH
  → Install Node.js: https://nodejs.org/

Runtimes:

✓ rust 1.78.0 >= 1.75.0
✗ python 3.9.7 does not satisfy >=3.10
  → Upgrade Python to 3.10 or later

Phase 3: Configure Tool

Detect Current Tool:

• Look for .claude/ → Claude Code
• Look for .opencode/ → OpenCode
• Look for .cline/ → Cline
• Look for .cursor/ → Cursor

For Claude Code:

• Plugins - Update .claude/settings.json:

   {
     "enabledPlugins": {
       "plugin-name@marketplace": true
     }
   }

• MCP Servers - Generate .mcp.json:

   {
     "server-name": {
       "type": "http",
       "url": "https://...",
       "headers": {
         "Authorization": "Bearer ${ENV_VAR}"
       }
     }
   }

• Hooks - Report hook configuration (requires manual setup):

   Hooks defined in agent.toml:
   - post_tool_use: rustfmt on *.rs files
   - stop: verification script

   To enable hooks, add to your Claude Code settings.

Phase 4: Report Status

Bootstrap complete for delft-core

Environment:
  ✓ All required commands found (git, cargo, rustfmt, npx)
  ✓ All runtime versions satisfied (rust 1.78.0, node 20.11.0)
  ⚠ 1 optional env var not set (TAVILY_API_KEY)

Remote Skills:
  ✓ 34 remote skills installed
  ⚠ 1 skill failed to install (see above)

Configuration:
  ✓ Enabled plugin: rust-analyzer-lsp
  ✓ Generated .mcp.json with 1 server
  ⚠ Hooks require manual configuration

Skills: 40 skills available (6 local, 34 remote)

Next steps:
  - Set TAVILY_API_KEY for enhanced web search
  - Review hooks configuration in agent.toml
  - Retry failed remote skill installs: npx skills add <source> -g -y

Phase 5: Verification (--verify mode)

Run each verification check:

Running verification checks...

[1/4] fmt
  Command: cd src && cargo fmt --check
  ✓ PASSED (0.8s)

[2/4] build
  Command: cd src && cargo build
  ✓ PASSED (12.3s)

[3/4] clippy
  Command: cd src && cargo clippy --workspace -- -D warnings
  ✗ FAILED (8.2s)

  error: unused variable `x`
   --> src/crates/delft-cli/src/main.rs:42:9

[4/4] tests
  Command: cd src && cargo test
  ⏭ SKIPPED (trigger = explicit, use --verify to run)

Verification: 2/3 passed, 1 failed

Environment Variable Checking

Check if variable is set (not its value):

# Bash approach
if [ -z "${VAR_NAME+x}" ]; then
  echo "VAR_NAME is not set"
fi

For Claude Code, use the Bash tool to check:

printenv | grep -q "^VAR_NAME=" && echo "set" || echo "not set"

Command Checking

command -v git >/dev/null 2>&1 && echo "found" || echo "not found"

Runtime Version Checking

# Rust
rustc --version | grep -oE '[0-9]+\.[0-9]+\.[0-9]+'

# Node
node --version | grep -oE '[0-9]+\.[0-9]+\.[0-9]+'

# Python
python3 --version | grep -oE '[0-9]+\.[0-9]+(\.[0-9]+)?'

File Operations

Read agent.toml

Use the Read tool to read agent.toml from repository root.

Update settings.json

Use the Edit tool to update .claude/settings.json with plugin configuration.

Generate .mcp.json

Use the Write tool to create .mcp.json with MCP server configuration.

Anti-Patterns

The Assumption Trap

Pattern: Assuming environment is correct without validation.

Problem: Leads to confusing errors later.

Fix: Always validate. Report clearly what's missing.

The Secret Leak

Pattern: Writing environment variable values to files.

Problem: Secrets in version control.

Fix: Only write ${VAR_NAME} references, never values.

The Implicit Bootstrap

Pattern: Auto-running bootstrap without user consent.

Problem: Security risk; unexpected changes.

Fix: Always require explicit /agent-bootstrap invocation.

The Over-Configuration

Pattern: Configuring everything even when not needed.

Problem: Confusing state; hard to debug.

Fix: Only configure what's declared in manifest.

Example Interactions

Example 1: Fresh Start

User: /agent-bootstrap

Your approach:

• Read agent.toml from repository root
• Validate environment requirements
• Configure Claude Code settings
• Generate MCP config if servers defined
• Report status and next steps

Example 2: Verification

User: /agent-bootstrap --verify

Your approach:

• Read verification checks from agent.toml
• Run each check with trigger = "stop" or trigger = "explicit"
• Report pass/fail for each
• Summarize results

Example 3: Check Mode

User: /agent-bootstrap --check

Your approach:

• Parse agent.toml
• Report what would be validated and configured
• Do not make any changes
• List any issues found

Example 4: No Manifest

User: /agent-bootstrap (no agent.toml exists)

Your approach:

• Report that no manifest found
• Offer to create a starter manifest based on project detection
• If user agrees, create minimal agent.toml
• Link to specification documentation

Integration Graph

Inbound (From Other Skills)

| Source Skill | Source State | Leads to State |

|--------------|--------------|----------------|

| (none) | - | AB0 or AB1 |

Outbound (To Other Skills)

| This State | Leads to Skill | Target State |

|------------|----------------|--------------|

| AB2 (configured) | gitea-workflow | (ready to work) |

| AB3 (verified) | (any) | (environment confirmed) |

Complementary Skills

| Skill | Relationship |

|-------|--------------|

| find-skills | Discover skills listed in manifest |

| context-network | May be bootstrapped after environment setup |

Manifest Schema Reference

See docs/agent-toml-spec.md for the complete schema specification.

Key sections:

• [manifest] - version (1.1 for remote skill support)
• [environment] - required_env, required_commands, runtimes
• [[skills]] - skill definitions (local with path, remote with source)
• [[plugins.{tool}]] - plugin configuration
• [[mcp.servers]] - MCP server definitions
• [[hooks.{tool}]] - hook configuration
• [[verification.checks]] - verification checks

Skills Schema (v1.1)

# Local skill
[[skills]]
name = "delft-authoring"
path = ".claude/skills/delft-authoring"

# Remote skill (GitHub)
[[skills]]
name = "code-review"
source = "jwynia/agent-skills@code-review"

# Remote skill with version pin
[[skills]]
name = "gitea-workflow"
source = "jwynia/agent-skills@gitea-workflow"
version = "v1.0.0"