Fabrico Creating Skills

---
name: fabrico-creating-skills
description: "Creates and reviews repository skills under .claude/skills using gerund naming, concise routing descriptions, progressive disclosure, templates, and validation checklists. Use when creating, reviewing, updating, or organizing SKILL.md files."
---

# Creating Skills

Creates well-structured, reusable skills for Claude Code. Enforces naming conventions, content structure, and progressive disclosure patterns based on the Agent Skills specification and best practices.

## Core Design Principles

<principles>

<what-is-a-skill>
A skill is a folder (under `.claude/skills/` in a project, or `~/.claude/skills/` for global) containing a `SKILL.md` file with YAML frontmatter and Markdown instructions. Skills provide **procedural knowledge** — step-by-step workflows, domain-specific context, templates, and reference materials that Claude loads on demand to perform specialized tasks.

- **Skills** = reusable workflows, domain knowledge, step-by-step processes, templates (`.claude/skills/<name>/SKILL.md` files)
- **Subagents** = behavior, personality, responsibilities, problem-solving approach (`.claude/agents/*.md` files)
- **Commands** = workflow triggers, task starters, reusable slash-command templates (`.claude/commands/*.md` files)

A skill must NOT define who the agent is — that belongs in the subagent file. A skill defines HOW to perform a specific task or workflow.
</what-is-a-skill>

<conciseness>
The context window is a shared resource. Every token in your skill competes with conversation history, other skills, and the user's actual request.

**Default assumption**: The LLM is already very smart. Only add context it doesn't already have.

Before adding any content, ask:

- "Does the LLM really need this explanation?"
- "Can I assume it already knows this?"
- "Does this paragraph justify its token cost?"

Write the minimum necessary to guide Claude effectively. Trim explanations of concepts the LLM already understands.
</conciseness>

<xml-syntax>
Use XML-like tags for structured content that requires explicit boundaries — principles, rules, specifications, or multi-part sections where nesting adds clarity. This ensures reliable parsing across all LLM model tiers.

Use plain Markdown for sequential content like step-by-step processes, guidelines, and reference tables where structure is already clear from headings and formatting.

**When to use XML tags**: Principles, rules, specifications, structured templates, sections with explicit open/close boundaries.
**When to use Markdown**: Steps, checklists, tables, guidelines, reference lists, code examples.
</xml-syntax>

<progressive-disclosure>
Skills use a three-tier loading model:

1. **Discovery** (~100 tokens): Only `name` and `description` are loaded at startup for all skills — this is how Claude decides which skills to activate.
2. **Activation** (< 5000 tokens recommended): The full `SKILL.md` body is loaded when the skill is triggered.
3. **Resources** (as needed): Files in `scripts/`, `references/`, and `assets/` are loaded only when required during execution.

Keep SKILL.md body **under 500 lines**. Move detailed reference material, examples, and templates to separate files. Reference those files from the SKILL.md body.
</progressive-disclosure>

</principles>

## Skill Directory Structure

A skill is a directory under `.claude/skills/` containing at minimum a `SKILL.md` file:

```
.claude/skills/skill-name/
├── SKILL.md              # Required: instructions + metadata
├── scripts/              # Optional: executable code
├── references/           # Optional: additional documentation
└── assets/               # Optional: templates, static resources
```

- The directory name MUST match the `name` field in the SKILL.md frontmatter.
- Keep file references one level deep from SKILL.md — avoid deeply nested reference chains.
- Name files descriptively: `form-validation-rules.md`, not `doc2.md`.

## Skill Creation Process

Use the checklist below and track your progress:

```
Creation progress:
- [ ] Step 1: Define the skill's purpose
- [ ] Step 2: Create the skill name
- [ ] Step 3: Write the skill description
- [ ] Step 4: Write the skill body
- [ ] Step 5: Create supporting files (if needed)
- [ ] Step 6: Assemble and validate the skill
```

**Step 1: Define the skill's purpose**

Before writing anything, clarify the skill's purpose with the user. Use the **AskUserQuestion** tool to gather answers to these questions in a single batch:

1. **What task does this skill perform?** — The core activity (e.g., "analyze test coverage", "generate API documentation").
2. **What triggers activation?** — When should Claude load this skill? What user requests or contexts should match?
3. **What does it produce?** — Expected output: a document, code changes, a report, analysis, etc.
4. **What makes it distinct?** — How is this different from existing skills? (List current skills for the user to compare against.)

If the user provided enough context in the conversation to answer these questions confidently, skip the clarification and proceed. Only ask about genuinely ambiguous or missing information.

**Step 2: Create the skill name**

<naming-conventions>

### Naming Formula

Use **gerund form** (verb + -ing) followed by the object:

```
{gerund-verb}-{object}
```

This format clearly describes the activity or capability the skill provides. It reads naturally as "this skill is about [doing something]."

### Rules

