Writing skills

How we write the skills published here. None of this is a specification - the format is Anthropic's - but these are the conventions that made the difference between a skill that gets used and one that sits in the marketplace untouched.

The description does the work

It is the only part the agent reads before deciding

A skill is loaded on the strength of its description alone. The body can be excellent and it will not matter if the description does not match how someone actually phrases the request.

So the description is written as two things joined together: what the skill does, and the concrete situations that should trigger it.

---
name: isolated-testing-style
description: Write tests that use real collaborators through simulation instead of stubs and mocks, take their isolation from randomised data rather than setup and teardown, and assert behaviour rather than call counts. Use when writing or reviewing tests, when a test needs a collaborator faked, when reaching for a mock, spy, `toHaveBeenCalledWith`, `beforeEach`/`afterEach` fixtures or a hardcoded expected hash, and when asked "how should I test this?".
---

Note what the trigger half names: specific function names, specific file shapes, and a question asked in the words a person would use. Abstract descriptions of a problem domain do not trigger; the artefacts someone is looking at when they need the skill do.

One skill, one job

Scope is what makes triggering possible at all

The temptation with a skill that works is to grow it. Resist it. A skill covering testing, deployment and code review has a description that matches everything, so it is loaded for everything, and the agent cannot use its presence as a signal about the task at hand.

When a skill starts needing "and also", that is a second skill. The three testing skills published here could have been one; they are three because each answers a question the others do not.

Write rules with their reasons

A rule without a reason gets applied literally or not at all

Every rule in these skills is followed by the failure it exists to prevent. This is not decoration. An agent that knows why a rule holds can tell when a case is genuinely an exception; an agent given a bare instruction either applies it where it does not belong or abandons it at the first friction.

A useful test

If you cannot name the specific bug a rule would have caught, the rule is probably a preference rather than a convention - and preferences are better expressed as an example than as an instruction.

The layout of a plugin

What the marketplace and npm both expect

plugins/my-skill/
  package.json          # @kensio/my-skill, versioned independently
  README.md             # for humans arriving from npm or GitHub
  skills/
    my-skill/
      SKILL.md          # frontmatter + the instructions themselves

The plugin name, the directory under skills/ and the name in the frontmatter all match. Nothing enforces that, but the sync that builds this website assumes it, and so does every human reading the repository.

package.json carries the version. Claude Code notices an update only when that number changes, so a released fix that forgets to bump it is a fix nobody receives.

Start from the template

The skill-template skill is a copy-and-edit starting point that carries all of the above. Install it, or read it inthe public repository.