Extension Development

Use this skill to guide the workflow, not as a second API manual. The online references below own the detailed contracts, examples, and reload behavior. The local engineering checks below remain mandatory even when those references cannot be fetched.

Before designing or editing

1. Identify what the user wants and the smallest capability set that can provide it. Check existing host services and shared panels before building a replacement.
2. For behavior-only discussion, apply Engineering checks without enumerating APIs. Before specifying or implementing an interface, choose its one matching capability reference below; read the overview when container/scaffold/reload behavior is relevant. Reuse verified text still in context. For a named interface, obey the system prompt's strict lookup budget and stop as unverified when it is exhausted. Use the article's contract/examples, not the documentation site's navigation, styles, or scripts. If the user declined a fallback, request only the missing source and never ask again.
3. Confirm the proposed behavior, affected files, and visible result with the user before scaffolding or editing. Do not publish, restart, or add privileged behavior merely because implementation was approved.

Documentation fallback

1. Fetch the relevant official URL directly; a web search is not required. For truncated output, read the returned temp_file for the needed section. For HTML pages, web_fetch saves extracted text with whitespace collapsed, not original HTML: line-based reading may still return one long line. One targeted text extraction is enough to check a detail. Do not write helper scripts or try to reconstruct code formatting from that text; lost newlines can change the meaning of code comments and examples. A no-file-change task includes temporary files such as /tmp/*.py: only read the tool-returned cache, do not create a script or reformatted copy elsewhere.
2. If the needed contract is still missing, truncated, or ambiguous, stop this lookup. Report it as unverified; no match on a page does not prove the method or its namespace absent, private, or unsupported. Do not inventory other APIs to infer an answer. Do not retry extraction or probe other extensions/the running host to fill the gap. Ask permission to open the official documentation in a new browser tab. If already authorized for this task's documentation lookup, do not ask again for each page.
3. After consent, use the available browser tool to read only the relevant official documentation. Do not navigate, inspect, or close unrelated tabs. Read beyond truncated snapshots as needed; opening a page alone does not verify its contents. If browser setup is required, ask whether the user wants to use browser-setup; never enable it silently or bypass a disabled browser. If the tool is unavailable, do not invent another browser control mechanism or install one without approval.
4. If the user declines or the browser cannot retrieve the reference, ask the user to supply the documentation or designate a separate source checkout matching the running version and permit read-only inspection. Do not search installed OpenClacky gem source. Reading a checkout does not authorize modifying it to make an extension work.
5. If still blocked, end with only Unverified detail, Reference checked, and Evidence or permission needed next. For example: "I could not verify this method from this page; please provide its source." Do not turn that into "the object does not exist" followed by a disclaimer. Clarifying the user's goal may continue, but implementation against that contract must wait. Resolve version differences before relying on a contract; version metadata is allowed, installed implementation source is not.

Capability → reference

Read the pages needed for this task, not every reference indiscriminately. This index routes lookups; field lists, signatures, and code examples belong in those pages.

Working boundaries

• Develop in ~/.clacky/ext/local/<id>/. Never edit installed/builtin packages or gem source to customize a user's extension. Do not search or read installed OpenClacky gem implementation source, even to resolve missing documentation; version metadata is allowed. Confirm intentional id overrides.
• Do not add hooks or patches without an explicit request; they execute arbitrary Ruby.
• Reuse the documented host APIs and theme conventions. Do not guess methods from similarly named libraries or manipulate host internals.
• Keep data outside the extension package using the documented persistence facility. Validate input and get consent for destructive or paid operations.
• Choose the reload procedure from the overview's contribution-specific table. Do not claim that every change hot-reloads, or restart the server without consent.
• Verification is evidence, not a prediction: distinguish manifest checks, tests, actual UI/API behavior, and anything still awaiting user verification.
• Local development does not imply marketplace publication.

Engineering checks

Apply these when proposing the design and again against the actual code before handoff. Do not count a promise to follow a rule as evidence that the implementation follows it.

1. Access and side effects: identify files, sessions, credentials, and external destinations involved. Refuse unauthorized access or disclosure; never bypass host authentication. Keep secrets out of frontend code and logs. Validate inputs and paths, keep persistent data outside the package, and ensure destructive changes or private-data transfers require specific approval rather than general permission to build.
2. Request budget: check every fetch, loop, timer, retry, and worker. Prefer events and cached reads; do not repeatedly fetch full histories. Default to no added threads; necessary concurrency must be bounded. No tight loops or sub-second polling. Necessary polling must use a coarse interval, prevent overlap, pause when hidden or finished, and have bounded retries and request duration. Check the failure path as well as success.
3. Lifecycle and cost: verify rerenders and session switches do not multiply listeners, timers, or requests; disposal releases them and stale responses cannot affect a new session. Hidden cached panels must pause unnecessary work without waiting for disposal. A tab/session switch does not prove disposal occurred; verify unsubscribe/visibility contracts instead of using assumed disposal as a substitute for cleanup. Model/media calls need explicit approval, including recurring scope; mounting, refresh, and history replay must not initiate paid or destructive actions or external sends. Read-only billing queries are not model invocations, but still need request limits.
4. Host reuse and evidence: reuse host capabilities and btn-* / form-*, Clacky.Modal, and var(--color-*); use scoped, prefixed custom styles where needed. For basic inputs use form-input / form-textarea. Confirm custom property names in the relevant reference or generated scaffold, not by their plausible spelling; do not invent fallback token names. If a token is unverified, omit the color override and inherit host styling, rather than adding a guessed token with hardcoded fallback colors. Prefix tab ids with the extension id to avoid collisions. Check light/dark appearance for UI work. Do not add unrequested hooks or patches or modify installed packages. Test the applicable boundaries above with controlled data; do not use real destructive, disclosure, or paid operations just to prove a safeguard. Report which checks were exercised, which were code review only, and which remain open.

Scaffold

1. Agree on the smallest implementation. A panel may reuse a host API without a new backend; a capability composed from existing tools may only need a skill. A user's ordinary app work does not need an extension container, and a project-only skill can live in that project's .clacky/skills/.
2. Run clacky ext new <id> for a runnable skeleton. Use --full only when the task needs the broader examples. Read generated files before changing them.
3. Implement the approved behavior against the referenced contracts. Keep manifest paths, unit ids, and actual files aligned; do not retain unused scaffold features.
4. Adapt the scaffold's tests to the real behavior and run them. If a backend has no tests, add them instead of treating missing tests as permission to skip verification. Cover invalid input and failures as well as the successful response; apply Engineering checks to the implementation.
5. Run clacky ext verify; resolve errors and review warnings using its actual code, file, and hint. Verify the visible feature or endpoint afterward.
6. Follow Handoff below.

Debug & verify

1. Reproduce the reported symptom; inspect the actual local container and relevant reference before proposing a fix.
2. Run clacky ext verify and read its structured findings. Use clacky ext list to identify the resolved layer and accidental shadowing. Do not maintain a second hardcoded list of accepted keys in this skill.
3. For invisible panels, check documented slots, tab options, manifest associations, and the browser error stack. For API failures, check the request method/path, handler contract, status, and logs. For stale behavior, check the reload matrix.
4. Fix the root cause within the agreed scope, rerun relevant tests and verification, then check the reported behavior and the affected Engineering checks. Do not widen scope to unrelated warnings without discussing them with the user.
5. Follow Handoff below.

Publish (only on explicit request)

1. Read the overview's current publishing requirements and command options.
2. Confirm the target local container, intended marketplace status, device binding, and version. Do not bypass authentication, ownership, or encrypted-content limits.
3. Run tests and verification. If README.md is missing, ask whether to write usage instructions before proceeding; derive them from the actual implemented behavior.
4. Publish only the approved target/version/status. Updating an existing extension requires manually choosing a greater version in ext.yml; --force does not increment it. Explain failures instead of guessing alternate publish behavior.
5. Report the actual version and status returned. Unpublishing also needs explicit approval; it is not routine cleanup.

Handoff

• State what changed, what passed, and what the user still needs to check.
• After extension edits, use the development UI helpers documented in Calling Host APIs to show the refresh button once; also open the aside for a session-aside panel. Use the injected service/session context, not a guessed host, port, or session id.
• These HTTP helpers are not browser control. If the user will test the browser, keep that boundary and report UI checks as pending; do not treat it as permission to inspect their tabs. Honor a separate request not to send UI-helper broadcasts.
• A successful UI-helper response only acknowledges a broadcast. If no matching UI is connected, ask for manual refresh. Verify required Ruby reloads separately; neither UI helper restarts the server.
• Stop at the approved outcome. Do not publish or perform other release actions as an automatic wrap-up.