skill-creator

Files (4)

• SKILL.md
• init-skill.sh · scripts/
• paths.sh · scripts/lib/
• validate-skill.sh · scripts/

SKILL.md (first lines)

# Skill Creator

## Overview

End-to-end authoring system for agent skills: gate the request, scaffold under `skills/`, write SKILL.md, validate, and confirm symlink discovery.

## Instructions

Follow every phase in order unless a skip condition applies.

### Repository Layout

```
<repo-root>/
├── skills/                    # canonical storage — write skills HERE
│   ├── skill-creator/
│   └── <skill-name>/
├── .cursor/skills -> ../skills   # symlink — never write here
└── .claude/skills -> ../skills   # symlink — never write here
```

Agents discover skills via the symlinks, but **all files must be created under `skills/`**.

### Script Invocation (Critical)

Bundled scripts resolve paths from **their own location**, not the shell's current working directory. You may run them from anywhere.

| Script | Purpose |
|--------|---------|
| `scripts/init-skill.sh` | Scaffold a new skill under the skills root |
| `scripts/validate-skill.sh` | Validate structure and content |
| `scripts/lib/paths.sh` | Shared path logic (sourced by other scripts, do not run) |

Always invoke with the repo-relative path:

```bash
skills/skill-creator/scripts/init-skill.sh <skill-name>
skills/skill-creator/scripts/validate-skill.sh <skill-name>
skills/skill-creator/scripts/validate-skill.sh <skill-name> --strict
```

**Never** pass `.cursor/skills` or `.claude/skills` as an output directory. `init-skill.sh` refuses paths outside the canonical skills root.

### Phase 0: Skill-Worthiness Gate

Before any scaffolding, decide whether a skill is the right abstraction.

**Create a skill when** the task encodes non-obvious knowledge: company workflows, proprietary APIs, multi-step procedures, platform-specific integrations, or repeatable patterns the base model would get wrong.

**Do not create a skill when** the request is general knowledge, basic reasoning, a one-off answer, or a test/demo explicitly labeled as such.

If the request fails the gate, tell the user why and suggest alternatives (a rule, a one-shot answer, or a `--profile minimal` test skill if they insist on scaffolding).

### Phase 1: Requirements

**Skip elicitation** when the user already provided: skill name, 1+ trigger phrases, and the core behavior.

**Otherwise ask** until you have:
- 2-3 concrete example tasks
- Exact trigger phrases users will say
- Target platform (Cursor, Claude, Codex, Grok, etc.)
- Constraints (APIs, security, languages)

### Phase 2: Choose Profile & Architecture

```
Is the skill a test/demo OR under ~40 lines with no scripts/references?
  yes → minimal profile
  no  → full profile
```

| Profile | When | Resources |
|---------|------|-----------|
| **minimal** | Demos, smoke tests, single-behavior skills | SKILL.md only |
| **full** | Production workflows | scripts/, references/, assets/ as needed |

Map tasks to resources:
- **scripts/** — deterministic logic you'd rewrite every time
- **references/** — long docs loaded on demand (>100 lines → add TOC)
- **assets/** — templates/files copied or modified, not read into context

Confirm the skill name is kebab-case, descriptive, and unique under `skills/`.

### Phase 3: Scaffold

Run init from anywhere:

```bash
skills/skill-creator/scripts/init-skill.sh <skill-name> --profile minimal
skills/skill-creator/scripts/init-skill.sh <skill-name> --profile full --resources scripts,references
```

Verify output lands in `skills/<skill-name>/`, not a symlink path.

### Phase 4: Frontmatter

Write YAML first. Rules:
- `name`: kebab-case, 2-64 chars, starts/ends with letter or digit, **must match directory name**
- `description`: max 1024 chars, includes `Triggers:` phrase list; wrap in double quotes if value contains `: `

```yaml
---
name: my-skill
description: "Does X for Y team. Triggers: do X, run X workflow, help with X."
---
```

### Phase 5: Author SKILL.md Body

**minimal profile** — required sections only:
1. `# Title`
2. `## Overview` (1 sentence)
3. `## Instructions` (numbered imperative steps)

**full profile** — add:
4. `### Workflow` with numbered steps
5. `### Edge Cases` with if/then rules
6. `## Example` with user input + expected response
7. `## Testing` with validate command

From amarjeet/agent-skills, MIT.

More from amarjeet/agent-skills