| 1 | --- |
| 2 | name: skill-creator |
| 3 | description: Create or improve codewhale skills. Use when the user wants a new skill, wants to update an existing skill, or needs guidance on when a skill should be a skill versus MCP, hooks, tools, or a plugin scaffold. |
| 4 | metadata: |
| 5 | short-description: Create Codewhale skills |
| 6 | aliases-for: create-skill |
| 7 | --- |
| 8 | |
| 9 | # Skill Creator |
| 10 | |
| 11 | Use this skill to create small, useful codewhale skills that match the |
| 12 | runtime this repository actually ships. |
| 13 | |
| 14 | ## What A Skill Is |
| 15 | |
| 16 | A skill is a local folder with a `SKILL.md` file. Codewhale reads the skill name |
| 17 | and description during discovery, then loads the body only when the user or task |
| 18 | matches the skill. |
| 19 | |
| 20 | Discovery paths, in precedence order: |
| 21 | |
| 22 | - `<workspace>/.agents/skills` |
| 23 | - `<workspace>/skills` |
| 24 | - `<workspace>/.opencode/skills` |
| 25 | - `<workspace>/.claude/skills` |
| 26 | - `<workspace>/.cursor/skills` |
| 27 | - `<workspace>/.codewhale/skills` |
| 28 | - `~/.agents/skills` |
| 29 | - `~/.claude/skills` |
| 30 | - `~/.codewhale/skills` |
| 31 | |
| 32 | Use skills for model instructions, workflows, and lightweight conventions. Use |
| 33 | MCP for live external APIs or durable tools. Use hooks for automatic local |
| 34 | events. To distribute a skill through a plugin bundle, give the bundle a |
| 35 | `plugin.json` whose `net.codewhale` extension points `skills.path` at a |
| 36 | directory holding `<name>/SKILL.md` folders; each skill then loads namespaced |
| 37 | as `<plugin>:<skill>` after review, trust, and enablement. A bare `SKILL.md` |
| 38 | directory is discoverable on the skills paths above but is not a plugin |
| 39 | bundle and cannot be installed through `/plugin install`. |
| 40 | |
| 41 | ## Minimum Shape |
| 42 | |
| 43 | ```text |
| 44 | my-skill/ |
| 45 | `-- SKILL.md |
| 46 | ``` |
| 47 | |
| 48 | ```markdown |
| 49 | --- |
| 50 | name: my-skill |
| 51 | description: Use when Codewhale should follow this specific workflow. |
| 52 | --- |
| 53 | |
| 54 | # My Skill |
| 55 | |
| 56 | Instructions for the agent. |
| 57 | ``` |
| 58 | |
| 59 | Frontmatter parsing is intentionally simple. Keep `name` and `description` as |
| 60 | plain single-line values. Use lower-case hyphen-case names. |
| 61 | |
| 62 | ## Writing Rules |
| 63 | |
| 64 | - Make the `description` action-oriented and trigger-specific. It is the main |
| 65 | signal Codewhale sees before loading the body. |
| 66 | - Keep the body operational. Include what to do, what to avoid, and how to |
| 67 | verify the result. |
| 68 | - Do not include general programming advice, marketing copy, or long background |
| 69 | material. |
| 70 | - Move bulky details to `references/` and mention exactly when to open them. |
| 71 | - Add `scripts/` only for deterministic helpers that are worth maintaining. |
| 72 | - Add `assets/` only for templates, fixtures, examples, or files reused by the |
| 73 | workflow. |
| 74 | - Do not assume scripts are safe to run. Community skill scripts require user |
| 75 | intent and trust review. |
| 76 | |
| 77 | ## Creation Workflow |
| 78 | |
| 79 | 1. Define the skill boundary in one sentence. |
| 80 | 2. Decide whether a skill is the right surface: |
| 81 | - Instructional workflow: skill |
| 82 | - External service/API: MCP server plus an optional skill |
| 83 | - Repeated shell helper: local tool or script plus an optional skill |
| 84 | - Packaging multiple pieces: plugin scaffold plus skill/MCP activation notes |
| 85 | 3. Create `<skill-name>/SKILL.md`. |
| 86 | 4. Write frontmatter with `name` and `description`. |
| 87 | 5. Write a concise body with: |
| 88 | - trigger and scope |
| 89 | - required inputs or assumptions |
| 90 | - step-by-step workflow |
| 91 | - validation checks |
| 92 | - safety notes |
| 93 | 6. Add companion files only when they reduce real complexity. |
| 94 | 7. Validate by loading the skill through `/skills` or by running the relevant |
| 95 | skill discovery tests if editing this repository. |
| 96 | |
| 97 | ## Updating Existing Skills |
| 98 | |
| 99 | - Preserve the user's local intent. Avoid replacing a working skill wholesale |
| 100 | unless the user asked for a rewrite. |
| 101 | - Tighten descriptions when the skill is under-triggering or over-triggering. |
| 102 | - Remove stale tool names, unavailable dependencies, and copied instructions |
| 103 | from other agents that do not apply to codewhale. |
| 104 | - Keep examples short and directly tied to this runtime's commands and tools. |
| 105 | |
| 106 | ## Validation Checklist |
| 107 | |
| 108 | - `SKILL.md` starts with `---`. |
| 109 | - `name` matches the directory name unless there is a deliberate reason. |
| 110 | - `description` says when to use the skill, not just what it is. |
| 111 | - The body references only tools, commands, and paths that exist or are clearly |
| 112 | optional. |
| 113 | - Any scripts or external-service steps explain credential and trust handling. |
| 114 |