Authoring skill for a personal skill collection. It turns a rough idea ("I want a skill that does X") into a lean, conventions-compliant in the host collection's skill layout, then hands the user a live-test loop to try it for real. Every skill is authored from scratch, never forked, and follows the conventions inlined below; skillkit exists so you don't re-derive those rules each time.

, or any natural "create/author/scaffold a skill" request. If the user hasn't said what the skill should do, ask before anything else. Drive the procedure below one step at a time; don't jump ahead to drafting before intent, visibility, provenance, and name are settled.

Ask what the skill should do and when it should trigger (the real user phrasings). Optionally ask for example skill links; if given, skim them for structure ideas, which is non-blocking and only worth doing if fetching is available. Capture the job, the trigger conditions, and any hard constraints (tools it needs, things it must not do).

Then check that a new skill is the right shape, because the collection's index is a human's to hold. A skill earns its own directory when a person genuinely wants to choose it: a distinct moment, a distinct decision they'd make deliberately. When the choice is one the agent should make from context instead, it belongs as a mode inside an existing skill, since a mode costs one branch in that skill's description where a new skill costs a permanent entry the user has to remember. Name the existing skill and let the user decide; don't refuse the request.

Ask whether this is an internal repo-only skill or a public publishable one, because it changes the rules for everything downstream.

Ask: is this original, or your version of an upstream skill? Either way it's authored from scratch here; the answer just informs how much you lean on the upstream for structure ideas (Gather intent).

Follow the host collection's naming convention when it has one. Otherwise suggest 3–5

kit

names and recommend one: one lowercase word, the functional term leads so it stays searchable (people search , not ), appended, and shorten an awkward root rather than force a clumsy join ( → , not ). Avoid collisions with well-known tools (, , anything already popular): when network access exists, search the candidate on the web and in the skills.sh directory; when offline, state that the popularity check was skipped. Let the user pick. The chosen name must equal the directory name.

Create the skill in the host collection's documented layout from the Frontmatter template below, applying the Quality bar, and stamp from Visibility. In a collection repo this is commonly ; standalone, use the agent's discovered skills directory such as . Keep it lean, and prefer one file.

Show the draft. Take edits and iterate until the user explicitly approves. Don't proceed to testing on a draft the user hasn't signed off.

Don't install the skill yourself. Hand the user the commands to drive the live trial. If the collection provides dev-link tooling (check its README or Makefile for a link/unlink target), tell them to inject the skill with that; otherwise have them symlink or copy into their agent's skills directory (e.g. ). Then test in a fresh session, because the skill list loads at startup, so a running session won't see the new skill. No scratch test-plan file; testing here is done live and directly. Suggest they exercise it against reality:

When done testing, they remove the dev link the same way it was added (the collection's unlink command, or deleting the symlink/copy).

First finish the mechanical tail: run the collection's skill lint if it has one (fix errors and address warnings; without one, self-check against the Conventions, Quality bar, and, for public skills, Portability), and update whatever the collection uses to list its skills (typically a README skills table, and a directory-grouping file if the repo has one). Then close:

What changed. Report the skill created (name, visibility, file count), the listing surfaces updated, and the lint or self-check result.

Where it landed. Give the skill's directory path, and whether a dev link from Live test is still in place (it should be removed by now; say so if it isn't).

Next. The work is uncommitted, so the move is to commit it: suggest a conventional message (e.g. ) for the user to run. Never commit automatically, because committing is the user's call.

A skill is built from steps (the ordered actions the agent performs) and reference (definitions, rules, and facts consulted on demand). The two mix freely: all steps, all reference, or both. What you decide for each piece is where it sits on a ladder ranked by how immediately the agent needs it. An in-file step is the primary tier; in-file reference is consulted on demand, and a flat peer-set of rules on one rung is a fine arrangement rather than a smell; disclosed reference is pushed into a satellite file inside the skill's own directory and loaded only when its pointer fires.

Disclose by branch, not by size. Inline what every branch needs, and push behind a pointer what only some branches reach, where a mode-filtered catalog that each run reads a third of is the clean case. Push too much down and you hide material the agent needs; push too little and the top bloats. Neither direction is the safe default.

Co-locate a concept: keep a definition, its rules, and its caveats under one heading rather than scattered through the file. Scattering is not duplication, since duplication repeats one meaning in two places while scattering fragments one meaning across many, and it fails differently, because the agent reads one part and never meets the rest.