| Rule | Requirement |
|---|---|
| Format | Gerund form: `{verb-ing}-{object}` |
| Characters | Lowercase letters, numbers, and hyphens only (`a-z`, `0-9`, `-`) |
| Length | 1–64 characters. Aim for **under 20 characters** |
| Start/end | Must NOT start or end with a hyphen |
| Consecutive hyphens | Must NOT contain `--` |
| Directory match | Must match the parent directory name exactly |

### Naming Examples

Good names (gerund form — preferred):

| Name | Chars |
|---|---|
| `creating-agents` | 15 |
| `reviewing-code` | 14 |
| `testing-e2e` | 11 |
| `analyzing-tasks` | 15 |
| `designing-architecture` | 24 |
| `gathering-context` | 17 |
| `finding-gaps` | 12 |

Avoid:

| Pattern | Example | Why |
|---|---|---|
| Noun phrases | `task-analysis` | Passive — doesn't convey action |
| Vague names | `helper`, `utils`, `tools` | Indiscoverable — Claude can't match them to tasks |
| Overly generic | `documents`, `data`, `files` | Too broad — will trigger on irrelevant tasks |
| Inconsistent form | Mix of `code-review` and `creating-agents` | Breaks convention — confuses pattern recognition |

### Shortening Long Names

When the gerund form gets too long (over ~20 chars), simplify the object — let the `description` field carry the specificity.

| Verbose | Shortened | Strategy |
|---|---|---|
| `analyzing-implementation-gaps` (30) | `finding-gaps` (12) | Simpler verb + shorter object |
| `discovering-technical-context` (30) | `gathering-context` (17) | Broader verb + drop qualifier |

### Confirming the Name

When multiple valid names exist, use the **AskUserQuestion** tool to let the user choose. Present 2-3 candidates with character counts. Mark the shortest gerund-form option as recommended.

</naming-conventions>

**Step 3: Write the skill description**

<description-guidelines>

### Purpose

The `description` field is the **primary discovery mechanism**. Claude reads all skill descriptions at startup to decide which skill to activate for a given task. Your description must provide enough detail for Claude to match it accurately from potentially 100+ available skills.

### Rules

| Rule | Requirement |
|---|---|
| Length | 1–1024 characters. Non-empty. |
| Point of view | Always third person. Never use "I", "you", or "we". |
| Content | Must describe both WHAT the skill does AND WHEN to use it. |
| Keywords | Include specific trigger terms that help Claude identify relevant tasks. |

### Formula

```
{What the skill does — core capabilities}. {When to use it — triggers and contexts}.
```

### Good Examples

