---

name: engineer-skill description: >- Guide for creating agent-invocable Agent Skills (SKILL.md packages auto-discovered by description). Use when users want to create or author a skill, or ask about skill structure or format. Not for user-invoked slash commands. Works across IDEs. license: 'Based on https://github.com/anthropics/skills'

Skill Creator

This skill guides through creating effective Agent Skills — markdown-based packages that teach AI agents specialized workflows, domain knowledge, and procedural capabilities.

Question Format (FR-UNIVERSAL.QA-FORMAT)

When asking the user a choice (IDE, scope, behavior decisions):

• Numbered — each question is a numbered list item (1., 2., …), not a heading, a bold-only line, or a paragraph.
• Self-contained — the question is answerable from itself and its options alone. Name what is being decided and what the answer changes, inside the question. "Which of the above?", a bare "Your choice?", and "Which variant do you prefer?" with nothing restated are defects: they send the reader back up the transcript to reconstruct the question.
• Each option stands on its own — a reader often jumps straight to the options, so an option's title and the lines under it must be enough to choose without the text above the question or the earlier turns. The title is a short name after the option's letter or number, and the reader answers with that letter or number; the **Essence:** line under it says what would be done, to what, and what the reader gets. A short reply option with no analysis of its own (Apply / Skip / Edit) has no Essence line, and its title says it alone. Inside an option, name things in words, never by a report's ids. Every line of the option — title, Essence, Pros, Cons, Risks, Best for — is read without the report, and ids slip in most often in Pros, Cons and Risks. Write what the thing is instead of its label: "the checkout errand on the shop site", not E4; "the search box ignoring the first keystroke", not N3. A label in parentheses after a general phrase — "the two most expensive errands (E4, E3)" — is still a bare label: name each item. A number taken from a report keeps what it measures in the same sentence: a percentage names the whole it is a share of ("page text takes about 40% of the cost", not "a 40% share"), and a sum says whose cost it is. Any phrase that stands for a group is a pointer: a count ("the four slow pages", "the same three errands"), a category ("the anomalies", "the issues found"), a rank or superlative ("the costliest runs"), "these", "as above", "the current round" — and so is a partial list, a count followed by a few examples or a "such as". Replace it with every member of the group, named in words, in that option — even when the list is long, even when the report above already lists them; if the whole set does not fit, drop the group from the option. Test: with the report deleted, could the reader name every member from this option alone? A word coined in this session gets a short explanation in the option. An explanation elsewhere in the reply does not count — not in the report above the question, not in another option. Before sending, read each option alone, line by line, and list every label (letters plus digits such as E4 or N3), number, group phrase (a count, a category, a superlative, "the same", "these") and coined term in it; replace each with words or remove it.
• No catch-all option — never add an option whose only content is an invitation to answer freely ("Other", "Something else", "Your own variant", "Tell me what you need"). The user can always type a free-form reply instead of a letter or number, and an IDE's question tool (AskUserQuestion and the like) already offers a free-text answer of its own, so such an option adds a line and no choice. An option that names a concrete alternative is a real option, even when its title starts with "Other".
• agent's choice — on a multi-select where the user delegates with agent's choice (or its language equivalent), pick the subset yourself, justify the pick in one line, and proceed without re-asking for confirmation.
• When the choices are mutually exclusive alternatives with their own analysis, that analysis is nested under the option inside the question — never repeated as a separate block before it. It opens with the **Essence:** line, then **Pros:**, **Cons:**, **Risks:** and **Best for:**, each on its own labelled line.

About Skills

Skills are self-contained packages (directory with SKILL.md) that extend agent capabilities with:

1. Specialized workflows — multi-step procedures for specific domains
2. Tool integrations — instructions for working with specific file formats or APIs
3. Domain expertise — company-specific knowledge, schemas, business logic
4. Bundled resources — scripts, references, and assets for complex tasks

IDE Detection and Skill Placement

Skills work across multiple IDEs. Before creating a skill, determine the current environment and ask the user where to place it.

Control Primitives Map by IDE

