SSD Nodes Learn Hosting plans →
How to do am Matt ConnorBy Matt Connor · Updated 2026-11-14

Wetin Agent Skills Really Be and How Dem Work

Agent skill na folder with SKILL.md wey agent only read when task need am. See why e better than giant prompt and how e differ from MCP.

Wetin agent skill actually be

Agent skill na folder for disk wey get file wey dem call SKILL.md inside am. That file get name, short description, and instructions wey dem write for plain markdown. Agent dey load the description when e start, and e go read the instructions only when your request match that description or you call the skill by name. Almost everything else about skills follow from those two sentences.

The folder fit hold more than the one file. Agent Skills specification name three optional directories: scripts/ for code wey agent dey run, references/ for documents wey e dey read when e need dem, and assets/ for templates and data. None of dem compulsory. Folder wey get only SKILL.md inside am na complete skill.

restore-drill/
  SKILL.md
  references/retention-policy.md
  scripts/verify_snapshot.sh

Description na the part wey people dey underrate. Na the only text wey agent see before e decide whether to open the skill at all, so e need explain wetin the skill dey do and when to use am, with the kind words wey person go really type.

Why skill dey cost almost nothing until person use am

Na this argument make the format worth understanding, and e dey about context, no be features. Loading dey happen for stages, and the specification call am progressive disclosure.

For startup, the agent load name and description of every installed skill, and nothing else. The Agent Skills specification estimate am at roughly 100 tokens per skill (published guidance, as of October 2026). If you install twelve skills, you don spend about the context wey one long paragraph go use.

When request match one description, the agent read the body of that one SKILL.md. The spec recommend say make the body stay under 5,000 tokens and the file under 500 lines. Files for references/ and scripts/ still cost nothing at this point. Reference file go load only if the instructions send the agent go am. Bundled script different again: the agent run am through the shell, so the script source no enter the context window; na only the output enter.

Now compare am with the thing wey people dey reach for first: one enormous prompt. Every line for system prompt or always-on instructions file dey cost for every request and every session, whether the task need am or not. E also dey compete for attention with the real question. Ten thousand tokens of standing instructions na bill you go pay even when you only ask wetin time be. Twelve skills cost around 1,200 tokens before activation, but loaded instructions fit remain for context for later tasks inside the same conversation. Na the whole case for skills be this, and na why small library better pass longer prompt.

One caveat dey catch people. For Claude Code, once skill load, e body remain for the conversation across later turns. So long SKILL.md na recurring cost, no be one-time cost. Compaction fit trim or drop loaded skill content. Moving detail enter references/ no be just tidiness. Na the mechanism dey work as e suppose.

Agent skill no be tool call

Tool, wey dem dey also call function call, na something wey model fit invoke. Harness go send model one schema: name, description, and shape of the arguments. Model go emit call, your code go run am, then result go come back as message. Tools dey do things. Both sides of this exchange belong to the harness, the program wey dey run the loop around the model, and na this same thing dey read your skill descriptions when e start and decide when to open one.

Skill no dey execute anything by itself. Agent go read am, then act with the tools wey e already get. Claude Code dey accept arguments when dem invoke skill and insert dem inside its instructions through placeholders like $ARGUMENTS. Wetin skill fit do na to tell model which tools to use, the order to use dem, and wetin to check afterwards. To hand job give second agent na the clearest example: one Claude Code session fit already send message to another, and na for skill you write when e make sense to do am and wetin to send.

The short version be say: tool dey give agent new ability, while skill mostly dey give am judgment about abilities wey e already get. When skill add ability, e dey do am through bundled script wey agent run with the shell wey e already get. If one step must produce exact, validated result every time, you need tool or script. If one step need the same thinking applied consistently, you need skill. Skill fit be only judgment and still be the one wey you dey reach for most, as Ponytail, wey dey push coding agent to make the smallest change wey go work show: e add no new capability and only change how agent dey use the ones wey e already get. That judgment fit point the other way too, and the unlazy skill, wey dey walk through a Depth Tree to stop agent from declaring job done too early na the same trick wey dem aim at thoroughness instead of restraint.

Agent skill no be MCP server

MCP (model context protocol) na protocol wey dey connect agent to outside system. MCP server na process wey dey run, speak that protocol, and expose tools to agent. E normally need configuration, credentials, plus either local command or network endpoint. Skill na folder wey get markdown file inside. No process, no port, and no protocol dey involved.

