# Skill Creator

> Scaffolds and reviews new agent skills for this repository, following the Agent Skills spec (SKILL.md frontmatter, progressive disclosure, references/scripts/assets layout). Use when the user asks to create a new skill, turn a workflow or piece of expertise into a skill, or review/improve an existing SKILL.md.

- Skill: `jsvillalbat/skill-creator` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add jsvillalbat/skill-creator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jsvillalbat/skill-creator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: jsvillalbat (https://skillmd.com/u/jsvillalbat)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jsvillalbat/skill-creator

---


# Skill Creator

Helps author skills that live in `skills/<name>/SKILL.md` in this repo, so they work
correctly across Claude Code, Codex, Cursor, and any other Agent Skills-compatible client.

## When to use this

- The user says "make this a skill", "turn this into a skill", "create a skill for X".
- The user asks you to review, clean up, or fix an existing `SKILL.md`.
- You're scaffolding this repo's own tooling-adjacent skills.

## Instructions

1. **Clarify the task the skill captures.** Ask (or infer from context): what triggers
   this skill, and what should the agent actually do once activated? A skill should
   cover one coherent capability — split unrelated workflows into separate skills.

2. **Pick the name.** Lowercase, hyphenated, 1–64 chars, no leading/trailing/double
   hyphens (e.g. `pdf-processing`, not `PDF-Processing` or `-pdf`). The folder name
   under `skills/` must match `frontmatter.name` exactly.

3. **Scaffold it.** Run:

   ```bash
   npm run new <skill-name>
   ```

   This copies `templates/skill-template/SKILL.md` into `skills/<skill-name>/` with the
   name pre-filled.

4. **Write the description first — it matters most.** Agents only see `name` and
   `description` at startup (progressive disclosure, stage 1). A vague description
   means the skill never activates. State both *what it does* and *when to use it*,
   with concrete keywords a real task would mention.
   - Weak: `Helps with PDFs.`
   - Strong: `Extracts text and tables from PDF files, fills PDF forms, and merges
     multiple PDFs. Use when working with PDF documents or when the user mentions
     PDFs, forms, or document extraction.`

5. **Write the body for an agent, not a human reader.** Step-by-step instructions,
   concrete examples, and edge cases. Keep it under ~500 lines / ~5000 tokens — this
   whole file is loaded into context once the skill activates (progressive disclosure,
   stage 2). See `references/skill-spec.md` for the full frontmatter rules.

6. **Push detail out of SKILL.md.** Anything long, occasionally-needed, or reference-y
   (API details, exhaustive option lists, background reading) goes in `references/`,
   and is loaded only if the agent follows a link there (stage 3). Executable helpers
   go in `scripts/`; templates or static files go in `assets/`. Keep file references
   one level deep from SKILL.md — don't chain references to references.

7. **Validate.**

   ```bash
   npm run validate
   ```

   Fixes anything it flags: name/folder mismatch, missing/oversized description,
   oversized body, dangling file references.

8. **Self-review against the checklist** in `references/checklist.md` before calling
   the skill done.

9. **Update the README table:**

   ```bash
   npm run sync-readme
   ```

## Reviewing an existing skill

Read the target `SKILL.md`, then walk it against `references/checklist.md` and
`references/skill-spec.md`. Report concrete fixes (not just "looks fine") — e.g. "the
description doesn't say *when* to use this skill" or "this 800-line body should move
its API reference into `references/`".

## Reference files

- `references/skill-spec.md` — condensed Agent Skills frontmatter/layout spec.
- `references/checklist.md` — pre-flight checklist for a finished skill.