Skills.sh, agent skills as files

Skills.sh, agent skills as files

Skills.sh is a registry and a command line tool for distributing skills to coding assistants. A skill is a directory holding a markdown description file, and installing one reduces to a single command that copies it into your project.

The tool appeared on the twentieth of January 2026, and its idea is that knowledge of how to do something in a particular project or with a particular library should stop living in people's heads and in individual conversations.

What a skill actually is

Worth settling immediately, since the name suggests something more elaborate than it is.

A skill is a text file with a header holding a name and a description, and a body stating how to perform a given task. There is no code executed by a system, no plugin, and no runtime layer. There is an instruction the model reads.

The consequence cuts both ways and both sides deserve knowing.

The advantage is simplicity. Writing a skill means writing a document, so anybody who can describe a procedure can do it. There is no interface to learn.

The drawback is the same thing. Since this is an instruction the model reads, installing one means putting somebody else's text into your assistant's context. We return to that below, since it is the most important thing in this whole text.

The format and how it works

A skill lives in a directory holding a description file, to which supporting material can be added: examples, templates, configuration fragments.

The file's header carries two mandatory things: a name and a description. The description matters more than it looks, since it decides when the assistant reaches for that skill.

---
name: database-migrations
description: Use when adding or changing a table in the database. Covers how
  to generate a migration, how to name it, and what to check before merging.
---

# Database migrations

1. Change the model in prisma/schema.prisma
2. Run pnpm prisma migrate dev --name change-description
3. Review the generated SQL in prisma/migrations, especially DROP and NOT NULL
4. Add a data migration if the column cannot be null

A sentence stating plainly in what situation to apply the skill works better than one merely stating what it concerns. A description opening with "Use when..." is more effective here than one opening with "Documentation for...".

Installation happens through a command run without installing anything permanently. The tool fetches the skill and writes it where your assistant looks for context, and that location depends on the tool.

.claude/skills/<name>/SKILL.md
.agents/skills/<name>/SKILL.md
.windsurf/skills/<name>/SKILL.md

The format is the same everywhere, a SKILL.md file with the same header, and only the target directory differs. Plenty of tools, Cursor, Codex, and Gemini among them, in fact share one common directory. By default a single canonical copy is created and the individual tool directories hold symlinks to it, so a fix in one place shows up everywhere; a separate flag forces independent copies where symlinks do not work. That is the entire value of this tool reduced to one paragraph.

That last point is the idea's core. Every assistant looks for additional context somewhere else, and this tool knows those places and lays the skill out across them for you. The same skill lands where it belongs regardless of whether you work in Cursor, in Windsurf, or in a terminal tool.

Several dozen tools are supported: the table in the project repository lists seventy six identifiers and it is the authoritative source, since lists elsewhere run shorter. Check yours against it before deciding, since the table also gives the path the skill will land under.

What this suits

Three uses make sense, and outside them this is a solution looking for a problem.

The first is project conventions invisible in the code. Naming style, an error handling pattern, a rule stating that the service layer never reaches the database directly. A model draws conclusions from what it sees, so a convention departed from over two years gets read as both versions at once.

The second is repeatable procedures. How to add a new job type, how to generate a migration, how to cut a release. Those are things one person on a team knows and explains from scratch every time. The raw material for such a skill comes from daily work: the instruction that landed on the first try is worth recording, because reconstructing it from memory two weeks later rarely works. That is one of the habits described in Get Shit Done, where a task is sized so its result can be reviewed in a quarter of an hour, since code produced faster than it can be read is debt rather than progress.

The third is fast moving libraries. A model knows the state as of its knowledge cutoff, so a skill describing a tool's current usage is sometimes the difference between working code and retired code.

Outside those three the value drops. A skill repeating what a library's documentation already says adds text to the context for no gain, and context is a limited resource.

Security, the most important part

Since a skill is an instruction the model reads, installing one from an unknown source means installing somebody else's prompt into your own tool.

That sounds mild and is not. A coding assistant has access to your repository, runs commands, and makes changes. An instruction telling it to also append something to a configuration file or send an environment variable's contents to a named address looks entirely ordinary inside a markdown file.

The difference from an ordinary package is that there the code can be read and somebody usually does, while here the content is prose easy to scroll past. Add to that the fact that the instruction need not be overt: a fragment tucked into supporting material or phrased as part of a procedure works just as well.

Three practical rules apply and deserve taking seriously.

Read before installing. It is a text file, so reading it takes a minute, and that minute is the main safeguard here. The registry does keep a separate tab with audit results gathered from three external services, but a handful of entries from the very top are checked while the rest show a pending status. The vendor itself states that it guarantees neither the quality nor the security of every entry. It also pays to check what exactly appeared in the repository rather than trusting that the installer added only what it promised.

git status --porcelain
git diff --cached -- '*/SKILL.md' '*.mdc'
grep -rInE "curl|wget|base64|process\.env|ANTHROPIC|AWS_|_TOKEN" .claude/skills/

That last command will not catch everything, since an instruction written in prose need contain none of those words. It does catch the most blatant cases, and those occur more often than sophisticated ones.

Install from sources you recognise. A skill from the author of a library you use is a different matter from a skill from an account created last week.

Treat it like a dependency in code review. A skill entering the repository should pass review like any other file, since it affects what the assistant does with your project.

