Add a skill

A skill declares a capability and its permissions. It does not grant its own authority or replace the host's approval policy.

Start with a manifest#

Create skills/<id>/manifest.json. A minimal read capability might look like:

{
  "id": "scratchpad",
  "name": "Scratchpad",
  "version": "0.1.0",
  "kind": "native",
  "permissions": ["scratchpad:read"],
  "commands": ["search"]
}

This is an illustrative declaration, not a working integration. Register its implementation and permission handling before exposing it to users.

The SkillManifest contract in src/contracts/skill.ts defines the supported fields and kinds. Optional tool declarations identify read-only tools; requiresConfirmation identifies commands that require the host's review flow. A read-only hint never exempts an AI-invoked tool from user confirmation.

Implement through the existing boundaries#

1. Put provider transport in src/connectors/ when a provider is involved.
2. Normalize domain behavior in src/server/services/.
3. Add or extend strict contracts in src/contracts/ and validate untrusted input.
4. Expose reads, search, and preview preparation independently from execution.
5. Add a feature module beside src/client/features/ and use Clidey UX controls.
6. Connect the feature through the composition root and add focused regressions.

Never send, write, or execute merely because a search result or model plan was produced. An external write belongs in an explicit execution path with the required fresh approval.

Validate#

pnpm run validate:manifests
pnpm run check

For a constrained external example, inspect the K9s read-only plugin. For UI and provider boundaries, see Architecture.