aimu.skills

Filesystem-discovered agent skills.

aimu.skills.AgentSkill dataclass

AgentSkill(name: str, description: str, path: Path, compatibility: str = '', license_info: str = '', metadata: dict = dict())

A single discovered Agent Skill from the filesystem.

script_tool_names

script_tool_names() -> list[str]

Return {skill}__{script_stem} tool names for every .py in scripts/.

load_body

load_body() -> str

Read SKILL.md, strip YAML frontmatter, return the markdown body.

aimu.skills.SkillManager

SkillManager(skill_dirs: Optional[list[str]] = None)

Discovers and manages Agent Skills from the filesystem.

With no skill_dirs argument, scans the standard search paths at project and user scope: .agents/skills/, .claude/skills/, ~/.agents/skills/, ~/.claude/skills/. Project-level paths win on name collision. Pass explicit skill_dirs to override all defaults.

Discovery logs (at INFO) the number of skills found and the paths searched, so a missing skill directory is easy to spot. Malformed SKILL.md files raise :class:SkillLoadError rather than being silently skipped.

Usage::

manager = SkillManager()                                # auto-discover
manager = SkillManager(skill_dirs=["/path/to/skills"])  # explicit
print(manager.catalog_prompt())
body = manager.get_skill_body("pdf-processing")

catalog_prompt

catalog_prompt() -> str

Return an XML skill catalog suitable for injection into a system prompt.

Each entry lists the skill name, description, and any script-derived tool names the model can call directly (without first calling activate_skill).

get_skill_body

get_skill_body(name: str) -> str

Return the full instructions body of a named skill.

Raises :class:SkillNotFoundError if the skill doesn't exist.

aimu.skills.SkillLoadError

Bases: ValueError

Raised when a SKILL.md file is malformed and cannot be parsed.

aimu.skills.SkillNotFoundError

Bases: KeyError

Raised when a requested skill name does not exist.

aimu.skills.build_skills_server

build_skills_server(manager: SkillManager) -> FastMCP

Build an in-process FastMCP server from a SkillManager.

Registered tools

• activate_skill(name): returns the full SKILL.md body for the named skill
• {skill_name}__{script_stem}(): runs a Python script from a skill's scripts/ dir

The returned FastMCP instance can be passed directly to MCPClient(server=...).