agent-bootstrap

What this skill does

# 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:
1. Reads `agent.toml` from repository root
2. Validates environment (required vars, commands, runtimes)
3. Configures plugins for the current tool
4. Generates MCP server config
5. 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

```bash
# 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:**

1. Check if skill already installed: `ls ~/.claude/skills/skill-name/SKILL.md`
2. If not installed, determine source type and run appropriate command
3. 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/`:
```bash
# 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`:
```toml
[[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:**

1. **Plugins** - Update `.claude/settings.json`:
   ```json
   {
     "enabledPlugins": {
       "plugin-name@marketplace": true
     }
   }
   ```

2. **MCP Servers** - Generate `.mcp.json`:
   ```json
   {
     "server-name": {
       "type": "http",
       "url": "https://...",
       "headers": {
         "Authorization": "Bearer ${ENV_VAR}"
       }
     }
   }
   ```

3. **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
  Comman