```yaml
description: "Create custom subagents (`.claude/agents/*.md`) for Claude Code. Provides templates, guidelines, and a structured process for building subagent definitions. Use when creating, reviewing, or updating subagent files."
```

```yaml
description: "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."
```

### Bad Examples

```yaml
# Too vague — Claude can't determine when to activate:
description: "Helps with documents."

# Wrong point of view — causes discovery problems:
description: "I can help you process Excel files."

# Missing trigger context — Claude doesn't know WHEN to use it:
description: "Processes data from various sources."
```

</description-guidelines>

**Step 4: Write the skill body**

The Markdown body after the frontmatter contains the skill instructions. There are no strict format restrictions — write whatever helps Claude perform the task effectively.

### Content Guidelines

<body-guidelines>

**Line limit**: Keep the SKILL.md body **under 500 lines**. If approaching this limit, split content into referenced files using progressive disclosure patterns.

**Structure the body with these sections** (see template at `./skill.template.md`):

| Section | Required | Purpose |
|---|---|---|
| Introduction | **Yes** | 1-2 sentences describing what the skill does. |
| Principles | No | Core design principles using `<principles>` XML tags — when the skill has foundational rules that constrain all decisions. |
| Process / Workflow | **Yes** | Step-by-step checklist and detailed instructions. The core of the skill. |
| Reference tables | No | Quick-reference tables for rules, patterns, or conventions. |
| Connected Skills | **Yes** | Links to related skills with brief rationale for each. |

**Conciseness rules**:

- Only add context the LLM doesn't already have.
- Use examples instead of explanations — they convey style and expectations more efficiently.
- See [examples/reviewing-code.skill.md](examples/reviewing-code.skill.md) for a complete example demonstrating conciseness.
- Provide a default approach, not multiple options. Add alternatives only when a specific condition requires them.
- Don't explain concepts the LLM already knows (e.g., what PDFs are, how REST APIs work).

**Consistent terminology**: Choose one term for each concept and use it throughout the skill. Don't alternate between "API endpoint", "URL", "route", and "path" if they mean the same thing.

**No time-sensitive information**: Don't include dates or version-dependent guidance. If you must reference a deprecated approach, use an "Old patterns" section.

**Use workflows for complex tasks**: Break operations into clear, sequential steps. Provide a checklist Claude can copy and track progress against.

**Implement feedback loops**: For quality-critical tasks, include validation steps: run validator → fix errors → repeat.

</body-guidelines>

### Degrees of Freedom

Match specificity to the task's fragility and variability:

| Freedom Level | When to use | Example |
|---|---|---|
| **High** (text instructions) | Multiple valid approaches; decisions depend on context | Code review guidelines |
| **Medium** (pseudocode / templates) | A preferred pattern exists but variation is acceptable | Report generation with customizable sections |
| **Low** (exact scripts, no params) | Operations are fragile; consistency is critical | Database migrations, file format validation |

**Step 5: Create supporting files (if needed)**

When the SKILL.md body approaches 500 lines, or when the skill includes resources that should be loaded on demand:

<supporting-files>

| File type | Location | Purpose | Load behavior |
|---|---|---|---|
| Templates | Skill root or `assets/` | Output format templates Claude fills in | Loaded when Claude needs to produce output |
| Reference docs | `references/` | Detailed specs, API docs, domain knowledge | Loaded when Claude needs specific details |
| Scripts | `scripts/` | Executable utility scripts | Executed via the **Bash** tool (not read into context) — saves tokens |
| Examples | Skill root or `references/` | Input/output examples, sample files | Loaded when Claude needs to understand expected format |

**File reference rules**:

- Use relative paths from the skill root: `./references/REFERENCE.md`
- Keep references **one level deep** from SKILL.md — avoid nested reference chains
- Make clear whether Claude should **execute** a script ("Run `analyze.py`") or **read** it as reference ("See `analyze.py` for the algorithm")
- Include a table of contents in reference files longer than 100 lines

</supporting-files>

**Step 6: Assemble and validate the skill**

Use the `./skill.template.md` template to build the SKILL.md file.
See [examples/reviewing-code.skill.md](./examples/reviewing-code.skill.md) for a complete filled-in example.

After assembling the skill, use the **AskUserQuestion** tool to run a final review with the user. Present the proposed `name`, `description`, and a summary of the skill's workflow steps. Ask the user to confirm or request changes before finalizing.

Then validate against this checklist:

### Validation Checklist

```
Validation:
- [ ] Frontmatter: `name` is valid (gerund form, lowercase, hyphens, ≤64 chars)
- [ ] Frontmatter: `name` matches the parent directory name
- [ ] Frontmatter: `description` describes WHAT the skill does and WHEN to use it
- [ ] Frontmatter: `description` is in third person (no "I", "you", "we")
- [ ] Frontmatter: `description` includes specific trigger keywords
- [ ] Body: Under 500 lines total
- [ ] Body: Introduction is 1-2 sentences
- [ ] Body: Process/workflow has a trackable checklist
- [ ] Body: Only adds context the LLM doesn't already have
- [ ] Body: Uses consistent terminology throughout
- [ ] Body: No time-sensitive information
- [ ] Body: XML tags (if used) are properly opened and closed
- [ ] Body: Connected Skills section references existing skills
- [ ] Files: Supporting files are one level deep (no nested reference chains)
- [ ] Files: Template files (if any) use XML tags for structured sections
- [ ] Files: Reference files over 100 lines have a table of contents
- [ ] Testing: Skill tested with real usage scenarios
```

## Common Patterns

For standard workflow patterns (checklists, templates, conditional workflows, feedback loops), see [references/common-patterns.md](references/common-patterns.md).

## Anti-Patterns to Avoid

| Anti-pattern | Why it's harmful | Fix |
|---|---|---|
| Over-explaining known concepts | Wastes tokens; Claude already knows what PDFs are | Remove. Only explain project/domain-specific knowledge |
| Offering too many options | Confusing; Claude may pick wrong one | Provide a default, with escape hatch for edge cases |
| Deeply nested references | Claude may partially read files at depth > 1 | Keep all references one level deep from SKILL.md |
| Vague file names | `doc2.md`, `helpers.md` | Use descriptive names: `form-validation-rules.md` |
| Windows-style paths | Breaks on Unix systems | Always use forward slashes: `scripts/validate.py` |
| Inconsistent naming within collection | Confuses pattern recognition; breaks discoverability | Use gerund form consistently for all skill names |
| Magic numbers in scripts | Claude can't determine the right value | Document why: `TIMEOUT = 30  # HTTP requests typically complete within 30s` |

## Connected Skills

- `fabrico-creating-agents` - to understand how skills relate to subagent definitions and avoid overlap
- `fabrico-creating-prompts` - to understand how commands reference and trigger skills
- `fabrico-technical-context-discovering` - to discover existing skill patterns in the project before creating a new one
- `fabrico-codebase-analysing` - to analyze existing skills and identify conventions to follow
- `fabrico-creating-instructions` - to understand when project rules belong in CLAUDE.md memory files rather than skill content
</content>
</invoke>