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, review product analytics, 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, review product analytics, and inspect hosted availability
  checks using the DebugBundle CLI and local project scaffold. Use when the user
  reports a runtime failure, production incident, product-usage question, endpoint
  downtime, or health-check issue.
metadata:
  author: debugbundle
  version: "1.0"
---

The frontmatter tells agents when to activate the skill. Runtime failures trigger the incident workflow, while questions about visits, routes, devices, actions, funnels, journeys, friction, or analytics opportunities trigger the product analytics workflow.

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. Review product analytics — Start with direct aggregate reads, narrow to funnels or structured journey evidence, and generate a durable analytics bundle only for a bounded question
9. 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.

Product Analytics

For product-usage questions, the generated skill starts with direct aggregate reads:

debugbundle analytics summary --project <project-id> --last 7d --json
debugbundle analytics routes --project <project-id> --last 30d --json
debugbundle analytics actions --project <project-id> --last 7d --json
debugbundle analytics funnel <funnel-key> --project <project-id> --last 30d --json
debugbundle analytics journeys --project <project-id> --last 7d --json

The equivalent MCP workflow begins with get_usage_summary and narrows through route, device, referrer, action, funnel, and journey-pattern reads. Agents inspect bounded, redacted journey samples only when aggregate evidence is insufficient. They generate an analytics bundle only for a focused question that needs a durable artifact; the product does not create one bundle per visit.

The skill also distinguishes reads from mutations. Agents read analytics settings and saved funnel definitions before proposing changes. Settings updates, saved-funnel create/update/archive operations, and bundle generation require explicit user intent and the appropriate member role. Project tokens are ingestion-only, and analytics workflows preserve consent, redaction, retention, and approved custom-dimension limits.

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
• AnalyticsBundle — Aggregate-first product analytics, privacy, and evidence lifecycle
• AnalyticsBundle CLI — Analytics metrics, journeys, funnels, settings, and bundles
• Availability Checks — Hosted health-check behavior for agents
• Managing Noise — How agents should reduce recurring low-value incidents
• MCP Tools — Complete MCP tool catalog