Chapter 20 · Skills: Pluggable Domain Capabilities

Learning objectives: Understand Agno's Skills plugin system (based on the Anthropic Agent Skills specification), learn to write a compliant SKILL.md, mount skills to Agents and Teams via LocalSkills, and learn how to access Claude's cloud-provisioned skills (pptx/xlsx/docx/pdf).

20.1 Why You Need Skills: From instructions to Skill Packs

In the chapters prior to this one, we've loaded domain knowledge into an Agent using only two approaches:

Approach	Suitable for	Shortcoming
instructions / system prompt	Short behavioral constraints	Context blows up with more knowledge; you pay for the full payload on every request
Knowledge (RAG)	Factual Q&A over massive static docs	Retrieves "document snippets"; poor at delivering cohesive methodology and scripts

Real-world business has a third need: package "how to do a certain type of task" into a reusable, sharable knowledge unit — e.g., "how to do a code review" or "how to write an industry weekly report." This is precisely what a Skill is positioned to do:

A Skill is a self-contained directory bundle containing structured instructions, optional executable scripts, and reference documents. The Agent uses it in a four-step progressive pipeline: discover -> load -> reference -> execute.

Skills and Tools are complementary, not substitutes: Tools give the Agent capabilities (what actions it can perform), Skills give the Agent methodologies (how to do a class of tasks well).

Relationship with the community ecosystem

Agno's Skills integration follows Anthropic's open Agent Skills specification. This means skill directories you wrote for Claude Code, or third-party skill packs shared online, can be dropped directly into an Agno project as long as their structure complies.

20.2 Progressive Loading: The Core Token-Saving Mechanism of Skills

The problem with dumping all domain knowledge straight into the system prompt is "pay for everything, occupy space for everything." Skills adopt a Progressive Discovery strategy:

1. Browse: After registration, only the name + one-line description of each skill appears in the Agent's system prompt (dozens of tokens);
2. Load: When a task matches a skill, the model calls get_skill_instructions(skill_name) to ingest the full instructions;
3. Reference: For more detail, it reads from references/ on demand;
4. Execute: For precise computation/validation, it runs shebang scripts under scripts/.

After mounting Skills, the Agent automatically gains these three dedicated tools:

Tool	Purpose
get_skill_instructions(skill_name)	Load a skill's full instructions
get_skill_reference(skill_name, reference_path)	Read a skill's reference document
get_skill_script(skill_name, script_path, execute, args, timeout)	Read or execute a skill's script

Token economics

Dumping ten complete methodology documents into the system prompt may cost tens of thousands of fixed tokens; the same content as ten skills leaves only ten summaries in the system prompt — only the matched one gets fully loaded.

20.3 Writing a Compliant Skill: SKILL.md and Directory Structure

A skill is just a normal directory; the sole required file is SKILL.md at its root:

my-skills/
├── report-writer/          # Directory name = skill name (must match exactly)
│   ├── SKILL.md            # Required: YAML frontmatter + Markdown instructions
│   ├── scripts/            # Optional: executable scripts (must have a shebang)
│   │   └── wc_check.py
│   └── references/         # Optional: reference docs, loaded on demand
│       └── style-guide.md
└── code-review/
    └── SKILL.md

SKILL.md is composed of YAML frontmatter metadata + body instructions. Only six top-level fields are legal: name, description, license, compatibility, allowed-tools, metadata; any other top-level field will cause validation to fail (put custom info inside the metadata dict):

---
name: report-writer
description: Write structured industry weekly reports, with word-count validation script and style guide
license: Apache-2.0
metadata:
  version: "1.0.0"
  author: gaoxueling
  tags: ["writing", "report"]
---

# Industry Weekly Report Writing Skill

Enable this skill when the user requests an industry weekly/monthly report.

## Workflow
1. First clarify the reporting period and target audience;
2. Organize content in a three-part structure: "This Week's Highlights -> Data Insights -> Next Period Outlook";
3. Before outputting, run scripts/wc_check.py to verify the word count is within range.

