Ext Debug
Testing & Qualityext-debugExt 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.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/clacky-ai/openclacky/blob/HEAD/lib/clacky/default_extensions/ext-studio/skills/ext-debug/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/ext-debug, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
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 thefilepath exists andext.ymlis valid YAML. A skill needsSKILL.mdunderskills/<id>/; an agent needs itspromptfile; a panel needs itsviewfile; api needsapi/handler.rb.schema.unknown_contributes— a top-level key undercontributes:isn't one ofpanels 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
- panel:
schema.bad_attach— a panelattach:entry isn't a valid token. Use agent ids or"*"for all.ref.missing_panel— an agent referencespanels: [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 referencesskills: [id]that no skill provides. Fix the id or add the skill.ref.missing_attach_agent— a panel'sattach: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 aSKILL.md, the user must reload the WebUI page — there's no restart, but a stale tab won't update on its own. Editingext.ymlalso applies on the next load. - Panel not appearing? Check the panel's
attach:(or the agent that references it viapanels: [id]). A panel with noattachand no referencing agent has nothing to mount onto. - API 404? Routes are relative to
/api/ext/<ext_id>/. Confirm the handler subclassesClacky::ApiExtensionand the route pattern matches whatview.jsfetches. - 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."