Skills

A skill is a folder containing a SKILL.md file: YAML frontmatter followed by a markdown body of instructions. Skills let you package expertise, and progressive disclosure keeps them cheap until the model actually needs them.

The SKILL.md format#

---
name: code-reviewer
description: Review a code change for bugs, security issues, and style problems.
---
 
# Code Reviewer
 
You are reviewing a code change. Work through it methodically and report only
findings you are confident about...

Progressive disclosure#

When you pass skills to an agent, only their names and descriptions are added to the system prompt as a catalog. The full instruction body stays out of context until the model calls the built-in load_skill(name) tool, at which point the body is returned as an observation and any tools the skill declares are registered. This keeps the base prompt small even with a large library of skills installed: the cost of a skill is only paid once the model decides to use it.

import asyncio
 
from agentling import Agent, OpenAIModel, tool
 
 
@tool
def read_file(path: str) -> str:
    """Read a UTF-8 text file and return its contents.
 
    Args:
        path: Path to the file to read.
    """
    with open(path, encoding="utf-8") as handle:
        return handle.read()
 
 
async def main() -> None:
    agent = Agent(
        model=OpenAIModel("gpt-4o-mini"),
        tools=[read_file],
        skills=["examples/skills/code-reviewer"],
    )
    print(await agent.run("Review the code in src/agentling/agent.py"))
 
 
asyncio.run(main())

Skills that bring their own tools#

A skill can declare Python entry points in its frontmatter. They are imported and registered when the skill loads:

---
name: linting
description: Lint Python files and report issues.
tools:
  - my_package.lint_tools:run_ruff
---

Each entry point is a "module.path:attribute" string that must resolve to a Tool, a function decorated with @tool. Because the loop reads the live tool set fresh on every step, tools registered during a load are available on the very next turn.

You can pass skills as folder paths, strings or Path objects, or as pre-built Skill objects created with Skill.from_path.

Security#

The Tools page covers what registered tools can do, and the project's SECURITY.md documents the full trust model.