Skip to main content
skill CX Codex

meta-skill-creator — Claude Code skill: create and install

The meta-skill-creator skill guides you through building and validating agent skills that follow the Agent Skills open standard. Use it to plan a SKILL.md and organize supporting files.

MIT 114 installs ★ 29 updated 2026-08-17

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add oakoss/agent-skills --skill meta-skill-creator -a claude-code
Open on GitHub

What meta-skill-creator does

meta-skill-creator walks through setting up a skill directory, writing the required name and description fields, and adding the required sections to SKILL.md. It also shows how to move code examples into references/ and link supporting files so agents can find them. The skill covers frontmatter and progressive disclosure too.

Before sharing a finished skill, run a project validator or skills-ref validate. The guide distinguishes portable standard fields from Claude Code extensions, which do not carry across agents. For Claude Code, the installation command uses npx skills add; the skill can live in a personal or project directory.

What it helps with

  • scaffold a skill directory and SKILL.md
  • write the required frontmatter fields
  • separate instructions from reference material
  • validate a skill before sharing it

Example prompts for the agent

  • Help me create an Agent Skills skill and draft its SKILL.md.
  • Review my skill folder and suggest what belongs in references/.
  • Draft frontmatter for a new skill and show me how to validate it.

How to install meta-skill-creator

1Skills CLI (Vercel)

npx skills add oakoss/agent-skills --skill meta-skill-creator -a claude-code

2Manually: put the files in place

~/.claude/skills/meta-skill-creator/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/meta-skill-creator/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about meta-skill-creator

How do I install meta-skill-creator in Claude Code?

Run npx skills add oakoss/agent-skills --skill meta-skill-creator -a claude-code. The skill file is at ~/.claude/skills/meta-skill-creator/SKILL.md.

What does meta-skill-creator do?

It guides you through creating an agent skill with the Agent Skills standard, from structuring SKILL.md to organizing reference files and validating the result.

How do I validate a finished skill?

Run your project validator or skills-ref validate before distributing the skill.

Source text

SKILL.md · MIT
---
name: meta-skill-creator
description: >
  Create agent skills following the Agent Skills open standard.
  Use when building new skills for Claude Code, Cursor, Gemini CLI, or other agents.
  Use for skill structure, SKILL.md authoring, frontmatter configuration, progressive disclosure, reference files, validation, and distribution.
license: MIT
metadata:
  author: oakoss
  version: '1.0'
  source: https://agentskills.io
disable-model-invocation: true
---

# Meta Skill Creator

## Overview

Agent Skills are portable folders of instructions, scripts, and resources that agents discover and load on demand. They follow the [Agent Skills open standard](https://agentskills.io) and work across 27+ compatible agents including Claude Code, Cursor, Gemini CLI, OpenAI Codex, VS Code, GitHub Copilot, Windsurf, Goose, and Roo Code. This skill covers the complete workflow for creating, structuring, and validating skills.

## Quick Reference

| Concept                | Summary                                                                  | Key Rule                                         |
| ---------------------- | ------------------------------------------------------------------------ | ------------------------------------------------ |
| Directory structure    | `skill-name/SKILL.md` plus optional `references/`, `scripts/`, `assets/` | `SKILL.md` is the only required file             |
| Frontmatter (required) | YAML block with `name` and `description`                                 | `name` must match directory, max 64 chars        |
| Frontmatter (optional) | `license`, `compatibility`, `metadata`, `allowed-tools`                  | Defined by open standard, portable across agents |
| Agent-specific fields  | `model`, `context`, `agent`, `hooks`, `user-invocable`                   | Claude Code extensions, not portable             |
| Description triggers   | Include "Use when..." or "Use for..." phrases                            | Keyword-rich, third-person voice                 |
| Progressive disclosure | Metadata -> Instructions -> Resources (three tiers)                      | SKILL.md loaded in full; references on demand    |
| SKILL.md size          | Target 100-150 lines, max 500                                            | No code examples in SKILL.md                     |
| SKILL.md sections      | Overview, Quick Reference, Common Mistakes, Delegation, References       | All five sections required                       |
| Reference files        | `references/[topic].md` with frontmatter                                 | Max 500 lines each, self-contained               |
| Reference frontmatter  | `title`, `description`, `tags` fields                                    | Required for all reference files                 |
| Scripts                | `scripts/` directory, executable code                                    | Agents run scripts, not read source              |
| Name format            | Lowercase letters, numbers, hyphens                                      | No `--`, no leading/trailing `-`, min 4 chars    |
| Excluded filenames     | `README.md`, `metadata.json`, `_*` files                                 | Not installed by distribution CLI                |
| Validation             | `skills-ref validate` or project-specific validators                     | Always validate before distributing              |

## Skill Creation Workflow

1. **Create directory** at the appropriate location with a `SKILL.md`
2. **Write frontmatter** with `name` (matching directory) and trigger-rich `description`
3. **Write required sections**: Overview, Quick Reference, Common Mistakes, Delegation, References
4. **Extract code examples** into `references/` files (no code in SKILL.md)
5. **Validate** with your project validator or `skills-ref validate`

## Common Mistakes

| Mistake                                 | Correct Pattern                                                   |
| --------------------------------------- | ----------------------------------------------------------------- |
| Missing "Use when" or "Use for" trigger | Include trigger phrases in description for agent discovery        |
| Code examples in SKILL.md               | Move all code to `references/` files                              |
| SKILL.md over 500 lines                 | Split detailed content into reference files                       |
| Reference files cross-referencing       | Keep references self-contained, one level deep from SKILL.md      |
| Name does not match directory           | `name` field must exactly match parent directory name             |
| Name contains uppercase or spaces       | Use only lowercase letters, numbers, and hyphens                  |
| Vague description without keywords      | Pack triggers with synonyms, abbreviations, library names         |
| Code blocks without language specifier  | Always specify language on fenced code blocks                     |
| Supporting files not linked in SKILL.md | Agents discover files through explicit links in SKILL.md          |
| Using excluded filenames                | Avoid `README.md`, `metadata.json`, files starting with `_`       |
| Blank line before frontmatter           | `---` must be on line 1, no preceding blank lines                 |
| Description in first-person voice       | Use third-person: "Extracts text", not "I help you"               |
| Deeply nested reference chains          | Keep one level deep: SKILL.md links to references directly        |
| Missing required SKILL.md sections      | Include all five: Overview, Quick Ref, Mistakes, Delegation, Refs |
| Reference file missing frontmatter      | Every reference needs `title`, `description`, and `tags`          |

## Skill Locations

Skills can be installed at different scopes depending on visibility needs:

| Location    | Path                | Scope                |
| ----------- | ------------------- | -------------------- |
| Personal    | `~/.claude/skills/` | You, all projects    |
| Project     | `.claude/skills/`   | Anyone in repository |
| Distributed | Via `skills` CLI    | Plugin users         |

## Delegation

- **Specification questions**: Refer to the [Agent Skills open standard](https://agentskills.io/specification)
- **Pattern discovery**: Use `Explore` agent to analyze existing skills for structure examples
- **Validation**: Run project validator or `skills-ref validate` before committing

## References

- [Skill anatomy: directory structure, SKILL.md sections, progressive disclosure, and size thresholds](references/skill-anatomy.md)
- [Frontmatter: required and optional YAML fields with constraints and usage guidance](references/frontmatter.md)
- [Validation: checklist, common issues, and testing your skill](references/validation.md)

© oakoss · MIT · oakoss/agent-skills

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set106

The whole set →

Project sponsors

Companies that keep this analytics open