Wetin Agent Skill Really Be and How E Dey Work

Wetin agent skill really 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 wetin you request match that description. Almost everything else about skills come from those two sentences.

The folder fit get more than that 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 cost almost nothing until you use am

Na this argument make the format worth understanding, and na context concern, not features. Loading dey happen in 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 around 100 tokens per skill (published guidance, as of August 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 body no pass 5,000 tokens and make file no pass 500 lines. Files for references/ and scripts/ still no cost anything 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 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 still dey compete for attention with the real question. Ten thousand tokens of standing instructions na bill wey you go pay even when you only ask wetin be the time. Twelve skills cost around 1,200 tokens when dem dey idle, and dem expand only for the one task wey need dem. Na the whole case for skills be this, and na why small library better pass longer prompt.

One caveat dey catch people. Once skill load, e remain for context for the rest of the session. So long SKILL.md na recurring cost, no be one-time cost. Moving detail go references/ no be just tidiness. Na the mechanism dey work as e suppose work.

Skill for agent no be tool call

Tool, wey dem dey also call function call, na something wey model fit invoke. Harness go send schema give model: 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.

Skill no dey execute anything by itself. Agent go read am, then act with the tools wey e already get. Model no fit pass arguments give skill the same way e dey pass arguments give tool. Wetin skill fit do na to tell model which tools to use, the order to use dem, and wetin to check afterwards.

The short version be say: tool dey give agent new ability, while skill dey give am judgment about ability wey e already get. If step must produce exact, validated result every time, you need tool or script. If step need make the same thinking apply 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 no add any new capability; e only change how agent dey use the ones wey e already get.

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, dey speak that protocol, and dey expose tools to agent. E usually need configuration, credentials, and 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 differ for the same way. Every tool wey MCP server expose get name, description, and argument schema. By default, dem dey inside request for the whole session, whether you use dem or not. Some clients don start to fetch tool schemas on demand, but loading dem upfront still na the normal case. Skill wey dey idle na one line of text.

The two dey complement each other, and the strongest setups dey run both. MCP server dey provide access. Skill dey provide procedure: which of those tools your team workflow really need call, the order to call dem, and how good result suppose look. If na you host am, running MCP servers for VPS cover that side.

An agent skill no be system prompt or AGENTS.md

Both na instructions for markdown, so this confusion make sense. AGENTS.md, CLAUDE.md and system prompt dey always on. Skill na on demand.

The test na one question: if you ignore this paragraph for task wey no relate to am, e go wrong? House style, build command and branch naming rule apply to every task, so dem belong for always-on file, where dem go load every time. 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 reach numbered procedure, na signal say you suppose move am.

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

Wetin minimal skill dey look like

For Claude Code, personal skills dey inside ~/.claude/skills/<name>/SKILL.md and dem apply to all your projects. Project skills dey inside .claude/skills/<name>/SKILL.md and git go commit dem, so every person and every agent wey dey work for that repository get dem. GitHub Copilot and VS Code dey read workspace skills from .github/skills/ instead. 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` prints `Fatal: unable to open config file`, the repository path or the password is wrong. Stop and report that instead of guessing.

Na complete skill be this. The directory name become the command wey you go type, so this one na /restore-drill. For Claude Code, /skills menu dey list wetin don install, and na the quickest way to confirm say e pick the file. If e no dey that menu, one name dey wrong: the file must answer to SKILL.md, and the directory name must use lowercase letters, digits and single hyphens. You fit write this same process as procedure wey your agent fit run again; e go naturally join scheduled restic backups for VPS, because backup wey run no be the same thing as backup wey 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 trigger?

Because e 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 actually dey type, so e go trigger.

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

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

No guess which of the three problems you get. Run the same prompt two times for fresh session: once with the skill available and once with am switched off. Then compare the answers. Fresh session matter because the session where you write the skill don already contain everything wey the skill talk, and this one fit hide gaps for the written version. Anthropic's skill-creator plugin dey automate this comparison inside Claude Code. E dey also generate prompts wey suppose and no suppose trigger the skill, and measure how often each one trigger.

Na this one vendor format or standard?

Anthropic publish the format for late 2025, then release am as open standard wey dey hosted for agentskills.io. As of August 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 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. Vendor wey dey build recorder whose output format belong to another party specification na good sign 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. E tool definitions normally dey occupy context for di whole session, whether dem use am or not. An agent skill na folder wey hold one SKILL.md file. E no get process and e no get protocol. E dey cost around 100 tokens until agent decide to read am. Use MCP server to give agent access to system. Use skill to tell agent di procedure for using dat access well. Plenty setups dey use both.

Agent skills dey work only with Claude Code?

No. Anthropic develop di format, then release am as open standard for agentskills.io. Di same folder dey read by Cursor, OpenAI Codex, Gemini CLI, GitHub Copilot, VS Code, Goose, OpenHands and other clients. Wetin differ 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/ for di repository. Di SKILL.md file itself dey move between dem without change.

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

Di main limit na startup budget, no be number. Each installed skill add its name and description, roughly 100 tokens according to di specification published guidance. So thirty skills cost about 3,000 tokens before you use any of dem. Wetin spoil first na matching, no be speed. Plenty skills wey get descriptions wey overlap make am harder for model to pick di correct one. Write descriptions wey no overlap, and delete skills wey you don stop to use.

Dis instruction suppose dey inside skill or AGENTS.md?

Ask whether e apply to every task for di repository. Build commands, house style and naming rules apply to all tasks, so dem belong inside di always-on file. Na there loading am every time dey make sense. Procedure wey you run sometimes, like release checklist or restore drill, suppose be skill. That one no go cost anything for tasks wey no need am. Section for AGENTS.md wey don turn to numbered steps usually na skill wey dey wait make you move am.