# Create Skill > Creates a new agent skill following best practices for structure, description writing, and progressive disclosure. Use when the user wants to author a new SKILL.md, scaffold a skill directory, or build a reusable skill. Do NOT use for improving an existing skill — use optimize-skill instead. - Skill: `tomevault-io/create-skill-3` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/create-skill-3` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/create-skill-3/raw - Safety review: pending (external: skill-scanner PASS, skillspector CAUTION) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - License: MIT - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/create-skill-3 --- ## Workflow Follow these 9 steps in order. Copy this checklist into your response and check off each step as you complete it: ``` Task Progress: - [ ] Step 1: Understand the skill with concrete examples - [ ] Step 2: Choose skill name - [ ] Step 3: Write description - [ ] Step 4: Write frontmatter - [ ] Step 5: Write SKILL.md body - [ ] Step 6: Decide on progressive disclosure - [ ] Step 7: Create bundled resources - [ ] Step 8: Validate - [ ] Step 9: Iterate ``` ### Step 1: Understand the Skill with Concrete Examples Work through 2-3 concrete examples of how the skill will be used. Ask the user: - What does the skill do? Can you show me an example of how you'd use it? - What would a user say that should trigger this skill? - Does it need `allowed-tools` (does it run shell commands, use MCP tools)? - Should this be a background skill? (always-loaded context, not user-invocable — see frontmatter-spec for `user-invocable: false`) For each example, walk through how it would be executed from scratch. This reveals what knowledge, scripts, or assets are needed. Classify the skill category: - **Document/asset creation** — generates files, reports, configs - **Workflow automation** — multi-step processes, scaffolding, setup - **MCP enhancement** — extends or coordinates MCP server capabilities ### Step 2: Choose Skill Name Rules: - Gerund form for processes (`creating-components`), noun form for tools (`code`) - Kebab-case, max 64 characters, must match folder name ### Step 3: Write the Description This is the highest-impact field — a poor description causes the skill to never be invoked. Follow the "What + When" formula and all rules in: -> See [description-writing](reference/description-writing.md) ### Step 4: Write the Frontmatter Use the exact YAML schema and constraints in: -> See [frontmatter-spec](reference/frontmatter-spec.md) ### Step 5: Write the SKILL.md Body Rules: - Under 500 lines (~5,000 words max) - Only include knowledge the agent does not already have — do not teach general programming, standard libraries, or well-known tools - No time-sensitive information (versions that expire, URLs that rot) - Consistent terminology throughout — pick one term for each concept and stick with it - Imperative voice - For any workflow with 3+ steps, include a copyable task list checklist (`- [ ]` items) that the agent copies and checks off as it progresses — this prevents step-skipping and makes progress observable - Match instruction specificity to task fragility — see "Degrees of Freedom" in skill-patterns Choose the best skill pattern for the use case: -> See [skill-patterns](reference/skill-patterns.md) ### Step 6: Decide on Progressive Disclosure Determine whether content belongs in SKILL.md or in bundled resources: -> See [progressive-disclosure](reference/progressive-disclosure.md) ### Step 7: Create Bundled Resources (If Needed) A skill can include three types of bundled resources: - **`reference/`** — Documentation loaded into context as needed (schemas, guides, examples). One level deep, one topic per file, kebab-case filenames. - **`scripts/`** — Executable code (Python, Bash, etc.) for tasks needing deterministic reliability or repeatedly rewritten code. Test scripts by running them. - **`assets/`** — Files used in output but not loaded into context (templates, fonts, icons, boilerplate). Do NOT create extraneous files like README.md, CHANGELOG.md, or INSTALLATION_GUIDE.md inside the skill folder. The skill should only contain what the agent needs to do the job. ### Step 8: Validate **Triggering test:** Ask the agent "When would you use the [skill-name] skill?" — it should quote the description back accurately. If it cannot, revise the description. **Anti-patterns check:** Review the skill against the anti-patterns list: -> See [anti-patterns](reference/anti-patterns.md) **Final checks:** - SKILL.md is under 500 lines - All links to bundled resources resolve to existing files - Frontmatter YAML is valid (check with a YAML parser if available) - No agent-specific language — the skill should work with any agent supporting the open skill standard - No XML angle brackets in frontmatter fields ### Step 9: Iterate Skills are living documents. After the initial version: 1. Use the skill on real tasks 2. Observe where the agent struggles or takes unexpected paths 3. Watch for triggering issues: - **Under-triggering** (skill doesn't load when it should) — add more trigger phrases and keywords to the description - **Over-triggering** (skill loads for unrelated queries) — add negative triggers ("Do NOT use for X"), narrow scope - **Instructions not followed** — put critical instructions at the top, use stronger language, consider scripts for deterministic operations 4. Update SKILL.md and bundled resources based on observations 5. Re-test and repeat ## Output Deliver the complete skill directory to the user: - `skills/{skill-name}/SKILL.md` - `skills/{skill-name}/reference/*.md` (if applicable) - `skills/{skill-name}/scripts/*.py` (if applicable) - `skills/{skill-name}/assets/*` (if applicable) Summarize what was created and suggest testing the skill by invoking it with one of the identified use cases. --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/hyf0) — claim your Tome and manage your conversions.