Agent Skill File

The DebugBundle skill file at .agents/skills/debugbundle/SKILL.md follows the agentskills.io specification. It teaches AI coding agents how to investigate incidents, inspect bundles, generate reproductions, and run improvement analysis — without requiring the agent to discover these capabilities from scratch.

File Location

your-project/
├── .agents/
│   └── skills/
│       └── debugbundle/
│           └── SKILL.md
├── .debugbundle/
│   ├── profile.json
│   └── local/
│       └── connection.json
└── AGENTS.md          ← references the skill

The skill file is generated automatically by debugbundle setup and kept in sync by debugbundle validate --fix.

Skill File Structure

Frontmatter

---
name: debugbundle
description: >-
  Investigate runtime incidents, inspect debug bundles, generate reproductions,
  and run improvement analysis using the DebugBundle CLI and local project scaffold.
  Use when the user reports a bug, runtime failure, or asks about production incidents.
metadata:
  author: debugbundle
  version: "1.0"
---

The frontmatter tells agents when to activate the skill — any mention of bugs, runtime failures, or production incidents should trigger DebugBundle workflows.

Core Workflow

The skill file defines a prioritized investigation workflow:

1. Check incidents first — Query existing incidents to avoid re-investigating known failures
2. Inspect the bundle — Read the debug bundle for full context (error, request, logs, environment)
3. Review reproduction — Use the reproduction artifact to understand how to trigger the issue
4. Analyze for improvements — Run debugbundle analyze for a deterministic change plan
5. Apply and validate — Make the fix and verify it using the project's test workflow

Profile Validation

Agents should periodically validate that .debugbundle/profile.json reflects the actual project structure. The skill file instructs agents to:

• Confirm services, frameworks, and workflows match the repository
• Fill in missing paths and ownership notes
• Update validation_status to agent-validated when the profile is trustworthy

Setup Verification

Before investigation, agents verify the local environment:

# Confirm profile, connection mode, and auth state
debugbundle doctor

# Restore missing generated files without overwriting the profile
debugbundle validate --fix

# Process any pending local events
debugbundle process

AGENTS.md Integration

The project's AGENTS.md file references the skill with a managed section:

<!-- debugbundle:start -->
## DebugBundle
- Check DebugBundle for existing incidents before investigating bugs.
- Read `.agents/skills/debugbundle/SKILL.md` for the full debugging workflow.
- Use `debugbundle inspect <incident-id>` or MCP `get_bundle` when a user reports an issue.
- Run reproduction artifacts from `.debugbundle/bundles/local/reproductions/` before proposing a fix.
- Use `debugbundle doctor` to validate local DebugBundle setup or connectivity issues.
<!-- debugbundle:end -->

This managed section is auto-generated by debugbundle setup and updated by debugbundle validate --fix. The comment markers ensure updates don't overwrite other content in AGENTS.md.

How Agents Discover the Skill

Agents discover DebugBundle capabilities through progressive disclosure:

1. AGENTS.md — Agent reads the project root and finds the DebugBundle section
2. Skill file — Agent follows the reference to .agents/skills/debugbundle/SKILL.md
3. References — Skill file points to CLI and MCP reference docs for command details
4. Local state — Agent reads .debugbundle/local/state.json for incident index

MCP Alternative

Agents with MCP access can skip the CLI entirely. The MCP tools mirror all CLI capabilities:

Next Steps

• Automation Recipes — End-to-end agent workflow patterns
• Agent Workflows — Overview of agent-first approach
• MCP Tools — Complete MCP tool catalog