Audit and Add Project Skills to Cursor
This skill scans project and Codex skills, checks Cursor compatibility, and guides adding them to Cursor.
Skill Sources
| Source |
Path |
Notes |
| Project skills |
{workspaceFolder}/.agent/skills/*/SKILL.md |
Often Codex/Claude format |
| Codex skills |
~/.codex/skills/**/SKILL.md |
May need adaptation |
Cursor Skill Format (Required)
Cursor expects:
---
name: skill-name
description: What the skill does and when to use it (third person, specific)
---
# Title
Body...
Compatibility Checklist
Fields Cursor Ignores (OK to Keep)
license, metadata, disable-model-invocation, globs, alwaysApply- Codex-specific:
metadata.short-description, agents/openai.yaml references
Adaptation Notes
| Project/Codex Pattern |
Cursor Equivalent |
${PROJECT_ROOT} |
{workspaceFolder} or omit |
${BRAIN}, ${HANDS} |
Omit or replace with "the agent" |
| References to "Codex" or "Claude" |
Replace with "the agent" or "Cursor" |
~/.codex/skills/ paths |
Use project .cursor/skills/ or ~/.cursor/skills/ |
Audit Workflow
- Discover skills: List SKILL.md files in
.agent/skills/ and optionally ~/.codex/skills/
- Read each SKILL.md: Extract frontmatter (name, description)
- Validate: Check name format, description quality, required structure
- Report:
- ✅ Compatible as-is
- ⚠️ Compatible with minor edits (update description, fix name)
- ❌ Needs adaptation (Codex-specific content, missing fields)
Add-to-Cursor Workflow
Target: Project skills → .cursor/skills/{skill-name}/
- Create
.cursor/skills/ if it doesn't exist
- For each compatible skill:
- Create
.cursor/skills/{skill-name}/
- Copy
SKILL.md (and optional reference.md, scripts/ if present)
- Apply adaptations from audit (description, path refs)
- Preserve original
.agent/skills/—do not delete
Do NOT add skills to ~/.cursor/skills-cursor/. That directory is reserved for Cursor built-in skills.
Quick Commands
List project skills:
Get-ChildItem -Path ".agent/skills" -Directory | ForEach-Object { $_.Name }
Check if SKILL.md exists:
Test-Path ".agent/skills/{skill-name}/SKILL.md"
Copy a skill to Cursor:
Copy-Item -Path ".agent/skills/{skill-name}" -Destination ".cursor/skills/{skill-name}" -Recurse
Decision: Project vs Personal
- Project (
.cursor/skills/): Skills shared with the repo; available only in this workspace
- Personal (
~/.cursor/skills/): Skills for all your projects
Use project scope for workspace-specific skills (NinjaTrader, UniversalOR, etc.). Use personal for generic skills (pdf, docx, code-formatter).
1---2name: audit-and-add-project-skills3description: Audits project skills in .agent/skills/ and Codex skills for Cursor compatibility, then helps add compatible skills to .cursor/skills/. Use when the user wants to migrate project skills to Cursor, check if skills work with Cursor, or add existing skills to Cursor.4---56# Audit and Add Project Skills to Cursor78This skill scans project and Codex skills, checks Cursor compatibility, and guides adding them to Cursor.910## Skill Sources1112| Source | Path | Notes |13|--------|------|-------|14| Project skills | `{workspaceFolder}/.agent/skills/*/SKILL.md` | Often Codex/Claude format |15| Codex skills | `~/.codex/skills/**/SKILL.md` | May need adaptation |1617## Cursor Skill Format (Required)1819Cursor expects:2021```markdown22---23name: skill-name24description: What the skill does and when to use it (third person, specific)25---26# Title27Body...28```2930### Compatibility Checklist3132- [ ] **name**: Lowercase, hyphens only, max 64 chars33- [ ] **description**: Third person, includes WHAT and WHEN (trigger terms)34- [ ] **Body**: Markdown instructions (procedures, examples, workflows)3536### Fields Cursor Ignores (OK to Keep)3738- `license`, `metadata`, `disable-model-invocation`, `globs`, `alwaysApply`39- Codex-specific: `metadata.short-description`, `agents/openai.yaml` references4041### Adaptation Notes4243| Project/Codex Pattern | Cursor Equivalent |44|-----------------------|-------------------|45| `${PROJECT_ROOT}` | `{workspaceFolder}` or omit |46| `${BRAIN}`, `${HANDS}` | Omit or replace with "the agent" |47| References to "Codex" or "Claude" | Replace with "the agent" or "Cursor" |48| `~/.codex/skills/` paths | Use project `.cursor/skills/` or `~/.cursor/skills/` |4950## Audit Workflow51521. **Discover skills**: List SKILL.md files in `.agent/skills/` and optionally `~/.codex/skills/`532. **Read each SKILL.md**: Extract frontmatter (name, description)543. **Validate**: Check name format, description quality, required structure554. **Report**:56 - ✅ Compatible as-is57 - ⚠️ Compatible with minor edits (update description, fix name)58 - ❌ Needs adaptation (Codex-specific content, missing fields)5960## Add-to-Cursor Workflow6162**Target**: Project skills → `.cursor/skills/{skill-name}/`63641. Create `.cursor/skills/` if it doesn't exist652. For each compatible skill:66 - Create `.cursor/skills/{skill-name}/`67 - Copy `SKILL.md` (and optional `reference.md`, `scripts/` if present)68 - Apply adaptations from audit (description, path refs)693. Preserve original `.agent/skills/`—do not delete7071**Do NOT** add skills to `~/.cursor/skills-cursor/`. That directory is reserved for Cursor built-in skills.7273## Quick Commands7475**List project skills:**76```77Get-ChildItem -Path ".agent/skills" -Directory | ForEach-Object { $_.Name }78```7980**Check if SKILL.md exists:**81```82Test-Path ".agent/skills/{skill-name}/SKILL.md"83```8485**Copy a skill to Cursor:**86```87Copy-Item -Path ".agent/skills/{skill-name}" -Destination ".cursor/skills/{skill-name}" -Recurse88```8990## Decision: Project vs Personal9192- **Project** (`.cursor/skills/`): Skills shared with the repo; available only in this workspace93- **Personal** (`~/.cursor/skills/`): Skills for all your projects9495Use project scope for workspace-specific skills (NinjaTrader, UniversalOR, etc.). Use personal for generic skills (pdf, docx, code-formatter).
diegosouzapw