cape.agent.skills: Agent skills for the CAPE agent

This package collects the agent skills available to the CAPE agent. A skill is a documented workflow that tells the agent how and when to use certain tools and how to chain tool calls together. Skills come from two sources:

Built-in skills are defined in this package, alongside any tools they provide (see cape.agent.skills.cntlrunner).

User skills are discovered from .agents/skills/<NAME>/SKILL.md files in the folder in which the user launches the agent (see cape.agent.skills.skillbase.discover_user_skills()).

Skills are gated by the SkillSet option of the model in use (see cape.agent.options.modelopts), and activated by the agent using the use_skill tool (see cape.agent.skills.skilltools).

class cape.agent.skills.Skill(name: str, description: str, content: str, tools: list | None = None, fname: str | None = None)

Definition of an agent skill, from code or a SKILL.md file

Call:
>>> skill = Skill(name, description, content, **kw)
Inputs:
name: str

Short name of the skill, e.g. "cntl-runner"

description: str

One-line summary shown in the skill listing

content: str

Full Markdown instructions for the agent

tools: {None} | list[str]

Names of tools this skill provides, if any

fname: {None} | str

Name of file skill was read from, if any

Outputs:
skill: Skill

Definition of one agent skill

content

str Full Markdown instructions for the agent

description

str One-line summary shown in the skill listing

fname

str | None Name of file skill was read from, if any

classmethod from_defn(name: str, defn: dict)

Create a Skill from a dictionary definition

Call:
>>> skill = Skill.from_defn(name, defn)
Inputs:
name: str

Short name of the skill

defn: dict

Dictionary with at least description and content

Outputs:
skill: Skill

Definition of one agent skill

name

str Short name of the skill

tools

list[str] Names of tools this skill provides, if any

cape.agent.skills.discover_user_skills(rootdir: str) → dict

Discover user skills from an .agents/skills/ folder

Scans <rootdir>/.agents/skills/<NAME>/SKILL.md and reads every valid skill file. Malformed files are skipped with a warning.

Call:
>>> user_skills = discover_user_skills(rootdir)
Inputs:
rootdir: str

Folder in which the agent was launched

Outputs:
user_skills: dict[Skill]

Map of skill names to skill definitions

Versions:

  • 2026-09-01 @ddalle: v1.0

cape.agent.skills.read_skillfile(fname: str) → Skill

Read an agent skill definition from a SKILL.md file

The file must start with a YAML front matter section delimited by --- lines, containing at least name and description. The remainder of the file is Markdown instructions for the agent.

Call:
>>> skill = read_skillfile(fname)
Inputs:
fname: str

Name of SKILL.md file to read

Outputs:
skill: Skill

Definition of one agent skill

Raises:
ValueError

If fname has no valid front matter or is missing a required key

Versions:

  • 2026-09-01 @ddalle: v1.0