# Ext Debug

> Ext Debug is an Agent Skill for testing & quality published in the clacky-ai/openclacky repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Debug an OpenClacky extension that won't load, throws errors, or whose panel/api/skill/agent isn't showing up. Use when the user reports something broken with their extension, when `clacky ext verify` reports issues, or when a change didn't take effect. Reads structured verify errors and fixes manifest and file problems.

- Skill name: `ext-debug`
- Category: [Testing & Quality](https://www.openparable.com/skill/testing-quality/1)
- Source: https://github.com/clacky-ai/openclacky/blob/HEAD/lib/clacky/default_extensions/ext-studio/skills/ext-debug/SKILL.md
- Repository: clacky-ai/openclacky (1,113 GitHub stars when collected)

## SKILL.md

# Extension Debug

Diagnose and fix a broken extension. Your primary instrument is `clacky ext verify` —
it's a compiler for extensions: every issue is structured with a `code`, `message`,
the offending `file`, and a `hint` telling you how to fix it.

## Step 1 — Run verify

```
clacky ext verify
```

Read the output line by line. `[OK]` lines confirm resolved units. `[ERR]` blocks a
load; `[WARN]` is advisory. Each issue looks like:

```
[ERR] <ext> <unit> (<code>) — <message> [<file>]
         hint: <how to fix>
```

## Step 2 — Fix by error code

- **`loader.error`** — a file the manifest points at is missing or the container
  couldn't be parsed. Check the `file` path exists and `ext.yml` is valid YAML. A skill
  needs `SKILL.md` under `skills/<id>/`; an agent needs its `prompt` file; a panel needs
  its `view` file; api needs `api/handler.rb`.
- **`schema.unknown_contributes`** — a top-level key under `contributes:` isn't one of
  `panels api skills agents channels patches hooks`. Fix the spelling.
- **`schema.unknown_field` / `schema.unknown_key`** — a unit has a field that isn't
  allowed for its type. Remove or rename it. Allowed fields:
  - panel: `id title title_zh description description_zh view order attach`
  - api: `id handler`
  - skill: `id dir protected`
  - agent: `id title title_zh description description_zh order prompt panels skills`
  - channel: `id platform adapter`
- **`schema.bad_attach`** — a panel `attach:` entry isn't a valid token. Use agent ids
  or `"*"` for all.
- **`ref.missing_panel`** — an agent references `panels: [id]` that no panel provides.
  Fix the id, or use `<ext_id>/<panel_id>` to reference a panel in another extension.
- **`ref.missing_skill`** — an agent references `skills: [id]` that no skill provides.
  Fix the id or add the skill.
- **`ref.missing_attach_agent`** — a panel's `attach:` names an agent that doesn't
  exist. Fix the agent id.
- **`override`** (warning) — a unit in a higher layer is shadowing a lower one
  (`local > installed > builtin`). Usually intentional; confirm with the user if not.

Fix one issue, re-run verify, repeat until clean.

## Step 3 — "It verifies but doesn't show up"

If verify is clean but a change isn't visible:
- **Hot reload is per-request.** After editing `view.js`, `handler.rb`, or a `SKILL.md`,
  the user must **reload the WebUI page** — there's no restart, but a stale tab won't
  update on its own. Editing `ext.yml` also applies on the next load.
- **Panel not appearing?** Check the panel's `attach:` (or the agent that references it
  via `panels: [id]`). A panel with no `attach` and no referencing agent has nothing to
  mount onto.
- **API 404?** Routes are relative to `/api/ext/<ext_id>/`. Confirm the handler subclasses
  `Clacky::ApiExtension` and the route pattern matches what `view.js` fetches.
- **Skill not triggering?** The AI selects skills by their `description`. Make the
  description concrete about WHEN to use it.

## Step 4 — Confirm the fix

End with a clean `clacky ext verify` and have the user reload to confirm the behavior
actually works — don't declare success on "should work."

---

Source: https://www.openparable.com/skill/testing-quality/ext-debug (OpenParable). Cite the canonical URL above.
