Skills¶

Skills are scoped instruction documents loaded on demand through two read-only tools. Kedi does not inject every skill into every prompt.

Layout¶

.agents/
  skills/
    release-review/
      SKILL.md
    incident-triage/
      SKILL.md

Each skill is exactly one UTF-8 SKILL.md under one skill-name directory. Skill names start with an alphanumeric character and may contain letters, digits, _, and -.

Enable Skills¶

> skills: enabled

>> Use a relevant project skill if one applies, then return [answer: str].
= <answer>

The compact directive registers list_skills and read_skill. Disable an inherited policy with > skills: disabled.

Profiles can carry the same setting:

> profile: maintainer:
    > adapter: pydantic
    > skills: enabled

The expanded form configures discovery:

> skills:
    enabled: true
    cwd: workspace
    max_skills: 40
    include_registry: true
    include_all: false
    exclude_paths: `["~/.agents/skills"]`

enabled is required in the expanded form. The remaining settings are:

Setting	Default	Meaning
`cwd`	program directory	Base directory used to locate the project-local `.agents/skills` source
`max_skills`	`20`	Maximum number of discoverable skills; accepts 1 through 100
`include_registry`	`true`	Include `$KEDI_HOME/registry/skills` in discovery
`include_all`	`false`	Merge all source roots instead of stopping at the first root containing valid skills
`exclude_paths`	empty	Exclude source roots or individual skill directories after path expansion

Relative cwd values resolve from the Kedi program, not the shell's incidental working directory. exclude_paths is an inline Python list; ~ is expanded before source comparison.

The policy is lexical. A top-level directive affects following calls and procedures defined after it. A directive inside a procedure or profile applies only in that scope. > skills: disabled explicitly turns off an inherited policy.

Source Priority¶

Kedi checks sources in this order:

$KEDI_HOME/registry/skills, normally ~/.kedi/registry/skills;
<cwd>/.agents/skills;
~/.agents/skills.

Merged names are deterministic. If sources define the same skill name, read_skill uses the highest-priority copy. Set include_registry: false to skip only the registry source.

Discovery Tools¶

list_skills(all: bool = false, limit: int = 20) -> list[str] returns valid skill identifiers in deterministic sorted order. limit must be a positive integer no greater than 100 and is additionally bounded by max_skills. Source merging is configured by include_all; the all tool argument remains accepted for API compatibility.

read_skill(skill_name: str) -> str returns the exact UTF-8 file content for one valid listed skill.

Both tools are read_only, so the default approval policy allows them.

On-Demand Loading¶

Enabling skills adds compact instructions telling the agent to:

call list_skills when reusable guidance may help;
call read_skill for a listed relevant name;
follow it only for the current task;
never claim to have read a skill whose contents were not returned.

The model does not know a skill's body until it reads that skill. This avoids filling every context with unrelated instructions and makes skill usage visible in the tool trace.

Install Into the Kedi Registry¶

Install a one-file skill from a local directory or GitHub repository:

kedi skills add --path ~/my-skill
kedi skills add --repo owner/skill-repository

The source must have SKILL.md at its root. Kedi copies only that file into ~/.kedi/registry/skills/<name>/SKILL.md. GitHub input uses the OWNER/REPOSITORY form, performs a credential-free shallow checkout, and records the checked-out revision. Installation is user-scoped and never writes into the project.

--path accepts either a skill directory containing SKILL.md or a path to that file. Reinstalling the same skill name replaces its registry copy only after the new source has passed validation.

Resolution and Security Checks¶

Kedi rejects invalid names, absolute/traversal attempts, symlink escapes, missing/non-file targets, non-UTF-8 content, and files larger than 256 KiB.

list_skills omits entries that fail validation rather than advertising unreadable content. read_skill reports the specific failure when explicitly requested.

These checks protect skill-file resolution. Skill content is still trusted instruction text and may attempt to influence agent behavior. Review project and installed skills, and keep approvals/tool boundaries active.

When to Use Skills¶

Use a skill for repeatable operational guidance that should be selected at task time: release procedures, code-review policy, migration checklists, or domain workflows. Put unconditional behavior in > system: and executable typed operations in tools instead.

Skills do not grant capabilities. A skill may instruct use of a tool, but the profile must separately expose that tool and its approval policy.