cape.agent.skills.skillbase: Core skill definition and discovery

This module provides the Skill class, which defines an agent skill: a documented workflow that tells the CAPE agent harness how and when to use certain tools, and how to chain tool calls together.

Skills can be defined in the code base (see cape.agent.skills.cntlrunner) or discovered from the folder in which the user launches the CAPE agent. User skills are read from .agents/skills/<NAME>/SKILL.md files, which consist of a YAML front matter section and a Markdown body:

---
name: my-skill
description: One-line summary shown in the skill listing
---

# My skill

Full instructions for the agent go here.

The name and description fields are used to list available skills in the system prompt; the full content and any skill-specific tool schemas are only shown to the model when it asks for them using the use_skill tool.

class cape.agent.skills.skillbase.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.skillbase.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.skillbase.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