Skip to main content

​
Skills

Skills let Kheish load reusable instruction bundles from disk and apply them explicitly within the runtime.

​
Discovery

The daemon builds a skill registry at startup from:
  • explicit skill roots passed to the daemon
  • repository-local skills/ roots
  • compatibility roots such as .claude/skills and legacy .agents/skills
  • user-level skill roots under the home directory

​
Skill shape

A skill is centered around SKILL.md plus optional runtime metadata such as allowed tools, blocked tools, execution context, and model overrides. See Skill format for the on-disk contract and supported metadata fields.

​
Execution contexts

Kheish currently supports two main execution patterns:
  • inline skills, which activate instructions directly in the session and persist as session-scoped active skills
  • fork skills, which run through a child agent path when the skill requires an isolated execution context

​
Persona defaults versus session-local skills

Skills can now enter a session from two different sources:
  • persona-provided default_skills, which are resolved and frozen into the session persona binding
  • session-local inline skill activations, which are stored as session state
At runtime, Kheish merges those two sources into the active inline skill set for that session. This distinction matters operationally:
  • updating a persona changes the defaults for future bindings, not for already bound sessions
  • deactivating or activating one session-local inline skill does not rewrite the underlying persona record
  • sidechains inherit the parent’s current persona snapshot and capability boundary, then build their own runtime state from that snapshot

​
Capability filtering

The effective capability scope can hide skills even when the daemon registry discovered them successfully. That filtering applies to:
  • the list of available skills advertised to the model
  • persona-provided default inline skills
  • session-local active inline skills
  • the session-visible skill list returned by GET /v1/sessions/{session_id}/skills
  • the visible_skills field returned by GET /v1/sessions/{session_id}/memory-context
  • runtime tools such as list_skills and use_skill
If a skill is excluded by the effective capability scope, it is neither advertised as available nor kept active in the runtime surface.

​
Control surfaces

Skills are exposed through:
  • runtime prompt sections that advertise available and active skills
  • agent tools such as list_skills and use_skill
  • control-plane endpoints for skill listing and inspection
  • session-scoped inspection endpoints such as GET /v1/sessions/{session_id}/skills
The global skill catalog and the session-visible skill surface are not the same thing. GET /v1/skills shows the daemon registry. GET /v1/sessions/{session_id}/skills shows only the subset that survives session capability filtering and promoted-skill source-scope checks. Kheish can also create daemon-owned skills from reviewed procedure learnings. That path is controlled through the learning surfaces, not through the base skill inspection endpoints. A promoted procedural skill:
  • originates from one durable learning record
  • is written into the daemon-owned skill root under the state directory
  • is reloaded into the daemon-owned promoted-skill store
  • becomes visible through the normal skill inspection and runtime activation surfaces only after its rollout status reaches active
Current production constraints:
  • only workspace-scoped procedure learnings can be promoted
  • promoted procedure skills must execute through fork
  • promoted procedure skills must resolve to the verification child-agent profile
  • promoted procedure skills are not used as persistent inline skill state
  • non-active rollout states (draft, verified, canary) stay durable but hidden from the visible catalog

​
Forked skill results

When use_skill activates a forked skill and waits for the child agent to settle, the returned spawn payload can include:
  • the child agent_id
  • the child session_id
  • the initial launch_run_id
  • the terminal child snapshot
  • final_output, when the child emitted a canonical run output
final_output is the safer completion signal for a waited forked skill because a successful child run may finish through a canonical output path without leaving a useful final assistant-text message. For promoted procedural skills, the daemon also allocates one dedicated child worktree under the current workspace root before spawning the child agent. That keeps the promoted procedure off the parent session root by default. See Semantic learning and procedural skills and Learnings API.

​
Operational guidance

Treat inline skills as session-scoped state. Treat fork skills as explicit execution requests. Do not assume that every skill is purely instructional; runtime metadata can constrain tools, model routing, and execution mode.