<!--
Skill Creator
Part of the Bles Software agent skills repository:
https://www.bles-software.com/claude-skills

Install for Claude Code:
  mkdir -p ~/.claude/skills/skill-creator
  mv skill-creator.md ~/.claude/skills/skill-creator/SKILL.md

Install for Codex:
  mkdir -p ~/.codex/skills/skill-creator
  mv skill-creator.md ~/.codex/skills/skill-creator/SKILL.md

For Gemini CLI and other agents, drop the body of this file into the
project instruction file the agent already reads.

Note: in production this skill also ships 2 helper file(s) alongside
SKILL.md. The procedure below is complete and self-contained; the helpers are
convenience scripts you can rebuild from the steps described here.
-->

---
name: skill-creator
description: |
  Creates powerful, well-structured Claude Code skills following Anthropic's official best practices.
  Use when the user wants to create a new skill, build a skill, make a custom capability,
  or asks about skill structure, SKILL.md format, or skill development.
allowed-tools: Read, Write, Bash, Glob, Grep
---

# Skill Creator - Build Powerful Claude Code Skills

Create production-quality skills following Anthropic's official best practices and patterns.

## Quick Start

When user wants to create a skill:

0. **Gate 0 + DRY check** - Should this exist, and does it already? See below.
1. **Gather requirements** - What task? What triggers it? What tools needed?
2. **Choose skill type** - See [Skill Types](#skill-types) below
3. **Generate structure** - Use templates from `templates/`
4. **Apply best practices** - Follow [Core Principles](#core-principles)
5. **Write the eval contract** - goal + dimensions + hard-fails in frontmatter
6. **Second-opinion pass** - another brain scores the output against the contract
7. **Hygiene gate** - one copy on disk, `python3 ~/teleclaudious/scripts/skill_hygiene.py` clean

---

## Gate 0: Should this be a skill at all?

A wrong skill is worse than no skill: the agent follows it confidently.
All three must be true, or it is a script or a one-off, not a skill:

- It will be invoked **2+ times**. One-off work is not a skill.
- It carries **more than ~20 lines of real logic or judgment**. Trivial helpers
  don't need routing.
- There is a **trigger phrase a user would actually say**. If you can't write
  one, nothing will ever route to it.

One skill = one capability = one coherent trigger family. "Run the build" /
"roll back the deploy" / "notify the team" is three skills, not one.

## DRY/MECE pre-check (before you write a line)

```bash
grep -ril "<the trigger phrase>" ~/.claude/skills/*/SKILL.md | head
python3 ~/teleclaudious/scripts/skill_hygiene.py | grep overlap
```

If an existing skill already owns that trigger, **extend it** (add a mode, a
phase, a trigger, bump the version) instead of creating a near-duplicate. Two
skills fighting for the same trigger is how the wrong one wins at 2am. If you
create a separate skill anyway, put the one-sentence distinction in its
description.

## The eval contract (frontmatter)

Every non-trivial skill states what "excellent" means, so any later edit can
be judged against the same bar instead of vibes:

```yaml
eval_contract:
  goal: |
    One or two sentences: what this skill achieves, for whom, and what
    excellent looks like in the real world. Concrete, skill-specific.
  dimensions:
    - "DIMENSION — the specific question this dimension answers for THIS skill"
  hard_fails:
    - "A failure mode that zeroes the result no matter what else is good."
```

Generic dimensions catch slop but miss whether the skill did its actual job.
3-6 dimensions, tuned to the skill.

## Second-opinion pass (our version of a cross-model eval)

We have three brains on this box. Use them instead of trusting one:

1. Run the skill once on its hardest documented input, keep the output.
2. Hand the output plus the eval contract to a different engine
   (`codex exec`) and ask it to score each dimension 1-10
   and name the top three fixes.
3. Fix what it flags, re-run, stop when every dimension is >= 7 and nothing
   scores below 5. Three cycles maximum, then ship with a KNOWN GAPS section.

Skip for skills whose output is under ~200 tokens or that wrap one API call.

## Improve mode (running on a skill that already exists)

This is the common case, and it is **not** a rewrite. Read the existing
SKILL.md, its scripts and its tests first, then change only the delta:

- **Bug:** add the constraint that prevents recurrence, plus a Bug log entry.
- **New input:** extend the affected section, leave the rest alone.
- **Quality pass:** re-run the checklist and touch only what fails.

```markdown
## Bug: [date] - [one line]
- What happened / Root cause / Fix / Hard rule added
```

**No-regression law:** an edit ships only if the skill still does its job at
least as well as before on the same representative input. If the new version
is worse on any dimension, revert or re-fix. We only go forward.

## One copy on disk

A skill lives in exactly one real directory; every other root points at it
with a symlink. Two divergent copies means Claude and Codex silently
follow different instructions for the same skill.

```bash
mv ~/.claude/skills/<name> ~/teleclaudious/skills/<name>
for r in ~/.claude/skills ~/.codex/skills; do
  ln -sfn ~/teleclaudious/skills/<name> $r/<name>
done
python3 ~/teleclaudious/scripts/skill_hygiene.py   # must exit 0
```

---

## Skill Types

| Type | When to Use | Complexity |
|------|-------------|------------|
| **Simple** | Single-purpose, no scripts | Low |
| **Reference** | Multiple domains, progressive disclosure | Medium |
| **Executable** | Includes Python/Bash scripts | Medium-High |
| **Workflow** | Multi-step processes with validation | High |

---

## Core Principles (Anthropic Official)

### 1. Concise is Key

Context window is shared. Challenge every token:
- "Does Claude really need this explanation?"
- "Can I assume Claude knows this?"
- Keep SKILL.md body **under 500 lines**

### 2. Progressive Disclosure

Load information only when needed:
```
SKILL.md          → Overview + navigation (always loaded)
references/*.md   → Detailed docs (loaded on demand)
scripts/*.py      → Utilities (executed, not loaded)
```

### 3. Description is Critical

Claude uses `description` to decide when to trigger. Be specific:

```yaml
# BAD - Too vague
description: Helps with documents

# GOOD - Specific with triggers
description: |
  Extract text and tables from PDF files, fill forms, merge documents.
  Use when working with PDF files or when user mentions PDFs, forms,
  or document extraction.
```

### 4. Naming Convention

Use **gerund form** (verb + ing):
- `processing-pdfs` ✓
- `analyzing-data` ✓
- `pdf-helper` ✗
- `utils` ✗

---

## SKILL.md Structure

```yaml
---
name: skill-name-here
description: |
  What this skill does in detail.
  Use when [specific triggers and contexts].
allowed-tools: Read, Write, Bash, Glob, Grep
---

# Skill Title

Brief overview (1-2 sentences).

## Quick Start

Immediate actionable guidance.

## When to Use

Decision tree or table for when to apply this skill.

## Commands/Actions

Concrete examples with code blocks.

## References

Links to bundled reference files (progressive disclosure).

## Troubleshooting

Common issues and solutions.
```

---

## Frontmatter Fields

| Field | Required | Description |
|-------|----------|-------------|
| `name` | Yes | Max 64 chars, lowercase, hyphens only |
| `description` | Yes | Max 1024 chars, third person, specific |
| `allowed-tools` | No | Restrict tools: `Read, Write, Bash` |
| `model` | No | Override model: `opus`, `sonnet`, `haiku` |
| `version` | No | Semantic version: `1.0.0` |

---

## Templates

### Simple Skill Template

See `templates/simple.md`

### Reference Skill Template (Progressive Disclosure)

See `templates/reference.md`

### Executable Skill Template (With Scripts)

See `templates/executable.md`

### Workflow Skill Template (Multi-Step)

See `templates/workflow.md`

---

## Directory Structure Patterns

### Simple Skill
```
my-skill/
└── SKILL.md
```

### Reference Skill
```
my-skill/
├── SKILL.md
└── references/
    ├── domain-a.md
    ├── domain-b.md
    └── examples.md
```

### Executable Skill
```
my-skill/
├── SKILL.md
├── scripts/
│   ├── main.py
│   ├── validate.py
│   └── utils.py
└── references/
    └── api.md
```

### Workflow Skill
```
my-skill/
├── SKILL.md
├── scripts/
│   ├── step1_analyze.py
│   ├── step2_process.py
│   ├── step3_validate.py
│   └── step4_output.py
├── references/
│   ├── workflow.md
│   └── troubleshooting.md
└── templates/
    └── output_template.md
```

---

## Best Practices Checklist

### Gates (fail = do not ship)
- [ ] Gate 0 passed: 2+ invocations, real logic, a trigger someone says
- [ ] DRY/MECE check: no existing skill already owns this trigger
- [ ] `eval_contract` in frontmatter (goal, dimensions, hard-fails)
- [ ] Second-opinion pass by another engine, every dimension >= 7
- [ ] Improve mode: edited surgically, no regression vs the previous version
- [ ] One real directory, other roots symlinked, `skill_hygiene.py` exits 0

### Core Quality
- [ ] Description specific with trigger words
- [ ] SKILL.md under 500 lines
- [ ] Progressive disclosure for detailed content
- [ ] No time-sensitive information
- [ ] Consistent terminology
- [ ] Concrete examples (not abstract)
- [ ] File references one level deep

### For Skills with Scripts
- [ ] Scripts handle errors (don't punt to Claude)
- [ ] No magic numbers (all values documented)
- [ ] Required packages listed
- [ ] Clear execution vs read intent
- [ ] Validation/feedback loops included

### Testing
- [ ] Tested with real scenarios
- [ ] Works across models (Haiku, Sonnet, Opus)

---

## Anti-Patterns to Avoid

| Anti-Pattern | Problem | Solution |
|--------------|---------|----------|
| Verbose explanations | Wastes context | Assume Claude is smart |
| Multiple options | Confusing | Provide clear defaults |
| Windows paths `\` | Breaks on Unix | Always use `/` |
| Nested references | Partial reads | Keep one level deep |
| Magic constants | Unclear values | Document all numbers |
| Punting errors | Unreliable | Handle in scripts |

---

## Creating a Skill - Step by Step

### Step 1: Define the Skill

```
Skill Name: [gerund-form-name]
Purpose: [one sentence]
Triggers: [when should Claude use this?]
Tools Needed: [Read, Write, Bash, etc.]
Complexity: [Simple/Reference/Executable/Workflow]
```

### Step 2: Create Directory

```bash
mkdir -p ~/.claude/skills/[skill-name]/{references,scripts,templates}
```

### Step 3: Write SKILL.md

Start with template from `templates/` matching your complexity level.

### Step 4: Add References (if needed)

Create separate `.md` files for:
- Domain-specific documentation
- API references
- Extended examples
- Troubleshooting guides

### Step 5: Add Scripts (if needed)

Create Python/Bash scripts that:
- Handle errors explicitly
- Return clear output
- Document all parameters

### Step 6: Test

1. Ask Claude to use the skill
2. Verify it triggers correctly
3. Test edge cases
4. Check across models

---

## Skill Location

| Location | Scope | Use Case |
|----------|-------|----------|
| `~/.claude/skills/` | User (all projects) | Personal skills |
| `.claude/skills/` | Project (git-tracked) | Team skills |
| Plugin marketplace | Shared | Published skills |

---

## Examples of Well-Structured Skills

### Example 1: Simple API Integration

```yaml
---
name: sending-slack-messages
description: |
  Sends messages to Slack channels and users via webhook or API.
  Use when user wants to send Slack notifications, post to channels,
  or integrate with Slack.
allowed-tools: Bash, Read
---

# Sending Slack Messages

## Quick Start

```bash
curl -X POST -H 'Content-type: application/json' \
  --data '{"text":"Hello!"}' \
  $SLACK_WEBHOOK_URL
```

## Configuration

Set webhook URL in environment:
```bash
export SLACK_WEBHOOK_URL="https://hooks.slack.com/..."
```
```

### Example 2: Progressive Disclosure Pattern

```yaml
---
name: analyzing-bigquery-data
description: |
  Queries and analyzes data from BigQuery tables.
  Use when user mentions BigQuery, data analysis, SQL queries,
  or asks about company metrics.
allowed-tools: Read, Bash
---

# BigQuery Analysis

## Available Datasets

- **Finance**: Revenue, billing → See [references/finance.md](references/finance.md)
- **Sales**: Pipeline, deals → See [references/sales.md](references/sales.md)
- **Product**: Usage metrics → See [references/product.md](references/product.md)

## Quick Query

```sql
SELECT * FROM `project.dataset.table` LIMIT 10
```

Read the appropriate reference file for schema and common queries.
```

---

## Reference Files

For detailed information on specific topics:

- **Progressive Disclosure Patterns**: See [references/progressive-disclosure.md](references/progressive-disclosure.md)
- **Script Best Practices**: See [references/scripts.md](references/scripts.md)
- **Testing Skills**: See [references/testing.md](references/testing.md)