New Skill

New Skill

A harness for adding one skill to this repository. It sequences three existing instruments — Archcore, skill-creator, /review-and-release — and fills the gap between them: skill-creator writes portable skills, this repo ships plugin skills, and the two disagree on frontmatter, packaging, and file layout.

Run the steps in order. Step 1 is the only one that questions the user.

Step 0: Ground in the repo's rules

Before asking anything, read what already binds:

1. mcp__archcore__search_documents with content: "skill command naming" — then get_document on .archcore/conventions/project-stack.rule.md. It fixes the file layout, the frontmatter fields, and the kebab-case naming rule.
2. ls skills/ — check no skill already covers the requested job. A near-duplicate is a reason to extend an existing skill instead, and a reason to say so before Step 1.
3. Read two or three existing SKILL.md files closest in shape to the request. They are the style baseline — skills/recap/SKILL.md for a short one, skills/compatibility-audit/SKILL.md for one with references/ and scripts/.

Step 1: Collect the brief

Ask the user. Batch these into one question widget where the host offers one; otherwise one message per question, most important first. Recommend an answer for every question.

Do not ask about a standalone README.md — the repo default is no. Add one only when the user asks for the skill to be installable on its own via npx degit.

Step 2: Draft with skill-creator

Invoke the skill-creator skill and follow its craft guidance: progressive disclosure, degrees of freedom, writing a description that carries all the triggering information, keeping SKILL.md lean.

Two deviations from its process:

• init_skill.py — run scripts/init_skill.py <name> --path skills/ only when answer 5 named bundled resources. It scaffolds example scripts/, references/, and assets/ directories that then have to be deleted. For a SKILL.md-only skill, write the file directly.
• Step 5, packaging — skip it. package_skill.py builds a .skill archive for standalone distribution; ai-kit ships through the plugin marketplace, and nothing in this repo consumes a .skill file.

Step 3: Apply ai-kit conventions

This is the delta skill-creator does not know about.

1. Location. The skill lives at skills/<name>/SKILL.md in the repo root. Never author under plugins/ai-kit/skills/ — that tree is generated by rsync at release and any edit there is overwritten.

2. Name. kebab-case, one string reused in four places: the directory, the frontmatter name, the command filename, and the /ai-kit:<name> invocation.

3. Frontmatter. Add model: <answer 3> alongside name and description. skill-creator says to include no field beyond name and description; this repo overrides that — /review-and-release fails a skill that carries neither model nor disable-model-invocation: true.

4. Do not run quick_validate.py or package_skill.py. Both reject every skill in this repository: their allowed-frontmatter list is name, description, license, allowed-tools, metadata, so model: reads as an unexpected key. /review-and-release is this repo's validator.

5. Command file, when answer 4 was yes — commands/<name>.md, exactly this shape:

   ---
   description: <one line, imperative, same subject as the skill description>
   ---
   
   # /ai-kit:<name>
   
   ## Arguments
   
   The user invoked this command with: $ARGUMENTS
   
   <one line on what an empty value means, and what a non-empty value selects>
   
   ## Instructions
   
   Use the skill at `skills/<name>/SKILL.md`.
   

   Add argument-hint: "[--flag]" to the frontmatter only when the skill takes flags — commands/reset-permissions.md is the one example.

6. A port, when answer 6 said so — read .archcore/importing-external-components.rule.md and follow it: check the upstream license, add the THIRD-PARTY-LICENSES.md map row and full license text, write skills/<name>/ATTRIBUTION.md, and add the README Credits bullet. A skill written from scratch that reuses only ideas gets the map row and the Credits bullet, and no ATTRIBUTION.md.

Step 4: Record the decision, when there was one

If the skill's design settled a question that will bind future work — a new convention, a rejected alternative, a model chosen against the default — record it with /archcore:document as an adr under .archcore/skills/. .archcore/skills/compatibility-audit-model.adr.md is the worked example. A routine skill that follows every existing rule needs no document.

Step 5: Release

Run /review-and-release. It validates conventions, rebuilds the README ## Skills and ## Commands lists, mirrors skills/ and agents/ into plugins/ai-kit/, bumps the patch version in both plugin manifests, and commits.

Do not hand-edit the README lists or the version — that skill owns them.

Result

Report: the skill path, whether a command was created, the new version, the commit hash, and any Archcore document written.