Loading...

Loading...

Agent Skills: Teach Your AI Once, Reuse Forever
Loading like and share buttons...
#agentskills#skill.md#claudecode#cursor

Agent Skills: Teach Your AI Once, Reuse Forever

Vibki AI
Vibki AI
Nov 5•5 min read

Have you ever wondered how an AI coding agent does a task right every time without you explaining it again and again? Agent Skills fix that: a skill is a SKILL.md file the agent loads on its own when a task matches. By the end you will have your first skill, written once, reused forever.

Are skills really as important as everyone says?

Let's test the claim on one job: "write the release notes", meaning merged PRs since the last tag, three headings, our tone. We retype that every session, because each one starts blank.

Be honest, how many times did you explain the same task this month?

The obvious fix is CLAUDE.md, the instructions file the agent reads at the start of every session. Paste it there and every unrelated session pays for it in context window. So the hype around Agent Skills has a point. But what is a skill, exactly: a file, a plugin, a prompt?

So what is a skill, a markdown file?

Yes. Our release-notes skill, all 8 lines:

šŸ“Markdown
1
2
3
4
5
6
7
8
---
name: release-notes
description: Write the release notes for the next version from the merged PRs since the last tag. Use when the user asks for release notes, a changelog, or what did we ship.
---
1. Run `scripts/changes_since_tag.sh` and use only its output as the list of changes.
2. Sort the lines under three headings: Added, Fixed, Improved.
3. Match the tone in `references/tone.md` and fill `assets/release-template.md`.
4. Show the result and ask before committing it.

A skill is a folder with a SKILL.md inside. The part between the --- lines is the frontmatter, a small YAML metadata block, and the Agent Skills specification requires two fields there: name (1 to 64 characters, lowercase, digits and hyphens, equal to the folder name) and description (up to 1024 characters, what it does AND when to use it). Below it, the Markdown body with the steps. The folder lives in .claude/skills/, .cursor/skills/ or .agents/skills/ and works in Claude Code, Cursor and antigravity.

Can a markdown file run a script?

Not by itself, but it can tell the agent to. Next to SKILL.md the spec allows scripts/ (code the agent runs), references/ (docs it reads on demand) and assets/ (templates it copies). Step 1's script, four lines of shell:

1
2
3
4
#!/bin/sh
since=$(git describe --tags --abbrev=0)
echo "since: $since"
git log --merges --format="- %b" "$since..HEAD" | grep .

Run in a scratch repo with three merged PRs:

šŸ“„Text
1
2
3
4
5
$ sh .claude/skills/release-notes/scripts/changes_since_tag.sh
since: v1.4.0
- Speed up post list query (#44)
- Fix login redirect loop (#43)
- Add dark mode toggle (#42)

The exact part, which PRs shipped, comes from git, never from memory, and the body stays four lines. We typed "what did we ship in this release?" And then he run the skill.

Wait, the agent only reads the label?

This is progressive disclosure, in the spec's words: loading in three tiers. At startup the agent reads only the name and description of every skill (about 100 tokens each), the body when it decides a task matches, the bundled files when a step needs them. Two things follow. The match is a judgment call, not a lookup: the model compares your request to the description, so a vague description gets skipped even when the task fits. That is why the description must hold the words you actually type: "release notes", "changelog", "what did we ship". And when you don't want to rely on the match at all, call the skill by name: /release-notes loads it directly.

What makes a good Agent Skill, and when is it too big?

The spec's limits are the ceiling: SKILL.md under 500 lines, body under about 5000 tokens. Four habits keep our release-notes skill well below:

  • Description in your words: "what did we ship", not "release management automation".
  • Steps as commands and checks: "every change comes from the script, never from memory".
  • Exact things in scripts/: prose can be paraphrased, a script cannot.
  • Split before it hurts: when the body starts holding the deploy checklist, make it two skills or move the long part into references/, and let skills-ref validate check the frontmatter.

Conclusion

Yes, but not for the reason the hype gives. A skill is a label the agent reads at startup and a drawer it opens when the task matches, with the release-notes script inside. It sits next to your always-on rules (CLAUDE.md, .cursor/rules) and does not replace them. Written once, reused forever.

Choose one task you explained twice, turn it into a SKILL.md whose description uses the words you type, then ask for it without naming the skill. Try it out!

Next time, we'll dive into AGENTS.md and CLAUDE.md, the file every agent reads first.

Sources: Agent Skills specification, Claude Code docs, Agent Skills, Cursor docs, Skills

Enjoyed this post?

Get the next one in your inbox. No spam, unsubscribe any time.

Comments

0 comments

Enter your comment. Maximum 2000 characters.

No comments yet. Be the first to share your thoughts!
Vibki logo wave icon
Vibki Surfing Bot
Vibki

Vibki is a developer blog where you will find tutorials on web development and AI integration. Each article is crafted with clear explanations, practical examples, and ready-to-use source code.

Talk to me
Copy email
LinkedIn
GitHub
Dev.to
Privacy Policy