# Swe:create Skill > Creates or revises `swe:` skills for this repository using a repeatable authoring workflow: define concrete use cases, tune trigger boundaries, apply progressive disclosure, add matching eval assets, and validate the package. Use when adding a new skill, tightening an existing skill that over- or under-triggers, or distilling an external workflow into a repo-ready skill. Do NOT use for generic documentation edits or for executing the workflow the skill would describe. - Skill: `ckorhonen/swe-create-skill` (Agent Skill) - Install (CLI): `npx skillmds@latest add ckorhonen/swe-create-skill` - Raw SKILL.md: https://api.skillmd.com/api/skills/ckorhonen/swe-create-skill/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: ckorhonen (https://skillmd.com/u/ckorhonen) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/ckorhonen/swe-create-skill --- # SWE Create Skill ## What This Skill Does Use this skill to author or revise a `swe:` skill package for this repository in a way that is: - grounded in concrete user workflows - narrow enough to trigger reliably - consistent with this repo's skill and eval conventions - easy to validate and improve over time This skill distills the Anthropic skill-building guidance into a repo-specific authoring workflow. The outcome should usually include: - one `skills//SKILL.md` - one matching `evals//README.md` - one matching `evals//rubric.md` - one matching `evals//cases.json` - any required updates to `README.md` or `AGENTS.md` ## When To Use Use this skill when the user wants to: - add a new `swe:` skill to this repository - revise an existing skill that is too broad, too narrow, or structurally weak - turn an external guide or repeated workflow into a reusable repo-local skill - standardize how future skill authors package instructions and evals ## Do Not Use Do not use this skill for: - implementing the engineering workflow that the skill would later describe - generic repo documentation cleanup with no skill-authoring goal - one-off prompts that are not repeatable enough to justify a skill - large repository policy rewrites unrelated to skill authoring ## Inputs To Confirm Confirm or infer: - whether the work is a new skill or a revision to an existing one - the target workflow, user outcome, and success criteria - 2-3 realistic trigger phrases a user would actually say - the important non-goals or negative triggers - whether the skill depends on local tooling, MCP integrations, or external references - whether matching eval assets already exist or must be created If the request is underspecified, ask only for the missing workflow boundary needed to keep the skill narrow. ## Instructions ### Step 1: Start With Concrete Use Cases Define 2-3 specific use cases before writing the skill. For each use case, capture: - user request - workflow steps Claude should perform - result the user should get Only proceed if the workflow is repeatable and benefits from consistent instructions. ### Step 2: Inspect Local Skill Conventions First Read the repository's current guidance and analogous skills before drafting. At minimum, inspect: - `AGENTS.md` - `README.md` - one or two nearby `skills/*/SKILL.md` examples - the matching `evals/*` assets for those examples Honor these repo-specific rules: - skill frontmatter `name` must start with `swe:` - skill folder names stay kebab-case without the `swe:` prefix - every skill needs a matching `evals//` directory - `README.md` must stay accurate when the skill inventory changes ### Step 3: Define The Trigger Boundary Write the trigger boundary before drafting the full body. The frontmatter description should state: - what the skill does - when to use it - a few realistic trigger phrases - at least one clear non-goal when over-triggering is plausible Prefer specific requests over vague categories. A skill that says `help with engineering` is not acceptable. ### Step 4: Design For Progressive Disclosure Keep the skill package layered: - frontmatter should be concise and triggerable - `SKILL.md` should hold the full workflow - only add `scripts/`, `references/`, or `assets/` when they materially improve execution or keep the main skill readable Do not inline large reference material if a short summary plus targeted lookup is enough. ### Step 5: Draft The Skill Body Draft the `SKILL.md` body using this repository's required structure: - `## What This Skill Does` - `## When To Use` - `## Do Not Use` - `## Inputs To Confirm` - `## Instructions` - `## Output Requirements` - `## Quality Bar` Make the instructions operational: - sequence the workflow clearly - name evidence sources or required artifacts - specify hard constraints when needed - keep output shape reviewable - prefer concrete language over broad advice Add optional sections only when they help, such as: - `## Tooling Stance` - `## Parallelization Rule` - `## Examples` - `## Troubleshooting` ### Step 6: Draft Matching Eval Assets Create or update: - `evals//README.md` - `evals//rubric.md` - `evals//cases.json` The eval set should test the real contract of the skill, not generic prose quality. Include cases that cover a mix of: - a clear happy path - a bounded-scope or report-only variant - an edge case involving missing evidence, missing tooling, or conflicting scope Prefer review questions that make the reviewer inspect whether the response stayed within the workflow boundary. ### Step 7: Validate And Tune After drafting, run the repo validators and use any failures to refine the package: - `npm run evals:check` - `npm run lint:md` If the skill still seems likely to over-trigger or under-trigger, tighten the frontmatter description before expanding the body. ### Step 8: Update Repo Guidance Narrowly If the new skill changes the public inventory or authoring workflow, update the narrowest correct guidance files, usually: - `README.md` - `AGENTS.md` Do not broaden unrelated policy text. ## Output Requirements When creating or revising a skill, provide: 1. the skill slug and frontmatter `name` 2. the workflow boundary in one short paragraph 3. the files created or updated 4. the key trigger phrases and non-goals 5. the validation commands run and their outcomes 6. any remaining risks, such as likely over-triggering or missing ecosystem examples If the request is draft-only, return a review packet instead of writing files. ## Quality Bar - Start from concrete use cases, not abstract capability names. - Keep the workflow narrow enough that it triggers reliably. - Follow repo conventions exactly for naming, sections, and eval layout. - Use progressive disclosure instead of bloating `SKILL.md`. - Include explicit non-goals when the scope could blur. - Make the eval cases test the skill's actual contract. - Update repo guidance only where the new skill changes documented behavior.