Failure Registry

Search the community-driven Agent Failure Registry for known agent errors, solutions, and lessons to debug issues or submit new failure post-mortems.

Security Scan

The skill does what it claims — it clones a public GitHub repo and searches YAML postmortems; nothing requested or installed is disproportionate to that purpose.

Purpose & Capability

Name/description match the provided files and script. The included search script implements the described registry search and PR guidance. The only mild mismatch: metadata declares no required binaries, but the script clearly relies on git and python3 (and common POSIX tools like find/grep).

Instruction Scope

SKILL.md instructs the agent to run the included search script and to submit postmortems via GitHub PRs — the script's behavior (clone/pull repository, parse YAML, print results) stays within that scope. The script reads only files in the cloned repo; it does not exfiltrate data to external endpoints beyond the GitHub clone/pull URL.

Install Mechanism

This is an instruction-only skill with a bundled shell script (no install spec). The script clones from a GitHub URL (well-known host) into /tmp and uses local tools. Network access to GitHub is required; cloning a public repo is expected for this purpose but does mean the skill will write files to /tmp at runtime.

Credentials

The skill requests no credentials or environment variables and does not attempt to read secrets. However, the packaged metadata lists no required binaries while the script requires git and python3 (PyYAML optional). This is a documentation mismatch (not an immediate security problem) — the script will fail if those tools are missing.

Persistence & Privilege

always:false and the skill does not request persistent system-wide privileges. It clones into /tmp and does not modify other skills or system configs. The agent can invoke it autonomously (default) but that is expected for skills of this nature.

Assessment

This skill appears coherent and implements a simple registry search. Before installing: ensure you are comfortable the agent can access the network and clone from GitHub (the REPO_URL is https://github.com/unleashedbelial/agent-failure-registry). Verify you have git and python3 (and PyYAML if you want richer output) on the host. Because the script writes to /tmp, consider running it in a restricted/sandboxed environment if you distrust the remote repo. Finally, avoid running any code from unreviewed PRs in the cloned repository — this skill only reads YAML, but cloned repos may later contain scripts; audit any executable content before running it.

Failure Registry Skill

Search and learn from the Agent Failure Registry — a community-driven database of agent failures, solutions, and lessons learned. When you hit a wall, check if someone else already climbed it.

Quick Start

Search for similar failures:

./scripts/search-registry.sh --category api_failure
./scripts/search-registry.sh --keyword "puppeteer"
./scripts/search-registry.sh --tag twitter --tag auth

Search everything:

./scripts/search-registry.sh --all

Use Cases

1. Search — When Things Break

When you encounter an error, search the registry before reinventing the wheel:

• By Category: api_failure, auth_expiry, rate_limit, silent_failure, data_corruption, timeout, logic_error, dependency_break, permission_denied, other
• By Keywords: Tool names, error messages, symptoms
• By Tags: Platform, service, technology

The registry contains post-mortems from examples/ (curated) and submissions/ (community).

Search Results Include:

• Summary of what went wrong
• Root cause analysis
• Fix that worked
• Prevention strategies
• Lessons learned

2. Submit — Share Your Pain

When you solve a new failure, help the community:

1. Document the failure following the schema
2. Submit via GitHub PR (script can help generate template)
3. Include context — what you tried, what worked, what didn't

Required Fields:

• Title, category, tags
• Summary, root_cause, fix
• Prevention steps, lessons learned
• Confidence level (1-5)

3. Learn — Stay Ahead

Periodically browse recent submissions to learn from others' failures before you hit them yourself.

Script Usage

The search-registry.sh script handles all the heavy lifting:

Arguments:

• --category CATEGORY — Search specific failure category
• --tag TAG — Search by tag (repeatable)
• --keyword KEYWORD — Free-text search in all fields
• --all — Show all entries (for browsing)

Examples:

# Find authentication issues
./scripts/search-registry.sh --category auth_expiry

# Find Twitter-related failures
./scripts/search-registry.sh --tag twitter

# Find Puppeteer issues
./scripts/search-registry.sh --keyword "puppeteer"

# Multiple criteria
./scripts/search-registry.sh --category api_failure --tag openai

# Browse everything
./scripts/search-registry.sh --all

Repository Structure

The Agent Failure Registry contains:

• examples/ — Curated failure post-mortems
• submissions/ — Community submissions
• template.yaml — Template for new submissions
• schema/postmortem.yaml — Schema validation

Categories Reference

• api_failure — API errors, timeouts, invalid responses
• auth_expiry — Authentication/token expiration issues
• rate_limit — Rate limiting, quota exceeded
• silent_failure — No error thrown, but wrong behavior
• data_corruption — Data integrity, parsing failures
• timeout — Operation timeouts, hanging processes
• logic_error — Flawed reasoning, incorrect assumptions
• dependency_break — External service/lib failures
• permission_denied — Access control, file permissions
• other — Miscellaneous failures

Tips

Before Searching:

• Extract key error messages or symptoms
• Identify the failing component (API, tool, process)
• Note the context (what were you trying to do?)

When Submitting:

• Be specific about the fix that worked
• Include what you tried that didn't work
• Rate your confidence in the solution (1-5)
• Tag with relevant technologies/services

For Prevention:

• Review failures in your domain periodically
• Update your error handling based on lessons learned
• Share edge cases and gotchas with the community

Implementation Notes

• Registry cloned to /tmp/agent-failure-registry
• Uses PyYAML for parsing (with grep fallback)
• Searches both examples/ and submissions/
• Output formatted for readability
• Handles multiple search criteria

Remember: Every failure is a lesson. Document it, share it, learn from it.