The registry's scale and what follows

The figures quoted for this registry impress: hundreds of thousands of entries within its first six months, with the most popular skills counted in millions of installs. Treat them as an order of magnitude, since they come from third party compilations rather than an audit.

More important than the numbers is what such scale implies when choosing.

First, most entries have been reviewed by nobody. A registry with a low barrier fills quickly, and the ratio of considered work to quickly generated work resembles any open catalogue.

Second, install count measures visibility rather than quality. A skill promoted early accumulates installs for months, including from people who installed it and never used it.

Third, duplicates are the norm. A dozen skills describing the same library differ in details and in date, and picking the best one requires reading them, meaning exactly what you should do before installing anyway.

The practical route: look for skills published by the authors of the tool they concern, and for the rest read the contents and check the date. A skill describing a library that changes quarterly, written a year ago, is worse than none, since the model will treat it as a reliable source.

Skills in a team

This mechanism's greatest value appears once it stops being one person's private collection.

A shared skill set for a team means everybody works from the same rules. Without it every person receives code in their own style, since every person holds a different context set, and the project drifts faster than anybody notices.

The sensible practice keeps team skills in the project repository so they arrive with the code. Somebody joining the project receives them automatically, and changing a rule passes review like any other change.

For that to work, the skills directory has to be tracked by version control rather than excluded along with the rest of the tool settings. That distinction is worth writing down explicitly.

.claude/settings.local.json
.claude/cache/
!.claude/skills/

The exclamation mark on the third line is the whole point. Without it an entry excluding the tool directory takes the skills with it, and then everyone on the team has their own set, invisible to the others.

Settle who writes them and when, too. A rule added after a problem's second occurrence is cheap and effective, while trying to describe everything up front produces a document nobody reads and which misleads six months later.

The last item concerns review. A skill entering the repository deserves reading as carefully as code, and not only for security reasons. A rule phrased ambiguously leads the model astray systematically, and finding the cause takes longer than writing it properly the first time.

Skills.sh against the alternatives

The distinction between the first two rows matters most here and gets confused. A skill tells a model how to do something. A server speaking the tool protocol gives a model the ability to do something: query a database, send a message, read a file. One is knowledge, the other is capability.

The third row deserves consideration before reaching for a registry. A rule concerning only your project need not be a package. A guidelines file in the repository works the same way, passes review with the code, and requires installing nothing.

The registry's value appears with knowledge portable between projects: how to work with a particular library, a procedure your company applies across ten repositories. There a package is the right form.

Writing your own skills

A few things separate a useful skill from one that clutters the context.

Write the header description as a condition for use rather than a topic. A sentence stating in what situation to reach for the skill decides whether the model uses it when it should.

Write the body as a procedure rather than an essay. A model needs steps and examples, not a historical introduction. A short code fragment showing correct usage works better than a paragraph describing the same thing in words.

Limit the length. A skill occupies context every time it gets used, so a two thousand word document costs on every task. Splitting it into several smaller ones, reached separately, is worthwhile.

State versions. A skill describing a library without naming the version it concerns misleads rather than helps six months later.

Test on a real task. A skill that looks good and changes no outcome is a cost rather than a gain, and that gets settled only by comparing with it and without.

Common mistakes

The first is installing a skill without reading its contents. It is an instruction for a tool with access to your repository, so a minute of reading is the only safeguard here.

The second is installing everything that looks useful. Every skill occupies context, and a model with twenty descriptions to weigh chooses worse than one with three.

The third is packaging rules concerning one project. A guidelines file in the repository does the same thing, passes review with the code, and requires no installation.

The fourth is confusing this with the tool protocol. A skill provides knowledge; a tool server provides the ability to act, and one does not replace the other.

The fifth is a description stating what the skill concerns rather than when to apply it. The model will not reach for it at the right moment despite it being installed.

The sixth is omitting versions when describing a library. After a few months the skill describes usage that no longer applies and worsens the result rather than improving it.

The seventh is judging a skill by its install count. That number speaks to visibility rather than quality, and an early promoted entry collects it from people who never used it too.

The eighth is keeping team skills outside the repository. Somebody joining the project never receives them, and changing a rule passes no review, so the team works from different context sets.

FAQ

What is a skill in this sense?

A directory holding a markdown file whose header carries a name and a description, with a body stating how to perform a given task. There is no code and no runtime layer; there is an instruction the assistant's model reads.

Which tools support this?

Seventy six identifiers listed in the table in the project repository, from terminal assistants to separate editors. Lists elsewhere run shorter, so check that table before deciding: it also gives the directory the skill will land in.

Is installing skills safe?

It requires the same caution as installing dependencies, and arguably more. A skill is an instruction for a tool with access to your repository that runs commands, so read the contents before installing and reach for sources you recognise.

How does this differ from MCP servers?

In the kind of thing they provide. A skill gives a model knowledge of how to do something. A server speaking that protocol gives the ability to do something, querying a database for instance. One does not replace the other and a typical project uses both.

When does an ordinary guidelines file suffice?

When the rule concerns this project alone. A file in the repository works the same way, passes review with the code, and requires no installation. A registry makes sense for knowledge portable between projects.

The format documentation sits on the vendor site, and the tool's code in the GitHub repository.