Sprawl is the failure mode: a skill simply too long, even when every line is live and unique. Attention thins across the excess. The cure is the ladder, not a trim pass.

Every step ends on a completion criterion, the condition that tells the agent the work is done. A step without one ends when the agent feels finished, which is the largest single source of run-to-run variance. Two properties make it a lever. Clarity: can the agent tell done from not-done? A vague bound ("understanding reached", "keep it lean") invites premature completion, where the step ends early because attention has already slipped to the steps still visible ahead of it. Demand: how much the wording requires. "Every modified model accounted for" forces real digging where "produce a change list" does not, so prefer the exhaustive form to the productive one. Demand is not step-bound; "every rule applied" binds a body of flat reference the same way, which is how an all-reference skill still carries a bar. The strongest criteria are both checkable and exhaustive.

Sharpen a rushed step's bound first, because that edit is local and cheap. Split the sequence only when the bound is irreducibly fuzzy and you have watched the rush happen, and note that splitting works only across a real context boundary, meaning a hand-off document or a subagent dispatch. An inline call leaves the later steps in context and hides nothing.

No hard wrapping. Write each paragraph and list item as one continuous line; let the editor and renderer soft-wrap. Fixed-width line breaks mid-sentence buy nothing, because the agent reads the text regardless of newlines, and every Markdown renderer soft-wraps anyway. Keep line structure only where it is meaningful: code fences, tables, and YAML frontmatter (a folded scalar is fine).

A skill writes for two different readers, and they need opposite prose. Text a skill writes back to its own operator (QA steps, handoff documents, status snapshots, sections, next-move lines, preview-and-confirm lines) is procedural: write it in ASD-STE100 Simplified Technical English. One instruction per sentence. Procedural sentences 20 words or fewer, descriptive sentences 25 or fewer. Active voice, present tense, name the actor. No metaphor, idiom, or second meaning. Pick one term per concept and keep it within a single document; the rule never reaches across documents. Text a person reads to form an opinion (plan context, research recommendations, ADR rationale, review verdicts) is explanatory and keeps uneven rhythm and a stated position; do not apply STE to it. Machine-read or format-bound text is exempt: commit subjects, issue titles, prompts, design tokens, code, paths, commands, and quoted source. Content the skill produces for a third-party audience is out of scope entirely, including project documentation, published prose, and UI copy, because that is production writing for readers outside the session and needs room to explain a concept. Precedence: an explicit user instruction, then the target repository's documented convention, then the register. Inline this rule in a public skill rather than linking it.

When a skill creates a durable Markdown artifact under , follow the host collection's convention when it has one. Otherwise use : a lowercase type prefix, a short lowercase kebab-case subject slug, and the artifact's ISO creation date at the end (for example, ). Keep that creation date stable when the file is edited. Update the same artifact in place; for a genuine same-day collision, make the slug more specific and only then insert a sequence immediately before the date (). ADRs retain their sequence as . Multi-file artifacts put the convention on their bundle directory, such as , while structural child names remain fixed. Inline the applicable rule in every public skill that creates such an artifact so the installed skill remains self-contained.

Never reference a step by its number (a bare "see step N" citation). A bare number binds to a step's position, so inserting or reordering steps silently makes it point at the wrong one. Reference the step's identity instead: for a step with a heading, link to it by name with a GitHub anchor (, since GitHub builds the anchor from the full heading text by lowercasing it, dropping punctuation, and turning spaces into hyphens); for a list item with no heading, name the action in prose rather than citing its ordinal.

Every skill ends by reporting what it did and naming what comes next, in a closing section titled (or inside a numbered procedure; a mode-per-section skill gets one per mode). A skill that goes quiet at the end leaves the user to reconstruct what changed on disk and what the next move is, which is exactly the work skills exist to remove. Three beats, in order. What changed: the mutations, concretely, including the ones that didn't happen. Where it landed: paths, branches, URLs, so nothing has to be hunted for. Next: the single best move, crowned, not a menu of equals. Route, don't launch: name the follow-up and its one-line invocation without invoking it, name a sibling skill only when it's installed, and always give the plain fallback ("open a PR with a PR skill, otherwise "). A terminal skill says plainly there is no next step rather than inventing one; a read-only skill may drop a genuinely empty beat, never pad it.

Apply these while drafting; they are the difference between a skill that triggers and reads well and one that doesn't:

A public skill is installed on its own into arbitrary environments. Only its own directory travels, so it must stand alone:

Internal skills are exempt, because they live and die in their repo and may use its machinery freely.