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.

---
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

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.

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 — memory your AI tools can read. Free to use and adapt under CC BY 4.0.