swe-skills

SWE Skills

AI skill files and eval suites for streamlining SWE workflows.

Structure

• skills/ stores skill definitions.
• evals/ stores evaluation suites and fixtures.
• judges/ stores draft LLM-as-judge prompt assets for subjective eval criteria.
• review-agents/ stores reusable prompt assets for agents that label or audit review data, including web-interface variants.
• review-app/ stores the zero-dependency browser review interface.
• review-data/ stores local generated review datasets and saved review results.
• scripts/ stores local repo utilities, including eval validation and review-packet rendering.
• docs/plans/ stores design and implementation plans for substantive repo changes.

Conventions

• Prefix every skill identifier or name with swe:.
• Keep repo documentation aligned with the current install flow and file layout.

Install

Use npx skills install ckorhonen/swe-skills.

Development

• Run npm install to install repo-local lint tooling and set up the Git hook.
• Run npm run lint:md to check Markdown files.
• Run npm run lint:md:fix to apply Markdown fixes.
• Run npm run evals:check to validate skill and eval asset structure.
• Run npm run evals:packet -- <skill-slug> to render a review packet for one skill.
• Run npm run judges:check to validate draft judge prompt assets.
• Run npm run judges:build-datasets to export explicit criterion-labeled examples for each draft judge from local review results.
• Run npm run review:build-dataset to generate local review datasets from the current eval cases.
• Run npm run review:sync-results after labeling all-skills.synthetic to copy aggregate labels into the per-skill result files used by coverage and judge export.
• Run npm run review:coverage to inspect overall, criterion, and review-question label coverage plus judge-readiness gaps.
• Run npm run review:serve to start the zero-dependency local review server and open the browser UI manually if desired.
• Pre-commit runs lint-staged, which lints and auto-fixes staged Markdown files.

Authoring Conventions

• Keep every skill name prefixed with swe: even though some generic external skill guides use unprefixed kebab-case examples.
• Use swe:create-skill before creating or revising anything under skills/ and the matching evals/ assets. It distills the Anthropic skill-building guide into this repo's local authoring workflow.
• If a skill consults .ai/swe.json, treat it as an optional local preference layer only. Explicit user requests and repo guidance such as AGENTS.md still outrank it.
• Write frontmatter descriptions so they clearly state what the skill does, when to use it, and a few realistic trigger phrases.
• Include explicit non-goals or negative triggers so skills do not overfire.
• Prefer a consistent SKILL.md structure: what the skill does, when to use it, inputs to confirm, instructions, output requirements, examples, and troubleshooting.
• Add compatibility notes when a skill depends on local checkout access, GitHub metadata, observability tooling, or ecosystem-specific scanners.

Skills