Skip to content

Skill Factory

The skill that builds skills. Encapsulates the entire skill-authoring workflow into one repeatable, approval-gated process.

When to use

  • The user identifies a recurring task worth turning into a reusable skill.
  • A subagent's responsibilities are small and single-shot — convert it to a skill instead.
  • A workflow keeps getting reinvented in chat — extract the pattern.

What you produce

A new skill folder under either .cursor/skills/<name>/ (project) or ~/.cursor/skills/<name>/ (user), validated against the checklist, with a stage-for-publish marker.

Procedure

Step 1 — Capture

Use the Ask tool. You need: - Name (lowercase, hyphenated; will become folder + name: field). - Description (1-2 sentences; includes the "use when" trigger — this is what the agent reads to decide invocation). - Scope: project or user. - Disable model invocation? (true = slash-only, false = agent decides). - Optional artifacts: scripts, references, assets — yes/no for each. - Compatibility / dependencies: any required tools, network, env vars. - Use cases: 2-3 concrete examples of when this skill should fire.

If any of the above is unclear, ask before scaffolding.

Step 2 — Draft SKILL.md

Build YAML frontmatter:

---
name: <name>
description: <use-when description>
license: <optional, e.g., MIT>
compatibility: <optional, e.g., requires-anytype-local-api>
disable-model-invocation: <true|false, default false>
metadata:
  authored_by: skill-factory
  authored_on: <yyyy-mm-dd>
---

Body sections (skip optional ones if not relevant):

  1. # <Display Name> — single-paragraph essence.
  2. ## When to use — bullets matching the description.
  3. ## What you produce — concrete output description.
  4. ## Procedure — numbered steps.
  5. ## Report template (only if the skill produces structured output).
  6. ## Anti-patterns — what this skill is not.
  7. ## Compatibility — dependencies, network, security expectations.

Step 3 — Scaffold optional folders

For each optional artifact answered "yes" in Step 1, create:

  • scripts/ with at least one stub main.<ext> matching the language.
  • references/REFERENCE.md with placeholders for further reading.
  • assets/ with a .gitkeep if no concrete files yet.

Step 4 — Validation checklist

Run through this checklist; each item must pass before staging.

  • name: matches folder name and is lowercase-hyphen.
  • description: clearly states when the agent should fire it (≥ 1 trigger phrase).
  • No secrets / API keys / personal data anywhere in the skill.
  • disable-model-invocation set explicitly when the skill should be slash-only.
  • All script paths in SKILL.md exist relative to skill root.
  • No instructions that violate the bounded-edit rule.
  • No instructions that would auto-egress to networks not in the project allowlist.
  • If skill writes to disk, it writes only inside the workspace or explicit user-approved paths.
  • Security checklist (SPB-09 secret handling) passes.
  • At least one negative-case ("don't use this when…") is documented.

Step 5 — Stage for install

  • Print the install command:
  • Project: skill is already in .cursor/skills/<name>/ — reload window.
  • User: copy or symlink the skill folder to ~/.cursor/skills/<name>/.
  • Append a one-line entry to the relevant skills index (e.g., README "skills" table) noting the new skill.
  • Suggest a test prompt the user can run to confirm the skill triggers correctly.

Step 6 — Verifier handoff

Invoke the verifier subagent (read-only) on the new skill folder. Report any gaps.

Step 7 — Optional: publish

If the user wants the skill bundled for distribution: - Move/copy into a plugin directory with .cursor-plugin/plugin.json. - Reference the Plugins reference for manifest schema. - Stop before any push/publish action — that requires explicit user approval.

Report template

# Skill Factory Report — <name>

## Created
- folder: <path>
- files: <list>

## Frontmatter
- name: <>
- description: <>
- disable-model-invocation: <>

## Validation
- [x] all checks passed
- (or list of failures with required fixes)

## Install
- <reload-window | copy-to-user-skills | symlink>

## Test prompts
- <suggested user prompts to confirm trigger>

Anti-patterns

  • Don't create skills for one-off needs — those belong in chat, not in a skill folder.
  • Don't bypass the description trigger and use vague "general helper" language.
  • Don't create scripts that require credentials without documenting where they come from.
  • Don't generate a skill folder without running the validation checklist.
  • Don't stage the skill if any validation item fails.

Compatibility

  • Read/write inside workspace only.
  • No network egress.
  • Approval-gated: scaffolding writes are confirmed before commit.

Reference