skillsify

---
name: skillsify
description: Creates, validates and installs Agent Skills without leaving the terminal. Use when the user asks to build a skill, turn a repeated workflow into a skill, find an existing skill for a task, or wants to know why a skill is not being triggered.
---

# Skillsify

Turn a described workflow into an installed, validated skill.

## When to use this

- The user asks to "make a skill" or "turn this into a skill".
- The user has repeated the same multi-step instruction more than twice and it
  should be captured.
- The user is looking for an existing skill for a task.
- A skill exists but is never being selected, and the user wants to know why.

## Before generating: check the registry first

Never generate what already exists. Search before creating:

```bash
npx skillsify list "<topic>"
```

If a published skill fits, install it and stop:

```bash
npx skillsify add <skill-name>
```

## Creating a new skill

```bash
npx skillsify create "<one line describing what the skill should do>"
```

The description is the whole input, so make it specific. Compare:

- ❌ `"testing"` — too vague to produce trigger conditions.
- ✅ `"find flaky tests in a CI log and classify why each one is flaky"`

The command streams the skill as it is written, runs the schema and lint gates,
and writes the result to `.claude/skills/<name>/`.

## Reviewing what came back

Generated skills are model output. Always read `SKILL.md` before relying on it,
and check these four things — they are the ones that actually go wrong:

1. **The description states *when*, not just *what*.** This is the only text the
   agent sees when deciding whether to load the skill. A description with no
   trigger condition produces a skill that never fires.
2. **Instructions are specific enough to act on.** "Follow best practices" is
   not an instruction.
3. **Referenced files exist** and carry the detail, rather than the body
   carrying all of it.
4. **No invented APIs.** Verify any function, flag or endpoint the skill claims
   exists against real documentation.

Fix problems by editing the files directly. They are plain Markdown.

## Diagnosing a skill that never triggers

Almost always the description, not the body. Work through, in order:

1. Read the `description` in the frontmatter. Does it name the situation the
   user would actually be in? Rewrite it to lead with the trigger:
   `"...Use when the user asks to X, reports Y, or is about to Z."`
2. Check the skill is in `.claude/skills/<name>/SKILL.md` — the directory name
   and the frontmatter `name` should match.
3. Check the frontmatter parses: it must be the very first thing in the file,
   opened and closed by `---` on their own lines.
4. Only then look at the body.

## Publishing

A skill that passes the gates can be published to the public registry, where it
gets a page, a quality report, and a one-command install. See
[references/publishing.md](references/publishing.md).

## Rules

- Search the registry before generating. Duplicates dilute the catalogue.
- Never present generated output as verified. It passed schema and lint gates,
  which is not the same as being correct.
- One skill, one job. If a description needs the word "and" twice, it is two
  skills.
- Do not commit a generated skill without reading it first.

# Publishing a skill

## What the gates check

A skill must clear these before it can be published. The first two run inside
the generation request, so you see the result immediately.

| Gate | Checks |
| --- | --- |
| Schema | Frontmatter parses as YAML; `name` is lowercase kebab-case, max 64 chars; `description` is 40–1024 chars; every referenced file exists in the bundle |
| Lint | `SKILL.md` under 32 KB; bundle under 512 KB; no absolute or machine-specific paths; no path traversal; no credentials in any file |
| Trigger eval | A judge model runs the skill against prompts that should fire it and prompts that should not, and records both results |
| Sandbox | Any bundled scripts are executed in isolation to confirm they run |

## Writing a description that gets selected

The description is the only text the agent reads when deciding whether to load
a skill. It has to answer two questions in one sentence:

```text
<what it does>. Use when <the situation the user is in>.
```

Concrete triggers beat abstract capability:

- ❌ `"Helps with database performance."`
- ✅ `"Finds N+1 query patterns in an ORM codebase. Use when a page is slow,
  when the user reports too many queries per request, or before shipping a new
  list view."`

Name the symptoms a user would describe, not the technique you would apply.
Users say "this page is slow"; they do not say "perform N+1 analysis".

## Progressive disclosure

`SKILL.md` is loaded whenever the skill is selected. Supporting files are read
only when the body points at them. So:

- Keep procedure, rules and decision-making in `SKILL.md`.
- Move lookup tables, thresholds, long specifications and worked examples into
  `references/`.
- Link to them from the body so the agent knows when to open them.

A 400-line `SKILL.md` with no references is a skill that costs full price on
every invocation.

## Versioning

Publishing again with changes bumps the version:

| Change | Bump |
| --- | --- |
| Reworded instructions, fixed a typo | patch |
| New capability, still backward compatible | minor |
| Changed what the skill triggers on, or removed a documented behaviour | major |

A changed `description` is usually a **major** bump — it changes when the skill
fires, which is the part other people depend on.