extension-design

Choose the surface before coding

Start from the experience the user wants, not from extension machinery. Before implementation, identify:

• who initiates the workflow
• how often it occurs
• what the harness or an existing CLI already provides
• which interface the workflow actually needs

Choose between direct CLI use, a script, skill, user-invoked slash command, human UI, agent tool, or extension integration. Confirm that shape with the user before writing code.

Prefer the smallest missing piece. If a CLI already owns the capability but is awkward to use from the harness, wrap it thinly rather than rebuilding it. Custom extension behaviour is earned by integration needs such as UI, state, hooks, events, or tool registration.

Do not register an agent tool merely because an extension can. A permanent tool must earn its model cost through repeated natural use or a capability the agent cannot otherwise reach. For rare or explicitly requested workflows, prefer a user-invoked command, script, or CLI, with a skill only when the agent needs invocation guidance.

Fit the real harness

Inspect the user's setup and conventions before designing around an abstract ideal. Reuse its existing navigation, settings, command, and tool patterns. Add engineering machinery only for risks and requirements present in this workflow. Do not turn a personal convenience into an enterprise subsystem because testing, permissions, retries, compatibility layers, or configurability sound generically respectable.