agentleFS
ivklgnivklgn/ai-kit/.claude/skills/new-skill/SKILL.md

new-skill

Skill12 starsChanged 2 months agoMITView on GitHub

Create a new ai-kit skill end to end — ground in the repo's Archcore rules, collect the brief from the user, draft with skill-creator, apply ai-kit conventions, then hand off to review-and-release. Use when the user says "/new-skill", "давай новый скилл", "add a skill to ai-kit", or describes a capability they want packaged as a skill in this repository.

25 other projects use a version of this, 1 of them edited.

Adopted by

Most recently taken up by

Used with

Projects with it also use review-skill, commit and 1 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • MongoDBSkill

    review-skill

    Review a proposed Agent Skill for structural validity and content quality before publishing. Runs the skill-validator CLI to check for structural issues, scores the skill with an LLM judge, and interprets results to advise SMEs on what to address. Use when a user wants to review, validate, or quality-check an Agent Skill.

    Also in 3 projects that use this

  • SentrySkill

    commit

    Create commit messages following Sentry conventions. Use when committing code changes, writing commit messages, or formatting git history. Follows conventional commits with Sentry-specific issue references.

    Also in 4 projects that use this

  • MicrosoftSkill

    handoff

    Compact the current conversation into a handoff document for another agent to pick up.

    Also in 3 projects that use this

The file

We split this skill into the rules it gives an agent

10 rules. 0 are common, 4 are distinctive, and 6 are very specific to this project.

  • 0

    Common

    Most of the 21 edited versions we read keep these.

  • 4

    Distinctive

    This author's own choices. Worth a look.

  • 6

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

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

    line 14
  2. Distinctive:

    Before asking anything, read what already binds:

    line 18
  3. Very specific:

    Read two or three existing SKILL.md files closest in shape to the request.

    line 25
  4. Distinctive:

    Ask the user. Batch these into one question widget where the host offers one.

    line 31
  5. Very specific:

    Do not ask about a standalone README.md — the repo default is no.

    line 44
  6. Very specific:

    Frontmatter: Add model: <answer 3> alongside name and description.

    line 72
  7. Very specific:

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

    line 100
  8. Very specific:

    If the skill's design settled a question that will bind future work — a new convention, a rejected alternative, a model chosen against the …

    line 111
  9. Very specific:

    Run /review-and-release. It validates conventions, rebuilds the README ## Skills and ## Commands lists, mirrors skills/ and agents/ into …

    line 118
  10. Distinctive:

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

    line 122

“Common” is measured: kept by at least 6 in 10 of the 21 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.

#QuestionRecommended default
1What does the skill do, and what are 2–3 concrete invocations of it?— the user must supply this
2What phrasings should trigger it?derived from answer 1; confirm the list
3model: haiku, sonnet, or opus?sonnet; haiku for a mechanical skill under ~60 lines
4A slash command in commands/?yes when the skill is an action the user fires at a moment; no when it is domain expertise the model picks up from the description
5Bundled scripts/, references/, or assets/?none — 5 of 20 skills carry nothing but SKILL.md
6Original text, or a port of something external?original; a port switches on the license track in Step 3
7Output languageEnglish, unless the skill's subject is Russian text

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.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.