## Details
Style requirements are in references/style-guide.md; load them only when the user questions the wording.

Validation runs at load time; non-compliant skills raise SkillValidationError:

• name: lowercase letters, digits, and hyphens only; ≤64 characters; cannot start/end with - or contain consecutive --; must match the directory name exactly;
• Length caps: description ≤1024 chars, compatibility ≤500 chars; license should use an SPDX identifier (e.g., MIT, Apache-2.0);
• Scripts must start with a #! shebang (e.g., #!/usr/bin/env python3), execute with the skill directory as cwd, and accept arguments from the model.

A practical companion script scripts/wc_check.py:

#!/usr/bin/env python3
"""Count Chinese characters and total lines in input text for pre-delivery self-check."""
import sys

text = sys.stdin.read() if not sys.argv[1:] else open(sys.argv[1], encoding="utf-8").read()
cjk = sum(1 for ch in text if "\u4e00" <= ch <= "\u9fff")
print(f"Chinese characters: {cjk}, total lines: {len(text.splitlines())}")
sys.exit(0 if 800 <= cjk <= 2000 else 1)

20.4 Mounting Skills to an Agent with LocalSkills

Skills is the skill orchestrator; LocalSkills is the built-in filesystem loader, supporting loading an entire skill library or a single skill:

import os

from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.skills import Skills, LocalSkills

agent = Agent(
    name="Weekly Report Assistant",
    # Book convention: OpenAI-compatible third-party model
    model=OpenAIChat(
        id="deepseek-chat",
        api_key=os.getenv("DEEPSEEK_API_KEY"),
        base_url="https://api.deepseek.com/v1",
    ),
    skills=Skills(loaders=[
        LocalSkills("./my-skills"),           # Entire skill library
        LocalSkills("./team-shared/skills"),  # Multiple loaders are merged
    ]),
    instructions=[
        "You possess several professional skills.",
        "When encountering a matching task, load the corresponding skill via get_skill_instructions before answering.",
    ],
    markdown=True,
)

agent.print_response("Write this week's AI Agent industry weekly report", stream=True)

Engineering notes:

• Later loader wins on name collision: skills with the same name from a later loader overwrite earlier ones — useful for a "team shared library + project-specific customization" layered setup;
• Hot reload at runtime: after changing skill files on disk, call skills.reload() to re-load without restarting the process;
• Lenient mode: LocalSkills(path, validate=False) skips spec validation and loads best-effort (only truly unreadable SKILL.md files are skipped with a warning) — suitable for introducing external skill packs incrementally.

Use debug_mode=True to observe the full progressive-loading sequence: the first request should show only the summary injected; after a matching task, you'll see the tool call to get_skill_instructions.

20.5 Skills in Teams: Letting the Leader Hold Expert Knowledge Directly

Pass Skills to the Team's skills parameter and the leader directly gains the skill tools and system prompt snippet — no need to delegate to members:

import os
from pathlib import Path

from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.skills import Skills, LocalSkills
from agno.team import Team

skills_dir = Path(__file__).parent / "my-skills"

implementer = Agent(
    name="Implementer",
    role="Modify code per review feedback",
    model=OpenAIChat(id="deepseek-chat", api_key=os.getenv("DEEPSEEK_API_KEY"),
                     base_url="https://api.deepseek.com/v1"),
)

review_team = Team(
    name="Code Review Team",
    model=OpenAIChat(id="deepseek-chat", api_key=os.getenv("DEEPSEEK_API_KEY"),
                     base_url="https://api.deepseek.com/v1"),
    members=[implementer],
    skills=Skills(loaders=[LocalSkills(str(skills_dir))]),  # Leader holds skills
    instructions=["Use your skills to complete the code review first, then delegate modifications to Implementer."],
    markdown=True,
)

review_team.print_response("Review and improve this code: def calc(x,y): return x+y", stream=True)

How to choose among three configuration layers:

