Skip to content

Skills: SKILL.md ​

After reading this section, you will be able to write a SKILL.md and have your Agent load it automatically when needed. We will actually run through this using the "write a weekly report" skill.

What a skill is ​

Tools answer "what can be done" (reading files, running commands), while skills answer "how this thing should be done".

It's like an operations manual a company gives to new employees: which subheadings a weekly report should have, no fabrication, what filename to save it as... These are not capabilities, they are methods. Write the methods into a file, and the Agent can read it when needed and know how to do it.

Agent Skills is exactly such a format: a skill is a folder containing a SKILL.md (a YAML metadata block at the top, followed by steps written in Markdown), and it can also include scripts, reference materials, and so on.

Background: Anthropic released Skills on 2025-10-16, and published Agent Skills as an open standard on agentskills.io on 2025-12-18. On 2026-11-4, the project passed its governance document, which states it will be established as a project under the Linux Foundation, with the Apache-2.0 license.

Write a SKILL.md ​

Our "write a weekly report" skill lives in skills/weekly-report/SKILL.md:

markdown
---
name: weekly-report
description: Organize the work records in a folder into a weekly report
---

# Write a weekly report

1. Use list_dir to see which record files are in the given folder, and use read_file to read them one by one.
2. Organize them under four subheadings: "Completed this week / In progress / Planned for next week / Need help", one sentence per item, stating which day it happened.
3. Do not fabricate content not present in the records; for subheadings with nothing in the records, write "None".
4. Use write_file to write the result to 周报.md, and show the full text to the user before writing.

The two required fields in the spec:

FieldRequirement
nameNo more than 64 characters, using only lowercase letters, digits, and hyphens; must be identical to the folder name
description1 to 1024 characters, clearly stating "what it does" and "when to use it"

Optional fields include license, compatibility, metadata, and the experimental allowed-tools.

Progressive disclosure: no need to read everything at once ​

If there are dozens of skills, stuffing them all into the prompt is wasteful. The spec's approach has three levels:

  1. Read only metadata at startup: the name and description of each skill, roughly 100 tokens;
  2. Read the body only when needed: the entire SKILL.md, recommended to be under 5000 tokens and 500 lines;
  3. Read resources only when needed: the bundled scripts and reference files.

Make your own Agent support skills ​

The spec website has a dedicated article, "Add Skills support to your Agent". The core comes down to two things: put the skill catalog into the system prompt, and provide a way to read a skill. Our implementation:

python
def load_skills():
    skills = {}
    for f in sorted((HERE / "skills").glob("*/SKILL.md")):
        meta = dict(re.findall(r"^(\w+):\s*(.+)$", f.read_text(encoding="utf-8").split("---")[1], re.M))
        skills[meta["name"]] = (meta["description"], f)
    return skills

SKILLS = load_skills()

def load_skill(name):                               # 用到时才把完整说明读进来(渐进式披露)
    return SKILLS[name][1].read_text(encoding="utf-8") if name in SKILLS else f"没有叫 {name} 的技能"

SYSTEM = ("……\n可用技能(需要时先 load_skill):\n"
          + "\n".join(f"- {n}:{d}" for n, (d, _) in SKILLS.items()))

Then add load_skill to the tool list. The spec also offers two suggestions: the tool's name parameter should ideally be an enum (allowing only existing skill names) to prevent the model from inventing nonexistent skills; and when there are no skills at all, don't include an empty catalog or register this tool. Additionally, .agents/skills/ is becoming a common skill catalog convention across different clients.

Run it ​

bash
python agent.py "用写周报的技能,把 worklog 文件夹整理成周报"

Our actual run on qwen3:8b:

text
  [1] load_skill({"name": "weekly-report"})
  [2] read_file({"path": "/worklog/11-16.txt"})
  [3] list_dir({"path": "./worklog"})
  [4] read_file({"path": "./worklog/11-16.txt"})
  [5] read_file({"path": "./worklog/11-18.txt"})
  [6] read_file({"path": "./worklog/11-20.txt"})

Agent: Weekly report results:
# Weekly report
## Completed this week
- Monday: Fixed a style misalignment on the login page in Safari
……
## Need help
- None

After you confirm the content, I will generate the 周报.md file.

Note that it did the two things written in the skill: all four subheadings present, writing "None" where nothing was recorded; and showing you the full text before writing the file. None of this is enforced by code—it's all written in the SKILL.md.

Quiz timeWhat's the difference between skills and tools?

Check yourself ​

  • I can state the two required fields of a SKILL.md and their requirements
  • I can explain the three levels of progressive disclosure
  • I got the weekly-report skill running and wrote a skill of my own

The next chapter connects to the ecosystem: MCP: Write a server and connect it.

gaodong.aiAboutPrivacyContact

Independent tutorials, not affiliated with any product mentioned. Product names and trademarks belong to their owners. Check official pages for prices and policies.