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

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,
  run improvement analysis, and inspect hosted availability checks using the
  DebugBundle CLI and local project scaffold. Use when the user reports a bug,
  runtime failure, production incident, endpoint downtime, or health-check issue.
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. Verify setup — Run debugbundle doctor --json to identify local-only versus connected mode
2. Check incidents first — Query local or cloud active incidents before broad source exploration
3. Inspect the bundle — Read the debug bundle for full context (error, request, logs, environment)
4. Review reproduction — Use the reproduction artifact to understand how to trigger the issue
5. Analyze for improvements — Run debugbundle analyze for a deterministic change plan when local bundles are available
6. Evaluate repeated noise — Use capture-rule suggestions or path-scoped client-error capture policy when bundle evidence shows recurring low-value incidents
7. Inspect availability checks — For downtime or endpoint reachability reports, list hosted health checks, inspect recent results/rollups, and use side-effect-free tests before changing monitoring
8. Apply, validate, and resolve — Make the fix, run the project validation workflow, then resolve verified incidents

The generated skill now keeps the most important commands near the top:

debugbundle doctor --json
debugbundle incidents --source local --status active --json
debugbundle incidents --source cloud --status active --json
debugbundle inspect <incident-id> --source <local|cloud> --json
debugbundle explain <incident-id> --source <local|cloud> --json
debugbundle bundle <incident-id> --source <local|cloud> --json
debugbundle reproduce <incident-id> --source <local|cloud> --json

It also points agents to the local evidence paths they need most often: .debugbundle/profile.json, .debugbundle/local/connection.json, .debugbundle/local/events/, .debugbundle/local/state.json, .debugbundle/bundles/local/, .debugbundle/bundles/local/reproductions/, and .debugbundle/bundles/cloud/.

Noise Management

When the same low-value pattern keeps reopening, the generated skill tells agents to inspect incident evidence first and then evaluate a scoped noise-control path:

• Run debugbundle capture-rule suggest <incident-id> --json before writing a manual rule
• Prefer project capture rules for centralized operational noise control
• Keep generic frontend suppression narrow with structured browser, opaque-event, or bot signals
• Use capture-policy client-error path rules for known route-scoped 4xx incidents instead of promoting all client errors

Availability Checks

For endpoint downtime, public reachability, or health-check setup requests, the generated skill tells agents to inspect hosted availability data before editing code or changing monitoring:

debugbundle health checks list --project-id <project-id> --json
debugbundle health checks results <check-id> --project-id <project-id> --json
debugbundle health checks daily-rollups <check-id> --project-id <project-id> --json
debugbundle health checks test --project-id <project-id> --url https://app.example.com/health --json

Agents should prefer health checks test before creating or updating a saved check. The test path is side-effect-free: it does not open incidents, write retained history, or advance counters. Saved availability checks are hosted DebugBundle requests, not SDK events, and V1 supports only external GET and HEAD targets.

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 --json

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

# Process any pending local events
debugbundle process --preset balanced --json

Update the Generated Skill

Run validation to check whether the generated skill and its references match the DebugBundle CLI version currently installed:

debugbundle validate

If validation reports stale generated guidance, refresh it safely:

debugbundle validate --fix

This updates .agents/skills/debugbundle/SKILL.md, generated references, schemas, and evals without overwriting .debugbundle/profile.json.

To refresh against the latest published DebugBundle CLI templates, run:

npx @debugbundle/cli@latest validate --fix

There is no separate debugbundle skill update command today. validate --fix is the canonical update path because it keeps the whole managed scaffold in sync, not just the top-level skill file.

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.
- After a fix is verified, or after an intentional smoke or dogfood incident has served its purpose, resolve it with `debugbundle resolve <incident-id> [incident-id ...]` or MCP `resolve_incident` / `resolve_incidents` so the needs-attention queue remains actionable.
- 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:

Drift Validation

debugbundle validate checks that the generated skill, references, schemas, and evals still match the current CLI templates. If an existing generated guidance file is stale, validation returns a warning and debugbundle validate --fix refreshes that file without overwriting .debugbundle/profile.json.

Next Steps

• GitHub Automation — Repository dispatch and GitHub Actions follow-up
• Agent Workflows — Overview of agent-first approach
• Availability Checks — Hosted health-check behavior for agents
• Managing Noise — How agents should reduce recurring low-value incidents
• MCP Tools — Complete MCP tool catalog