The context cost dey different for the same reason. Every tool wey MCP server expose get name, description, and argument schema. For client wey load dem upfront, all these details dey inside request throughout the whole session, whether you use dem or not. Claude Code no longer work like that by default: as of October 2026, tool search dey enabled out of the box, so na only tool names and server instructions dey load when session start. The full definitions go arrive when Claude search for dem. Skill wey dey at rest na one line of text.

The two dey complement each other, and the strongest setups dey run both. MCP server provide the access. Skill provide the procedure: which tools to call for your team real workflow, the order to call dem, and wetin good result suppose look like. If na you dey host your own, how to run MCP servers on a VPS cover that side.

An agent skill no be system prompt or AGENTS.md

Both na instructions for markdown, so this confusion make sense. The difference na when dem load. System prompt and project instructions wey load for startup dey always active; nested AGENTS.md and CLAUDE.md files load when agent dey work inside their directories. Skill na on-demand. Claude Code output styles dey for the always-on extreme, because choosing one dey edit the system prompt itself. So e dey shape every reply for the session, including replies wey no skill ever touch.

The test na one question: if you ignore this paragraph for task wey no concern am, e go wrong? House style, build command, and branch naming rule apply to every task, so dem belong for always-on file, where loading dem every time na the main point. Release checklist wey you run twice every month no apply to every task, so e belong for skill. When one section for your always-on file don grow enter numbered procedure, na signal say you should move am.

Those files get their own conventions wey you need handle correctly. See wetin belong inside AGENTS.md and wetin belong inside the human file and a design.md wey explain the structure of a codebase for the two wey we use.

Wetin minimal skill look like

For Claude Code, personal skills dey inside ~/.claude/skills/<name>/SKILL.md and dem apply to all your projects for that machine, but dem no apply to Cowork or cloud sessions. Project skills dey inside .claude/skills/<name>/SKILL.md and git go commit dem, so your team go get dem too; cloud threads for Claude project no load dem. GitHub Copilot and VS Code dey read project skills from .github/skills/ and .agents/skills/, plus .claude/skills/. The file wey dey inside na the same file.

mkdir -p ~/.claude/skills/restore-drill
---
name: restore-drill
description: Run a restic restore drill and report what was recovered. Use when the user asks to test backups, verify a restore, or check that a snapshot is readable.
---

# Restore drill

1. Run `restic snapshots` and pick the newest snapshot for the host in question.
2. Restore it into a scratch directory under `/tmp`, never over live data.
3. Compare the restored file count and total size against the snapshot summary.
4. Report the snapshot ID and anything that failed to restore.

If `restic snapshots` reports that it cannot open the config file, stop and report the full error instead of guessing the cause.

Na complete skill be this. Directory name go become the command wey you type, so this one na /restore-drill. For Claude Code, /skills menu dey list wetin dem install, and na the fastest way to confirm say e pick the file. If e no dey that menu, check the names first: the file name must be SKILL.md, and Agent Skills specification require make the name use lowercase letters, digits, and single hyphens, with the same name as the directory. You fit write this same process as procedure wey your agent fit run again. E go naturally pair with scheduled restic backups for VPS, where say backup dey run no mean say backup fit restore.

When skill suppose be script instead

Any step wey get one correct answer every time suppose be script, and make the skill remain just few lines wey talk when to run am and how to understand the output. Get two reasons, and both of dem practical.

First, script source no dey enter the context window. A 300 line parser go cost you only its output, and nothing more. But if you write the same logic as markdown instructions, e full length go cost every time the skill load.

Second, script dey give the same answer two times. If you ask model to derive the same log parsing rule again for every run, e fit change small on a bad day. You no go notice until two numbers no match.

So divide the work by type. "Parse the CSV and print every row where the total no match the line items" na script. "Look the rows wey script print and explain which ones look like data entry mistake" na skill instruction. Keep judgment for markdown and deterministic work for code. Na the same discipline as building a loop wey agent fit run without you watching.

Why my skill no dey ever trigger?

Because its description dey talk wetin the skill dey do, but e no dey talk when to use am. Na that one line agent get to match against your request. “Helps with database work” no match any particular thing. “Runs a schema migration against the staging database. Use when the user asks to migrate a table, add a column, or change a schema” get the words wey person fit actually type, so e go fire.

The opposite problem na skill wey dey trigger all the time. Description like “Use for any code changes in this repository” match everything, so body load for every task and later remain inside conversation for other turns. Make the description narrow reach the exact case wey you mean. For Claude Code, you fit also set disable-model-invocation: true inside frontmatter. That one stop automatic loading and keep the skill available when you type its name.

