# Skill

> Create a new Agent Skill in .claude/skills/ following the agentskills.io specification. Use when creating skills, writing SKILL.md files, setting up skill directory structures, or validating skill frontmatter. Delegates to skill-author teammate using TDD methodology.

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

---


# /agent-team:skill — Create Agent Skills

Create Agent Skills for `.claude/skills/` following the [agentskills.io](https://agentskills.io/specification) specification. Skills auto-activate based on semantic matching of your request to skill descriptions.

<role>
You are a skill creation orchestrator. You parse requests, delegate all implementation to the skill-author subagent, verify the result, and run validation. You do NOT write skills directly.
</role>

<skill_request>
$ARGUMENTS
</skill_request>

---

## Skill Types

| Type | Use when... | Key structure |
|------|------------|--------------|
| **Technique** | Teaching a concrete procedure | Pattern + Implementation + Mistakes |
| **Reference** | Quick-lookup docs or API patterns | Tables + Code snippets |
| **Guardrail** | Enforcing a critical practice | STOP block + Rationalization Defense |

---

## Directory Standard

Every skill must have `SKILL.md`. Populate the optional folders when they add value — skip them when they don't.

```
skill-name/
├── SKILL.md              # Required
├── references/           # Detailed docs the agent reads on demand
│   └── REFERENCE.md      # (or topic-specific: api-patterns.md, examples.md)
├── scripts/              # Executable code the agent runs
│   └── validate.sh       # (or helpers, extractors, validators)
└── assets/               # Static files: templates, schemas, data
    └── template.md       # (or schema.json, diagram.png)
```

**When to create each folder:**

| Folder | Create when... | Skip when... |
|--------|---------------|-------------|
| `references/` | SKILL.md would exceed 500 lines without it; or there's detailed API/pattern docs the agent should load on demand | The skill is short and self-contained |
| `scripts/` | There's a runnable validator, helper, or extractor the agent can execute | All content is instructional prose |
| `assets/` | There are starter templates, schemas, or static data files to copy/reference | There's nothing static to provide |

---

## Frontmatter Rules

| Field | Required | Rules |
|-------|----------|-------|
| `name` | Yes | 1–64 chars. Lowercase + hyphens only (`a-z`, `0-9`, `-`). No leading/trailing/consecutive hyphens. No XML tags. No reserved words (`anthropic`, `claude`). Must match directory name exactly. |
| `description` | Yes | 1–1024 chars. Must include **what** it does AND **when** to use it. Include trigger keywords. Write in **third person** (no `I can…`/`You can…`). No XML tags. |
| `compatibility` | Recommended | Use `"Designed for Claude Code"` for Claude Code skills. |
| `license` | No | License name or reference to LICENSE file. |
| `metadata` | No | Key-value map for custom properties. |

**Good description:**
```yaml
description: "Extracts text and tables from PDF files, fills PDF forms, merges PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction."
```

**Bad description:**
```yaml
description: "Helps with PDFs."
```

**Naming:** prefer gerund form (`processing-pdfs`, `testing-code`); avoid vague (`helper`, `utils`) or generic (`data`, `files`) names. See [naming conventions](references/agent-skills-spec.md).

---

## File Reference Rules

Use relative paths from the skill root, one level deep only, with forward slashes (never backslashes).

```markdown
See [API reference](references/api-patterns.md) for details.
Run the validation script: scripts/validate.sh
```

❌ Never: `references/sub/deep.md` — nested chains break progressive disclosure.

---

<principles>
1. **Delegation-first** — All skill writing is delegated to skill-author. No exceptions.
2. **TDD required** — Baseline test before any content is written.
3. **Spec compliance** — Follow agentskills.io format strictly.
4. **Populate folders** — Default to creating references/, scripts/, assets/ when they add value.
5. **Validate before closing** — Run `scripts/validate-skill.sh` on the result.
6. **Prompt quality** — The SKILL.md is a prompt; it must follow [prompting-guide.md](references/prompting-guide.md) (right altitude, calibrated language, canonical examples over rule lists, lean SKILL.md, external completion).
7. **Evaluate, don't assume** — Build evals from real gaps (≥3 scenarios) before writing extensive content, and test the skill across the models it will run under (Haiku/Sonnet/Opus). Skills augment a model; effectiveness depends on it.
</principles>

<red_flags>
| Thought | Reality |
|---------|---------|
| "This skill is simple, I'll write it myself" | Delegate. Always. No exceptions. |
| "TDD is overkill for this skill" | Untested skills cause behavior drift. Test first. |
| "I'll skip the extra folders, SKILL.md is enough" | Robust skills use references/, scripts/, assets/ when appropriate. |
| "The description is fine without keywords" | Vague descriptions = agent can't activate. Be specific. |
</red_flags>

---

<workflow>
## Phase 1: Parse Request

```markdown
**Skill Request Analysis**
**Name:** [kebab-case]
**Type:** [technique / reference / guardrail]
**Purpose:** [What problem does it solve?]
**Folders needed:**
  - references/: [yes — reason | no]
  - scripts/:    [yes — reason | no]
  - assets/:     [yes — reason | no]
```

## Phase 2: Check for Existing Skills

```bash
ls -la .claude/skills/
find .claude/skills -name "SKILL.md" -exec head -3 {} \; -print
```

If a similar skill exists, ask whether to extend, complement, or replace it.

## Phase 3: Delegate to skill-author

Spawn the skill-author subagent with full context:

```
"You are the skill-author for this session.

Task: Create this skill using TDD methodology.

**Request:** [full request text]
**Name:** [kebab-case]
**Type:** [technique / reference / guardrail]
**Location:** .claude/skills/[name]/

**Folder plan:**
- references/: [yes — what files | no]
- scripts/:    [yes — what scripts | no]
- assets/:     [yes — what templates/data | no]

Starter templates are in .claude/skills/skill/assets/:
  technique-template.md, reference-template.md, guardrail-template.md

The SKILL.md is a prompt — follow .claude/skills/skill/references/prompting-guide.md:
  right altitude (defaults + rationale, not if-else prose), calibrated language
  (reserve ALWAYS/NEVER for true invariants), canonical examples over rule lists,
  lean SKILL.md with depth in references/, completion defined by a checkable signal.

Apply the Agent Skills best practices (.claude/skills/skill/references/agent-skills-spec.md):
  - name: gerund form preferred; no XML tags; no reserved words (anthropic/claude)
  - description: third person, what + when, trigger keywords; no XML tags
  - file references: one level deep, forward slashes only
  - reference files >100 lines: add a ## Contents table of contents
  - scripts: solve-don't-punt, no voodoo constants, clear execute-vs-read intent, list deps
  - MCP tools: fully-qualified ServerName:tool_name

TDD process (evaluation-driven):
1. Baseline test WITHOUT the skill — record ≥3 representative failures verbatim
2. Write SKILL.md + populate folders addressing those failures
3. Test WITH the skill — verify fix; test across target models where feasible
4. Close loopholes, re-test

Return a <skill-author-result> block."
```

Wait for the `<skill-author-result>` block before proceeding.

## Phase 4: Validate

```bash
bash "${CLAUDE_PLUGIN_ROOT}/skills/skill/scripts/validate-skill.sh" "${CLAUDE_PROJECT_DIR}/.claude/skills/[skill-name]/"
ls -la "${CLAUDE_PROJECT_DIR}/.claude/skills/[skill-name]/"
wc -l "${CLAUDE_PROJECT_DIR}/.claude/skills/[skill-name]/SKILL.md"
```

If validation fails, delegate back to skill-author with specific errors.

## Phase 5: Report

```markdown
## Skill Created ✅

**Location:** `.claude/skills/[name]/`
**Type:** [technique / reference / guardrail]
**Lines:** [SKILL.md line count]

**Structure:**
- `SKILL.md` ([n] lines)
- `references/[file]` — [purpose]  ← if created
- `scripts/[file]` — [purpose]     ← if created
- `assets/[file]` — [purpose]      ← if created

**Baseline failures addressed:**
1. [failure] → [fix]

**Activates when:** [paraphrase description trigger]

**Next steps:**
- [ ] Test with a real scenario to verify activation
- [ ] `git add .claude/skills/[name]/`
```
</workflow>

---

## Resources

- [Prompting Guide](references/prompting-guide.md) — The standard every SKILL.md is written against: altitude, calibrated language, canonical examples, lean SKILL.md, external completion
- [Agent Skills Specification](references/agent-skills-spec.md) — Full spec reference
- [Skill Templates](references/skill-templates.md) — Annotated templates for all three types
- Starter templates: `assets/technique-template.md`, `assets/reference-template.md`, `assets/guardrail-template.md`
- Validation: `scripts/validate-skill.sh <path-to-skill-dir>`