Skip to main content

​
Skills API

Kheish exposes the skill registry through both control-plane endpoints and runtime tools.

​
HTTP endpoints

  • GET /v1/skills
  • GET /v1/skills/{skill_name}
  • GET /v1/sessions/{session_id}/skills
GET /v1/skills supports a query filter and returns summary data such as name, description, version, scope, digest, runtime metadata, and resolved paths. GET /v1/skills/{skill_name} returns the full definition, including instructions. GET /v1/sessions/{session_id}/skills also supports query, but it returns only the skills currently visible to that session after capability filtering and promoted-skill source-scope filtering. For ordinary on-disk and daemon-loaded skills, the /v1/skills surface is inspection-only. Skill activation still happens inside the runtime through tools, not through a direct execution endpoint. Promoted procedural skills add related control-plane endpoints under the learning surface:
  • POST /v1/learnings/{learning_id}/promote-skill
  • GET /v1/learning-skills
  • GET /v1/learning-skills/{skill_name}
  • POST /v1/learning-skills/{skill_name}/revoke
Those promoted-skill endpoints are documented in Learnings API.

​
Runtime surfaces

Inside the agent runtime, skills are exposed through:
  • list_skills
  • use_skill
These tools let the model discover the available catalog and activate a skill explicitly. Important runtime rule:
  • list_skills and use_skill operate on the session-visible skill surface, not on the raw global catalog

​
Execution model

The skill surface distinguishes between:
  • session-scoped inline activation
  • forked execution through a child agent path
When use_skill waits for a forked child to settle, the returned spawn payload includes the child snapshot and can also include final_output when the child emitted a canonical run output. Prefer that canonical output over spawn.snapshot.last_assistant_message when you need the child’s final result. The waited fork response can also include the child launch_run_id, which lets operators inspect the child run through the normal run-debug endpoints. Promoted procedural skills add stricter execution guarantees:
  • they only execute through fork
  • they must use the verification child-agent profile
  • they run inside a dedicated worktree under .kheish-procedural-worktrees/...
  • only active promoted skills are visible through /v1/skills and /v1/sessions/{session_id}/skills
Use the control-plane API for operator inspection and the runtime tools for execution-time behavior.