The third problem na skill wey dey duplicate a tool. Instructions wey tell agent to curl an API wey its MCP server already exposes, or to grep through files when the harness get search tool, give you slower path plus two sets of instructions wey fit disagree. Delete the duplicate and describe the intention instead.

No guess which one of the three na your own. Run the same prompt twice for a fresh session: once with the skill available and once with am switched off. Then compare the answers. The fresh session matter because the session where you write the skill already get everything wey the skill talk, and this one fit hide gaps for the written version. Anthropic's skill-creator plugin automate this comparison inside Claude Code. E also generate prompts wey suppose and no suppose fire the skill, then measure how often each one fire. If the skill load but agent still no do wetin e talk, description no be your problem. Check the reasons agent dey ignore instructions wey e don already read next.

Na format for one vendor, or na standard?

Anthropic publish the format for late 2025, then release am as open standard wey dey hosted for agentskills.io. For October 22, 2026, Anthropic announce say dem donate Agent Skills to the Agentic AI Foundation under the Linux Foundation. As of October 2026, that specification define the required name and description fields, the optional license, compatibility, metadata and allowed-tools fields, the three optional directories, and the staged loading behaviour. E also ship with reference validator, so skills-ref validate ./my-skill fit check folder against the spec before you share am.

The client list na the real signal. Claude Code, Cursor, OpenAI Codex, Gemini CLI, GitHub Copilot, VS Code, Goose, OpenHands and opencode, among others, dey read the same folder. Microsoft publish its own skills for the format at github.com/microsoft/skills, and e ship desktop tool wey dem call Skill Recorder. The tool dey watch as you do task once, reconstruct am as intent plus ordered steps, then write the result as skill. If vendor build recorder wey output format belong to another specification, e show say the format don stop to be feature for only one product.

Wetín to write first

No plan library from the start. Wait until you notice say you don paste the same instructions for chat the third time, then move that text go one SKILL.md and delete the paste. Repetition wey you don already experience na the only reliable signal say the skill worth keeping. Search procedure na good first one, and one search skill wey your own SearXNG instance support show the pattern.

Two habits dey help keep the library healthy. Read every skill wey you no write yourself before you install am, including scripts, because skill na instructions wey your agent go follow and code wey e fit run: treat am like software wey come from stranger. And no keep credentials inside the folder, because skill na text file wey people fit commit and share. How to keep secrets away from your agents explain where those values suppose stay instead, and road map for learning agents this year arrange skills together with the rest of the setup.

FAQ

Wetin be di difference between agent skill and MCP server?

An MCP (model context protocol) server na process wey dey run and expose tools to agent through protocol. So e need configuration and credentials, and im complete tool definitions dey use context for the whole session unless client defer dem, as Claude Code now dey do by default. An agent skill na folder wey hold one SKILL.md file. E no get process or protocol, and e cost around 100 tokens until agent decide to read am. Use MCP server to give agent access to system. Use skill to tell agent the procedure for using that access well. Plenty setups dey run both.

Agent skills dey work only with Claude Code?

No. Anthropic develop the format, then release am as open standard for agentskills.io. The same folder dey read by Cursor, OpenAI Codex, Gemini CLI, GitHub Copilot, VS Code, Goose, OpenHands and other clients. Wetin different na where each client dey look and which extra frontmatter fields e understand. Claude Code dey read ~/.claude/skills/ and .claude/skills/, while GitHub Copilot and VS Code dey read .github/skills/, .claude/skills/ or .agents/skills/ for the repository. The SKILL.md file itself dey move between dem unchanged.

How many skills I fit install before e start slow things down?

The main limit na startup budget, no be number. Each installed skill add im name and description, roughly 100 tokens according to the specification published guidance. So thirty skills cost about 3,000 tokens before you use any of dem. The first thing wey dey get worse na matching, no be speed. If many skills get descriptions wey overlap, e go harder for model to choose the correct one. Write descriptions wey no overlap, and delete skills wey you don stop to use.

Make this instruction dey inside skill or AGENTS.md?

Ask whether e apply to every task for the repository. Build commands, house style and naming rules apply to all tasks, so dem belong inside the always-on file, where loading dem every time na the main purpose. Procedure wey you run sometimes, like release checklist or restore drill, suppose be skill, so e go cost only im one-line description before activation. Once e load for Claude Code, im instructions remain for the conversation across later turns, including unrelated tasks. A section of AGENTS.md wey don grow into numbered steps usually na skill wey dey wait to move.

Dis article help you?