Configuration	Scenario
Team(skills=...)	Leader needs domain standards to coordinate and dispatch (review criteria, routing rules)
Member Agent(skills=...)	Expert member needs domain knowledge to do their actual work
Both levels configured	Leader needs context for dispatching; members also need knowledge for execution

Under the hood it is isomorphic to the knowledge/memory/tools mechanisms from previous chapters: skills.get_tools() adds skill tools to the leader's tool list, get_system_prompt_snippet() injects skill metadata into the leader's system prompt.

20.6 Advanced: Claude Cloud Agent Skills (Optional Reading)

If you use the Anthropic official API, you can also let skills "run in the cloud" — Claude provides four out-of-the-box containerized skills that can produce Office files directly in an isolated sandbox:

Skill ID	Capability
pptx	Create/edit presentations and analyze their content
xlsx	Create spreadsheets, generate reports with charts
docx	Create/edit Word documents
pdf	Generate professionally typeset PDF reports

Usage: pass the skill config to the Claude model object (up to 8 skills per request; type="custom" with skill_* IDs lets you use custom skills uploaded to your workspace):

from agno.agent import Agent
from agno.models.anthropic import Claude

agent = Agent(
    model=Claude(
        id="claude-sonnet-4-6",
        skills=[{"type": "anthropic", "skill_id": "pptx", "version": "latest"}],
    ),
    instructions="Create a concise, well-structured presentation.",
)

run = agent.run("Generate a three-slide presentation on renewable energy")
# Output is not on local disk: extract file_ids from run.model_provider_data,
# then download via Anthropic Files API (client.beta.files.download).

Production notes

Cloud skills run in air-gapped containers with no network access; outputs must be downloaded via the Files API (still beta); for pause_turn long-task interruption scenarios, prefer Anthropic's native SDK for continuation. Skills/Files APIs are unavailable via Amazon Bedrock and Google Vertex AI channels. This section is optional advanced material; all other examples in this book do not depend on direct Anthropic integration.

20.7 Engineering Checklist

• What deserves to be a Skill: stable processes, cross-Agent reusable methodologies (review criteria, writing templates, ops runbooks); "values that must be fetched fresh each time" should stay as Tools/RAG;
• Deterministic computation -> scripts: word-count stats, format conversion, lint checks — write them as scripts the model calls; far more reliable than asking the model to "compute in its head";
• Test your skills too: SKILL.md is part of prompt engineering; re-validate after switching models;
• Version governance: use metadata.version to track iterations; important changes go through Git PR review.

20.8 Chapter Summary

• Skill = SKILL.md + optional scripts/ + optional references/; six legal frontmatter fields; name must match the directory name;
• Progressive loading: summary always resident -> instructions on demand -> references on demand -> script execution; saves tokens significantly;
• Mount to Agent via Skills(loaders=[LocalSkills(...)]); pass to Team.skills and the leader holds it directly;
• Anthropic users can layer in cloud-provisioned skills (pptx/xlsx/docx/pdf) to produce Office files.

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. After registering Skills with an Agent, which tools does it automatically gain?

2. Regarding skill directory and SKILL.md naming rules, which is correct?

3. Why are Skills more cost-effective than "stuffing all methodology docs into the system prompt"?

4. What is the effect of passing skills= to a Team?

🛠️ Hands-On Exercises

1. Write a skill pack for a routine task of yours (e.g., daily-report or pr-review): include a compliant SKILL.md, one script, and one reference document; then intentionally make name invalid and observe the SkillValidationError message;
2. Mount to an Agent with debug_mode=True; observe the sequence "summary injection -> get_skill_instructions -> script execution" within a single task-matching request;
3. Mount the same skill library to a standalone Agent and to a Team leader respectively; compare the quality difference in their responses;
4. (Optional) If you have an Anthropic API Key, run the pptx example from 20.6 and complete the Files API download logic to obtain a real .pptx file.

Skills complete the "methodology-type" building blocks beyond "capability-type" tools. Next chapter turns toward safety and compliance: Chapter 21 · Human-in-the-Loop and Guardrails; production service deployment is covered in Chapter 23: AgentOS.