# Error To Action

> skill: error-to-action

- Skill: `0-uddeshya-0/error-to-action` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add 0-uddeshya-0/error-to-action`
- Raw SKILL.md: https://api.skillmd.com/api/skills/0-uddeshya-0/error-to-action/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: 0-uddeshya-0 (https://skillmd.com/u/0-uddeshya-0)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/0-uddeshya-0/error-to-action

---

# skill: error-to-action

## purpose
Convert a raw error message into a plain-English explanation and a specific next action. Stops agents from returning cryptic error strings to users or getting stuck when a tool fails.

## when_to_use
- After a tool call fails or returns an unexpected error
- System response contains a status code or exception that must be handled
- Before presenting any error state to a user

## when_not_to_use
- Error is expected and already handled by your logic (404 that means "not found, skip")
- The "error" is a successful empty result (zero rows is not an error)
- Not enough context to determine action — ask the user instead

## input
```
error: string            # Raw error message, exception, or failure response
operation: string        # What was being attempted when this occurred
user_context: string     # Who the user is and what they were trying to do
retry_count: int         # How many times already retried
```

## output
```json
{
  "error_type": "string",
  "user_message": "string",
  "action": "retry|fix_input|escalate|skip|wait",
  "action_detail": "string",
  "retryable": true | false,
  "developer_note": "string"
}
```

## instructions

```
Classify the error and decide what to do.

Classification → action:
- auth/permission denied, fix is known (e.g. wrong credentials, fork required, use different token) → fix_input with exact steps
- auth/permission denied, fix requires admin/third-party action (internal system, org SSO, billing) → escalate immediately, no retry
- not found (404) → fix_input or skip
- rate limit (429) → wait then retry
- validation error → fix_input (request was malformed)
- server error (500, 503) → retry once; escalate if persists
- timeout → retry once with simpler payload if possible
- network → retry once; escalate if persists

user_message rules: one sentence, plain English, say what happened and what happens next, no stack traces or error codes, no "an error occurred" — say specifically what failed.

retryable is false for: auth errors, permanent validation failures, after 2+ retries.

Return JSON only.
```

## constraints
- Max output tokens: 250
- user_message: one sentence, no technical jargon
- retryable false after 2 retries regardless of error type

## example

**Input:**
```
error: "429 Too Many Requests. Retry-After: 30"
operation: "Fetching billing data from billing_api"
user_context: "User viewing subscription page"
retry_count: 0
```

**Output:**
```json
{
  "error_type": "rate_limit",
  "user_message": "Fetching your billing info — it'll be ready in about 30 seconds.",
  "action": "wait",
  "action_detail": "Wait 30 seconds per Retry-After header, then retry same request unchanged.",
  "retryable": true,
  "developer_note": "billing_api 429. Retry-After: 30s. retry_count=0."
}
```

---

**Input:**
```
error: "403 Forbidden: You don't have permission to push to this repository"
operation: "git push to agent-skills repo"
user_context: "New contributor trying to submit their first PR"
retry_count: 0
```

**Output:**
```json
{
  "error_type": "auth_permission_denied",
  "user_message": "You don't have write access to this repo — fork it, push to your fork, then open a PR.",
  "action": "fix_input",
  "action_detail": "Fork the repo on GitHub, push your branch to your fork, then open a PR to the upstream main branch.",
  "retryable": false,
  "developer_note": "403 on push. Public repo, fix is known: fork workflow. No escalation needed."
}
```

## feedback_log
<!-- date | situation | what went wrong | better behavior -->
# 2026-05-29 | 403 on push to public repo — fix was fork + open PR | skill returned escalate, but the fix was known and required no admin | split auth errors: fix_input when workaround is known, escalate only when admin/third-party action required