| Primitive | Scope | Claude Code | Cursor | OpenCode | | :--- | :--- | :--- | :--- | :--- | | Persistent Instructions | User | ~/.claude/CLAUDE.md | - | ~/.config/opencode/AGENTS.md<br>~/.claude/CLAUDE.md (fallback) | | | Project | CLAUDE.md<br>.claude/rules/*.md | AGENTS.md<br>.cursor/rules/*/RULE.md<br>~~.cursor/rules/*.mdc~~ | AGENTS.md<br>CLAUDE.md (fallback)<br>opencode.json instructions | | | Folder | subdir/CLAUDE.md<br>CLAUDE.local.md | subdir/AGENTS.md | - | | Conditional Instructions | Project | .claude/rules/*.md | .cursor/rules/*/RULE.md<br>~~.cursor/rules/*.mdc~~ | opencode.json instructions (globs) | | Custom Commands | User | ~/.claude/commands/*.md | ~/.cursor/commands/*.md | ~/.config/opencode/commands/*.md | | | Project | .claude/commands/*.md<br>.claude/commands/<namespace>/*.md | .cursor/commands/*.md | .opencode/commands/*.md | | Skills | User | ~/.claude/skills/<name>/ | ~/.cursor/skills/<name>/ | ~/.config/opencode/skills/<name>/<br>~/.claude/skills/<name>/ (fallback) | | | Project | .claude/skills/<name>/ | .cursor/skills/<name>/ | .opencode/skills/<name>/<br>.claude/skills/<name>/ (fallback) | | Event Hooks | User | ~/.claude/settings.json | ~/.cursor/hooks.json | ~/.config/opencode/plugins/*.{js,ts} | | | Project | .claude/settings.json<br>.claude/settings.local.json | .cursor/hooks.json | .opencode/plugins/*.{js,ts} | | MCP Integration | User | settings.json<br>managed-mcp.json | ~/.cursor/mcp.json | opencode.json mcp | | | Project | .mcp.json | .cursor/mcp.json | opencode.json mcp | | Context Ignoring | User | .claude/settings.json | - | - | | | Project | - | .cursorignore | .gitignore<br>.ignore<br>opencode.json watcher.ignore |

Skill-Specific Paths

| IDE | Personal Skills | Project Skills | |-----|----------------|----------------| | Cursor | ~/.cursor/skills/<name>/ | .cursor/skills/<name>/ | | Claude Code | ~/.claude/skills/<name>/ | .claude/skills/<name>/ | | OpenCode | ~/.config/opencode/skills/<name>/ | .opencode/skills/<name>/ |

OpenCode also reads skills from fallback locations: .claude/skills/, .agents/skills/, ~/.claude/skills/, ~/.agents/skills/.

Detection Strategy

1. Check for IDE-specific markers in the project:
   • .cursor/ directory → Cursor
   • .claude/ directory → Claude Code
   • .opencode/ directory or opencode.json → OpenCode
2. If multiple detected or none → ask the user
3. Ask: personal skill (user-level) or project skill (shared via repo)?

IMPORTANT: Never create skills in ~/.cursor/skills-cursor/ — reserved for Cursor internals.

Core Principles

Concise is Key

Context window is shared with conversation, other skills, and user request. Every token competes for space.

Default assumption: the agent is already very smart. Only add context it doesn't already have.

Challenge each piece:

• "Does the agent really need this explanation?"
• "Does this paragraph justify its token cost?"

Prefer concise examples over verbose explanations.

Set Appropriate Degrees of Freedom

| Freedom Level | When to Use | Example | |---------------|-------------|---------| | High (text instructions) | Multiple valid approaches, context-dependent | Code review guidelines | | Medium (pseudocode/templates) | Preferred pattern with acceptable variation | Report generation | | Low (specific scripts) | Fragile operations, consistency critical | Database migrations |

Anatomy of a Skill

Every skill: required SKILL.md + optional bundled resources in a directory:

skill-name/
├── SKILL.md              # Required - main instructions
├── references/           # Optional - detailed documentation
│   ├── api_reference.md
│   └── patterns.md
├── scripts/              # Optional - executable code
│   └── validate.py
└── assets/               # Optional - output resources
    └── template.md

SKILL.md (required)

• Frontmatter (YAML): name and description fields. These determine when the skill triggers.
• Body (Markdown): Instructions loaded AFTER skill triggers.

Bundled Resources (optional)

| Type | Path | Purpose | When to Include | |------|------|---------|-----------------| | Scripts | scripts/ | Executable code (Python/Bash) | Same code rewritten repeatedly; deterministic reliability needed | | References | references/ | Documentation loaded into context as needed | Detailed info too lengthy for SKILL.md | | Assets | assets/ | Files used in output (templates, images, fonts) | Templates, boilerplate, images for final output |

What NOT to Include

No README.md, CHANGELOG.md, INSTALLATION_GUIDE.md, or other auxiliary docs. The skill contains only what the agent needs to do the job.

Progressive Disclosure

Three-level loading to manage context:

1. Metadata (name + description) — always in context (~100 words)
2. SKILL.md body — when skill triggers (<5k words)
3. Bundled resources — as needed (unlimited)

Keep SKILL.md under 500 lines. Split content into separate files when approaching this limit. Reference them clearly from SKILL.md with guidance on when to read them.

Important: Keep references one level deep from SKILL.md. Avoid deeply nested chains.

Writing Effective Descriptions

Description is critical for skill discovery. The agent uses it to decide when to apply the skill.

Rules

1. Third person (injected into system prompt):

   • Good: "Processes Excel files and generates reports"
   • Bad: "I can help you process Excel files"

2. Specific with trigger terms:

   • Good: "Extract text/tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction."
   • Bad: "Helps with documents"

3. Include WHAT and WHEN (the WHEN phrase is MANDATORY, not optional):

   • WHAT: specific capabilities
   • WHEN: trigger scenarios — an explicit phrase such as "Use when …" or "when the user …"
   • Enforced: validate_skill.ts (and flowai's check-skills.ts for every skills/ primitive) reject a description that has no recognized WHEN-trigger phrase. Lazy forms ("How to X", "Helps with X", a bare domain label) fail.

Constraints

| Field | Limit | |-------|-------| | name | Max 64 chars, [a-z0-9-] only, no leading/trailing/consecutive hyphens | | description | Max 1024 chars, no angle brackets <> | | name + description combined | <100 tokens (~400 chars; chars/4 approx) — the flowai validator check-skills.ts rejects over-budget catalog metadata. Agents load this tuple at session start for skill discovery; over-budget means the skill won't be visible. Aim for ~75 tokens to leav