agent-failure-registry_skill

Overview

This skill lets you search and contribute to the Agent Failure Registry — a community archive of agent post-mortems, fixes, and prevention tips. Use it to find documented solutions for errors, learn root causes, and avoid repeating known mistakes. It also supports submitting new post-mortems via GitHub PR to enrich the shared knowledge base.

How this skill works

The skill indexes the registry repository (examples/ and submissions/) and supports category, tag, and free-text keyword searches. A provided shell script runs the search locally, parses YAML entries, and formats results with summary, root cause, fix, prevention, and lessons learned. Submissions follow a template and schema, and you can generate or validate a post-mortem before creating a GitHub PR.

When to use it

• You hit an error and want to check if someone else already solved it
• Debugging complex agent behavior where root cause is unclear
• Auditing common failures to improve your error handling and tests
• Sharing a resolved incident as a post-mortem to help others
• Proactively reviewing recent failures in your tech stack or platform

Best practices

• Search by category first (e.g., api_failure, auth_expiry) then narrow with tags or keywords
• Capture exact error messages and the failing component before searching
• When submitting, include what you tried that failed and the concrete fix that worked
• Rate confidence (1–5) and tag technologies/services to improve discoverability
• Regularly review registry entries in your domain and apply prevention steps to code and runbooks

Example use cases

• Find a known Puppeteer timeout workaround by keyword search
• Locate previous Twitter API auth_expiry incidents and their token refresh strategies
• Search rate_limit post-mortems to design backoff and retry policies
• Submit a dependency_break post-mortem after an external library upgrade caused errors
• Browse recent submissions to incorporate lessons into your CI/CD checks