Skill Factory — Reference
Frontmatter fields (per Cursor docs)
| Field |
Required |
Description |
name |
yes |
Skill identifier; lowercase letters/numbers/hyphens; must match folder name. |
description |
yes |
What the skill does and when to use it. Used by the agent to decide relevance. |
license |
no |
License name or reference to a bundled license file. |
compatibility |
no |
Environment requirements (system packages, network access, etc.). |
metadata |
no |
Arbitrary key-value mapping. |
disable-model-invocation |
no |
When true, only triggers via /skill-name. |
Skill directory locations
| Location |
Scope |
.agents/skills/ |
Project-level |
.cursor/skills/ |
Project-level |
~/.agents/skills/ |
User-level (global) |
~/.cursor/skills/ |
User-level (global) |
Compatibility paths (also discovered): .claude/skills/, .codex/skills/, plus their ~/ equivalents.
Optional directories
| Directory |
Purpose |
scripts/ |
Executable code that agents can run. |
references/ |
Additional documentation loaded on demand. |
assets/ |
Static resources like templates, images, or data files. |
Best practices
- One responsibility per skill. Split if it spans multiple use cases.
- Description-driven discovery: describe the trigger explicitly.
- Keep
SKILL.md short. Move detail to references/.
- Self-contained scripts with helpful errors.
- No secrets in the skill folder ever.
Useful internal docs