Kode Skill Format (SKILL.md)

Native skill packaging for *roductsdevkode* A skill is a reusable unit of agent capability — a system-prompt + tool whitelist + optional inline scripts the kode agent can invoke by name.

Distinct from Claude-style commands (meta/context/commands SKILL.md.

• LoadNativeSkillFile(path) (NativeSkill, error) — parses one file.
• DiscoverNativeSkillsDirs() []string — default order:
  1. Cfg.NativeSkillsDir (explicit override; YAML config key

     native_skills_dir).

  2. ~/.kode/skills/.

First-match wins on slug collisions.

The loader is *est-effort by file* a malformed SKILL.md skips that one directory but does not fail the registry load. Validation errors surface via NativeSkill.Err so the operator can inspect why a skill didn't load.

R5 — Runner (interface)

internal/skills.SkillRunner (forward-declared; concrete impl ships in engines/sdk/koder_kit Go binding when #025 lands):

type SkillRunner interface {
    Run(ctx context.Context, skill NativeSkill, args []string) (string, error)
}

kode binaries ship NoopSkillRunner which returns ErrSkillRuntimeMissing so unwired binaries fail loud — same fail-loud pattern as subagent.NoopRunner (DKODE-100).

The koder_kit KodeSkillRunner (DKODE-025) registers a real Runner via tools.SetSkillRunner once the Go binding ships.

R6 — Surfaces

Operator slash commands (read-only inspection until Runner lands):

• /skills or /skills list — registered skills with slug + description.
• /skills show <slug> — frontmatter + body of one skill.
• /skills resolve <slug> [args ...] — render body with $ARGUMENTS

  substituted (same convention as /commands resolve).

Once Runner lands, also:

• kode skill exec <slug> [args ...] — CLI invocation through Runner.
• skill_exec(slug, args) agent tool — harness dispatch.

R7 — Permission model

Permission verb skill + target <slug>. Examples:

• skill:dangerous-* — disable a family
• skill:* — disable all
• tool:skill_exec (legacy) — covers the agent tool wholesale

Sub-tool invocations from the skill body still pass through the permission matcher individually (the Runner forwards them), so deny rules on bash/fs:write apply transitively.

R8 — Distribution

Skills resolve from:

1. Local path: kode skill install <path> copies into ~/.kode/skills/.
2. Koder Hub: kode skill install <slug> resolves through

   hub.koder.dev/api/v1/skills/<slug> (depends on DKODE-026 type=skill Hub adapter).

Hub-unavailable falls back to a clear error; manual operators can always install by path.

Out of scope

• Sandboxing of kode skill exec body execution — that's a separate

  ticket (engines/sandbox per #032).

• Cross-platform binary distribution — Hub side; this spec only

  prescribes the on-disk format.

• TOML loader (the Claude convention uses TOML; kode uses YAML for

  consistency with its own config tree — both can land if the broader Stack standardizes).

Test contract

T1. Empty SKILL.md rejects with a clear validation error. T2. Missing name rejects. T3. Missing description rejects. T4. Missing version rejects. T5. Mismatched name ↔ directory name rejects. T6. Round-trip: file → load → Resolve(args) substitutes $ARGUMENTS. T7. Discovery: override > ~/.kode/skills/; first-match wins. T8. NoopSkillRunner.Run returns ErrSkillRuntimeMissing. T9. Real Runner registration via tools.SetSkillRunner round-trips. T10. Multi-skill directory with one malformed entry: the rest load.