Skip to content

Agent Skills Guide

This guide explains how kneo_agent integrates with the Agent Skills open standard from agentskills.io.

What Kneo Supports

Kneo Agent supports two skill authoring paths:

  1. In-memory skills created directly in Python with Skill(...) or ToolRegistry.to_skill(...)
  2. Disk-backed skills loaded from Agent Skills-compatible SKILL.md directories

The second path is designed to interoperate with the broader Agent Skills ecosystem.

Skills work alongside middleware, but they solve different problems:

  • skills package reusable prompts, tools, defaults, and metadata
  • middleware adds executable policy around runs, streams, model calls, and tool calls

Supported File Structure

Kneo Agent expects either:

  • A path to a skill directory containing SKILL.md
  • A direct path to SKILL.md

Example:

weather/
├── SKILL.md
├── references/
│   └── REFERENCE.md
├── scripts/
│   └── normalize_weather.py
└── assets/

SKILL.md Format

SKILL.md must contain:

  • YAML frontmatter delimited by ---
  • A Markdown body used as the skill instruction content

Minimum required frontmatter fields:

  • name
  • description

Kneo Agent also preserves these optional fields when present:

  • license
  • compatibility
  • metadata
  • allowed-tools
  • tools
  • defaults
  • extra
  • tags

Example:

---
name: weather
description: Load a reusable weather skill from disk and use it for weather questions.
license: MIT
compatibility: Works with Python and a registered get_weather handler.
metadata:
  author: kneo-agent
allowed-tools: Bash(python:*) Read
tools:
  - name: get_weather
    description: Return current weather for a city.
    parameters:
      type: object
      properties:
        city:
          type: string
      required:
        - city
defaults:
  max_iterations: 5
tags:
  - domain:weather
---

# Weather Skill

Use this skill when the user asks for current weather conditions by city.

Loading Skills

Use load_skill(...) to activate a single skill:

from kneo_agent import load_skill

skill = load_skill("examples/skills/weather")

If the skill declares tools, bind handlers in code:

skill = skill.with_tool_handlers({"get_weather": get_weather})

That split is deliberate: the standard file defines portable metadata and instructions, while executable handlers stay local to the host application.

Discovering Skills

Use discover_skills(...) to scan one or more directories:

from kneo_agent import discover_skills

catalog = discover_skills(["examples/skills"])
for entry in catalog:
    print(entry.name, entry.path)

Use discover_default_skills(...) to scan conventional locations:

from kneo_agent import discover_default_skills

catalog = discover_default_skills(
    project_root=".",
    user_home="~",
)

The default search covers:

  • .agents/skills
  • .claude/skills

Progressive Disclosure

Kneo Agent supports the Agent Skills guidance to keep SKILL.md concise and place detailed material in sibling folders.

Supported bundled resource folders:

  • references/
  • scripts/
  • assets/

Resources are discoverable but not injected automatically into every run.

Use:

paths = skill.resource_paths()
reference_text = skill.read_resource("references/REFERENCE.md")

This keeps the core skill lightweight while still letting the runtime or host agent load extra material on demand.

Activation Payloads

For integrations that want to inject a structured skill payload into prompts, use:

prompt = skill.activation_prompt()

This returns:

  • The Markdown body from SKILL.md
  • The skill directory path
  • A list of discoverable bundled resources

Current Kneo Behavior

Kneo Agent currently maps Agent Skills into its existing runtime contract:

  • The Markdown body becomes Skill.system_prompt
  • Frontmatter tools becomes ToolDefinition[]
  • Frontmatter defaults contributes to RunConfig
  • Frontmatter extra merges into RunConfig.extra
  • Bound tool handlers are merged into extra["tool_handlers"]

This means skills work across Bridge, Native, and Adapter runtimes without provider-specific changes.

Middleware is intentionally separate from this mapping. Skills compile into data-oriented RunConfig fields, while middleware remains executable code attached explicitly through AgentBuilder or RunConfig(middlewares=[...]).

MCP-Backed Tool Registries

MCP support builds on the same capability path rather than introducing a separate execution model.

A typical pattern is:

  1. import remote MCP tools into ToolRegistry
  2. package that registry into a skill or attach it with AgentBuilder.with_tool_registry(...)
  3. let the existing RunConfig.extra["tool_handlers"] mechanism execute them

Example:

from kneo_agent import MCPServerConfig
from kneo_agent.utils import ToolRegistry

registry = ToolRegistry()
await registry.register_mcp_server(
    MCPServerConfig.stdio(
        name="filesystem",
        command="npx",
        args=["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
    ),
    prefix="fs_",
)

skill = registry.to_skill("filesystem-mcp")

This keeps MCP tool servers aligned with the same skill and tool packaging model described in the rest of this guide.

Example

See:

  • Skill.from_path(...)
  • load_skill(...)
  • discover_skills(...)
  • discover_default_skills(...)
  • Skill.resource_paths()
  • Skill.read_resource(...)
  • Skill.activation_prompt()
  • ToolRegistry.to_skill(...)
  • ToolRegistry.register_mcp_server(...)
  • AgentBuilder.with_tool_registry(...)