# Create Agent Skill En

> Creates a new Agent Skill that follows the agentskills.io open specification. Use this skill whenever a user or agent wants to author a new skill, scaffold a skill directory, write a SKILL.md, add reference files, or add scripts to an existing skill. Activate for phrases like: "create a skill", "write a skill", "new skill for X", "scaffold a skill", "add a skill to my repo", or "make a SKILL.md".

- Skill: `roebi/create-agent-skill-en` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add roebi/create-agent-skill-en`
- Raw SKILL.md: https://api.skillmd.com/api/skills/roebi/create-agent-skill-en/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: CC BY-NC-SA 4.0
- Author: roebi (https://skillmd.com/u/roebi)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/roebi/create-agent-skill-en

---


# Create Agent Skill

Guides you through authoring a new Agent Skill that complies with the
[agentskills.io specification](https://agentskills.io/specification).

## Specification constraints (must follow exactly)

| Field         | Rule |
|---------------|------|
| `name`        | 1–64 chars. Lowercase `a-z`, digits, hyphens only. No leading/trailing/consecutive hyphens. Must match directory name. |
| `description` | 1–1024 chars. Describes what the skill does AND when to activate it. |
| `license`     | Optional. Short license name or reference to bundled `LICENSE.txt`. When scaffolding a new skill a default `LICENSE` file with **CC BY-NC-SA 4.0** should be added and the frontmatter set accordingly. |
| `compatibility` | Optional, max 500 chars. List environment requirements only if non-obvious. |
| `metadata`    | Optional. Arbitrary key-value string map. |
| `allowed-tools` | Optional, experimental. Space-delimited list of pre-approved tools. |

The `SKILL.md` body has **no format restrictions** — write whatever helps
agents perform the task. Keep it under 500 lines; move detail to `references/`.

## Directory layout

```
<skill-name>/
├── SKILL.md            # Required
├── references/         # Optional — load on demand, keep files focused
├── scripts/            # Optional — executable code (see scripts guide)
└── assets/             # Optional — templates, static files
```

## Step-by-step workflow

### 1. Gather intent

Before writing anything, clarify:

- **What does this skill do?** One clear sentence.
- **When should an agent activate it?** List trigger phrases and contexts.
- **What is the expected output?** File, command, explanation, ...
- **Are there environment dependencies?** Binaries, network access, credentials?
- **Should there be scripts?** If tasks are repetitive or complex, yes.

### 2. Choose the skill name

```bash
# Name must match the directory you will create
# Good names: pdf-processing, git-workflow, terminal-cli, code-review
# Bad: PDFProcessing, pdf_processing, -pdf, pdf--processing
```

### 3. Create the directory

```bash
mkdir -p skills/<skill-name>/references
mkdir -p skills/<skill-name>/scripts   # only if scripts are needed
```

> **Tip:** specify `license: CC BY-NC-SA 4.0` in your SKILL.md frontmatter. A standalone
> `LICENSE` file is *optional*—the spec only requires the field, not a separate file. Keep it
> simple.

### 4. Write SKILL.md

Start with the frontmatter, then the body (the spec only cares about the field):

```markdown
---
name: <skill-name>
license: CC BY-NC-SA 4.0   # a single line is all that's required by agentskills.io
description: >
  One paragraph. First sentence: what it does.
  Remaining sentences: when to activate it, what trigger
  phrases should cause an agent to load this skill.
---

# <Title>

Brief intro paragraph.

## When to use this skill
...

## Step-by-step instructions
...

## Examples
...
```

**Description writing guide:**

- Include both *what* (capabilities) and *when* (trigger contexts).
- List specific keywords agents can match: tool names, file types, verbs.
- Be specific enough that the agent activates this skill and not a generic fallback.
- Bad: `"Helps with PDFs."` — too vague, no trigger signals.
- Good: `"Extracts text and tables from PDF files, fills forms, merges documents. Use when the user mentions PDFs, forms, or document extraction."` — clear capability + trigger.

### 5. Add reference files (if SKILL.md would exceed 500 lines)

```bash
# Create focused reference files — one topic per file
cat > skills/<skill-name>/references/advanced.md << 'EOF'
# Advanced <Topic> Reference
...
EOF
```

Reference them from SKILL.md:

```markdown
For complete options, see `references/advanced.md`.
```

### 6. Add scripts (if needed)

See `references/scripts-guide.md` for full script design rules.

Quick rules:
- No interactive prompts — accept all input via flags or env vars.
- Always implement `--help`.
- Send structured data (JSON/CSV) to stdout, diagnostics to stderr.
- Support `--dry-run` for destructive operations.
- Use exit codes meaningfully (0 = success, 1 = user error, 2 = system error).

### 7. Validate

```bash
# Install the reference validator
pip install skills-ref --break-system-packages

# Validate your skill
skills-ref validate ./skills/<skill-name>

# Preview the XML that agents will see in their context
skills-ref to-prompt ./skills/<skill-name>
```

### 8. Add GitHub topic

After pushing your repo, add the `agent-skills` topic so others can discover
your skill at `https://github.com/topics/agent-skills`.

## Progressive disclosure reminder

An agent loads your skill in three stages:

1. **Startup** — only `name` + `description` (~100 tokens). Make the description do its job.
2. **Activation** — full `SKILL.md` body. Keep under 500 lines.
3. **On demand** — `references/` and `scripts/` files, only when the agent needs them.

Never put everything in `SKILL.md`. If you are approaching 500 lines, split.

## Reference files in this skill

- `references/scripts-guide.md` — detailed guide for writing agentic scripts
- `references/examples.md` — annotated example skills (good and bad)