Skill Glossary
An agent skill is a packaged capability written for an agent rather than for an ordinary software user. It usually contains triggers, operating instructions, tool conventions, safety notes, and local knowledge for a repeatable class of work: using Canvas, handling Apple Notes, managing GitHub issues, querying email, transcribing audio, or maintaining the Dictionary.
Agent Skills is also the name of an open format documented at agentskills.io, described there as “a standardized way to give AI agents new capabilities and expertise.” Under its specification, a skill is a directory containing a required SKILL.md file — YAML metadata followed by Markdown instructions — and may also contain executable scripts/, on-demand references/, templates or other assets/, and additional resources. Supporting agent products can discover the name and description first, then load the instructions and resources progressively as the task requires them.
The general concept is older and broader than any one file format. The open format matters because it makes procedural knowledge more portable across compatible agent products. Compliance with the format, however, says nothing by itself about whether a particular skill is accurate, safe, or appropriate for the environment in which it will run.
A tool is something the agent can call. A skill is the larger recipe that tells the agent when to call it, how to interpret the result, and what local conventions matter. This distinction is important because many agent failures are not tool failures. The tool works; the agent used it in the wrong situation or without the surrounding judgment.
In the Dictionary’s architecture, skills are one way to turn tacit operator knowledge into durable system behaviour.
The neighbouring terms do different jobs. A skill tells the agent what procedure to follow; MCP gives it a standard way to reach tools and outside systems; RAG retrieves relevant documentary knowledge; and Agent Memory carries facts, decisions, and lessons across sessions. A skill may instruct the agent to use all three, but is not interchangeable with any of them.
Five practices for building a trustworthy skill
IBM Technology’s useful formulation treats a skill as procedural knowledge handed to an AI agent. Because the format can be little more than a Markdown file plus supporting resources, the engineering discipline sits in what the author chooses to put inside it.
- Treat the description as the trigger. An agent may initially see only a skill’s name and description. The description therefore needs to say both what the skill does and when the agent should use it. A precise skill that never triggers is merely well-filed literature.
- Build from real expertise. The valuable content is not generic advice the model already knows. It is the operator’s actual procedure, examples, review history, local conventions, and especially the gotchas discovered when reasonable assumptions failed. Every repeated human correction is a candidate for the skill.
- Spend context carefully. Keep the main instructions lean and place detailed references in supporting files that the agent reads only when required. This is progressive disclosure: enough information to act correctly now, with deeper material available on demand.
- Use deterministic scripts for fragile steps. Where several approaches can produce an acceptable result, instructions leave room for judgment. Where arithmetic, formatting, parsing, validation, or another exact operation must behave consistently, the skill should call tested code. The compact rule is: loose step, instructions; fragile step, code. Deterministic does not mean infallible; the script still needs tests.
- Vet a skill before running it. A downloaded skill may contain executable code with access to files, networks, or credentials. An open format does not make every package trustworthy. Third-party skills should be reviewed like any other software dependency: inspect the instructions, scripts, permissions, and external connections before execution.
The risk is not theoretical. In February 2026, Snyk’s ToxicSkills audit examined 3,984 public agent skills from ClawHub and skills.sh. It reported that 1,467 skills — 36.82% — contained at least one security issue, while 534 — 13.4% — contained at least one critical-level issue, a category covering prompt injection, malicious code, and suspicious downloads. The researchers separately confirmed 76 malicious payloads involving credential theft, backdoor installation, or data exfiltration. The technical report is worth reading with the percentages: “security issue” is broader than “malware,” but the confirmed malware means the supply-chain threat is not merely hypothetical.
The five practices point toward one larger principle: a good skill preserves the human’s domain expertise while giving the agent the routine work. The agent supplies fluency and repetition; the skill supplies the parts that should not be improvised anew each time.
Source: IBM Technology, “5 Best Practices for Building AI Agent Skills”, YouTube, 2026.