---
name: skill-format
title: the skill format
kind: skill
version: 1.0.0
description: >
  the document class for a shareable skill — one markdown file, a manifest at the
  top, a link you can hand to any ai. defines the required and diagnostic fields,
  what makes a skill more than a readable document, and how to write one another
  model can act on without further explanation.
when_to_load: >
  when writing, publishing, reviewing, or sanitising a skill — any document meant
  to teach an ai how to do something. also when deciding what belongs in a skill
  versus a prompt, a doc, or a memory.
authored_by: innernet
author_url: https://innernet.live
license: CC BY 4.0
updated: 2026-07-26
tags: [skills, format, spec, ai, documentation]
---

# the skill format

> a skill is an ordinary document wearing a modifier. same markdown, same prose —
> but it declares who wrote it, what it is for, and when to load it, so the moment
> you hand out the link the recipient knows more than the words alone would tell
> them.

A note is something you keep. A doc is something you read. **A skill is something
you hand to a model so it does the work differently afterward.** That difference
is entirely in the manifest — which is why a skill is a class, not a folder
convention.

---

## the shape

One markdown file. A YAML manifest at the top, between `---` fences. Prose below.
Nothing else is required — no directory, no build step, no runtime.

```markdown
---
name: quiet-interface
title: quiet interface
kind: skill
version: 1.0.0
description: >
  What this skill makes the model able to do, in one or two sentences,
  written so a model deciding whether to load it can decide correctly.
when_to_load: >
  The moment to reach for it, in the words that moment actually uses.
authored_by: someone
author_url: https://example.com
license: CC BY 4.0
updated: 2026-07-26
tags: [design, ui]
---

# quiet interface

...the skill itself...
```

### required fields

| field | what it carries |
|---|---|
| `name` | the stable slug. lowercase, hyphenated, never changes once shared — it is half the link. |
| `description` | what the skill makes the reader *able to do*. Written for a model choosing whether to load it, not for a human browsing. |
| `kind` | `skill`. The modifier itself — what turns a document into this class. |

### the diagnostic fields

These are what make giving someone access to the file more useful than sending
them the text. Optional in the parser, expected in practice.

| field | what it carries |
|---|---|
| `title` | the human name, if it differs from the slug. |
| `when_to_load` | the trigger. A description says what a skill *is*; this says when to reach for it. It is the single highest-value field, and the most often skipped. |
| `version` | semver. Bump the minor for new material, the major when previous guidance is reversed. |
| `updated` | ISO date of the last substantive revision. A skill with no date is a skill nobody trusts. |
| `authored_by` · `author_url` | attribution. A skill is a position someone took, not an anonymous fact sheet — knowing whose it is tells you how to weigh it. |
| `license` | how it may be reused. Say so explicitly; silence reads as "don't". |
| `tags` | for finding it among others. |

---

## how to write one a model can act on

**Write imperatively.** A skill is instructions, not an essay about instructions.
"Bound prose to 60–75 characters" beats "line length is an important
consideration in readability".

**Give the reason with the rule, once.** A rule without a reason gets
misapplied at the first edge case; a reason without a rule gets ignored. One
sentence of why, attached to the rule, is enough.

**Order by what it costs to get wrong.** The things that make output
unmistakably bad go first. Reference material goes last, or into a second file.

**Separate taste from floor.** Some of a skill is a position you're taking
(taste, house style); some is non-negotiable regardless of house (correctness,
accessibility, safety). Mark which is which, so someone adapting the skill knows
what they may change.

**Include the failure modes.** The list of what makes work read as generated,
wrong, or lazy is often more actionable than the list of what makes it good.

**End with a checklist.** Something the model can actually run against its own
output before calling the work done.

**Keep it one file if you can.** A single file is a single link, and a single
link is the whole point. Split into references only when the main file stops
being readable in one sitting — and then say, in the main file, exactly when to
open each one.

---

## what belongs in a skill — and what doesn't

**belongs:** durable method. How to do a kind of work well. Rules that outlive
the current task, and would be worth teaching to a new colleague.

**doesn't belong:**

- *anything private.* A skill is written to be shared. Internal file paths,
  service names, credentials, customer names, business context, personal detail —
  strip all of it. If a rule only makes sense with private context attached, the
  rule is under-generalised; find the version that stands alone.
- *the current task.* That's a prompt.
- *what the code already says.* Structure, APIs, and file layout are read from
  the source, not memorised from a document that will go stale.
- *facts about a person.* That's memory, and it has different consent.

A useful test before publishing: **would this still be true and useful for
someone with no access to my systems?** If not, either generalise it or keep it
internal.

---

## sanitising an internal skill for sharing

Most good skills start private. To make one shareable:

1. **strip identifiers** — repo paths, internal component and module names,
   service and vendor names, ticket numbers, people.
2. **generalise the specifics** — an internal component name becomes the *job*
   it does ("the one text field"), so the rule survives the rename.
3. **replace values with structure** — hand over the shape of the token contract,
   not your brand's hex codes; say what each slot is for.
4. **remove the business** — pricing, roadmap, strategy, and metrics are context,
   not method.
5. **keep the reasons.** The reasons are the actual value, and they're rarely
   sensitive.
6. **read it once as a stranger.** Anything you can't understand without inside
   knowledge is still internal.

The result should be a genuine gift, not a teaser. A sanitised skill that
withholds the useful half is worse than not publishing.

---

## the link is the interface

A published skill has one canonical URL. That link should:

- render as a readable page for a human,
- serve the raw markdown to anything that asks for it,
- and state, right under the title, that pasting the link into an AI is all the
  instruction the AI needs.

That last line matters more than it looks. Most people don't yet know that a URL
is a valid way to hand a model a capability — say it plainly and once, and the
whole format explains itself.

---

*kept by [innernet](https://innernet.live) — memory your AI tools can read.
Free to use and adapt under CC BY 4.0.*