Excellence Skill Creator

---
name: excellence-skill-creator
description: 'Create opinionated, anti-slop skills that encode taste. Use when the user wants a skill that makes Claude less generic in a domain, in the style of frontend-design, cli-design or system-architecture. NOT for: general skill structure, reference guides, procedural docs (use skill-creator instead).'
---

Design-excellence skills transform Claude from a generic pattern-matcher into an opinionated craftsperson. A skill without strong opinions is just documentation with delusions of grandeur.

The user provides a domain (e.g., "API design", "error messages", "database schemas") and context about what makes generic output unacceptable. If they can't articulate why generic output fails, help them find that angle first—it's the foundation of everything that follows.

<excellence_philosophy>
## Philosophy: What Makes a Design-Excellence Skill

A design-excellence skill without these five traits is just documentation pretending to have opinions:

1. **Force intentional choices**: Make Claude commit to a direction before touching the keyboard. Intentional choices produce distinctive output; default choices produce forgettable output.

2. **Encode taste, not just rules**: Rules tell you what's legal. Taste tells you what's *good*. Your skill transmits the judgment of someone who has failed enough times to know what actually matters.

3. **Name the anti-patterns**: Claude knows thousands of patterns. Tell it which ones are tired, overused, or inappropriate for this context. The anti-patterns block is often the most valuable section—it's where your hard-won experience becomes actionable guidance.

4. **Define done**: Success criteria prevent the "good enough" trap. If you can't measure it, Claude will satisfice. Measurable outcomes distinguish excellent from adequate.

5. **Match complexity to context**: A TODO app doesn't need microservices. A landing page doesn't need a design system. A skill that over-engineers simple cases teaches Claude to over-engineer everything.

If your skill reads like it could have been written by anyone, it will produce output that could have been written by anyone. Encode your opinions explicitly.
</excellence_philosophy>

<excellence_workflow>
## Workflow: Scaffold → Craft → Audit

This skill orchestrates a 3-pass workflow for maximum skill quality.

### Step 0: Choose Workflow

Run the full workflow for a new skill. When SKILL.md already exists, start at Craft. Skip Audit only when the user asks for a quick iteration.

### Pass 1: Scaffold

**When to run**: New skill from scratch. Skip if SKILL.md exists.

Invoke skill-creator init with the domain name. If unavailable, create manually:

```yaml
---
name: [domain]-design
description: [What it creates]. Use when [the user intents it serves, named as categories]. NOT for: [exclusions].
---
```

The description format matters: state what it does, the user intents that should load it, and what it's NOT for (disambiguation).

### Pass 2: Craft

**When to run**: Always.

Start from the domain's anti-slop angle, then fill the seven sections of `<excellence_structure>`: an opening context saying what the user provides and what the skill produces, design thinking questions that force real decisions, guidelines carried by good/bad example pairs, the specific anti-patterns Claude tends toward in this domain, measurable success criteria, what simple cases need versus complex ones, and a one-sentence closing principle.

This is the core pass. It transforms structure into opinionated content.

### Pass 3: Audit

**When to run**: Recommended. Skip only for quick iterations.

Run `/claude-api prompt-audit <path to SKILL.md>` on the completed SKILL.md. It reports dated prompting patterns with a proposed diff.

If the claude-api skill isn't available, manually verify:
- Triggers are specific (not just "create a skill")
- Examples show concrete good/bad contrast
- Each guideline explains "why" not just "what"
- Anti-patterns name specific behaviors, not vague categories

### Workflow Complete

After all passes, present:
- Summary of what was created
- Path to the skill file
- Suggestion to test by invoking the skill
</excellence_workflow>

<excellence_structure>
## Skill Structure Template

Every design-excellence skill contains seven sections:

**Frontmatter format**: `description: [What]. Use when [user intents, as categories]. NOT for: [exclusions].`

1. **Opening Context** - What user provides, what skill produces
2. **Design Thinking** - Questions that force intentionality before implementation
3. **Domain Guidelines** - "What to do" with good/bad example pairs
4. **Anti-Patterns Block** - Explicit patterns to avoid with alternatives
5. **Success Criteria** - Measurable outcomes defining "done right"
6. **Complexity Matching** - Guidance on scaling appropriately
7. **Closing Principle** - One memorable sentence capturing the skill's spirit

For detailed templates with markdown examples, see:
`references/structure-template.md`
</excellence_structure>

<excellence_examples>
## Example Domains and Anti-Slop Angles

When creating a design-excellence skill, identify:
- **The domain**: What is being designed?
- **The anti-slop angle**: What does generic AI output look like? What makes practitioners cringe?

The table below shows the contrast for common domains:

<example_good title="Strong anti-slop contrast">
| Domain | Generic | Excellence |
|--------|---------|------------|
| Error messages | "An error occurred" | Context + cause + recovery path |
| API design | Every HTTP verb for CRUD | Consistent resources, clear error contracts |
</example_good>

<example_bad title="Weak anti-slop contrast">
| Domain | Generic | Excellence |
|--------|---------|------------|
| Code | Bad code | Good code |
| Design | Ugly design | Pretty design |
</example_bad>

**Full domain reference**:

| Domain | Generic AI Output | Design Excellence |
|--------|-------------------|-------------------|
| API design | RESTful CRUD with every HTTP verb | Consistent resource modeling, clear error contracts, thoughtful pagination |
| Error messages | "An error occurred" | Context, cause, recovery path, actionable guidance |
| Config files | Every option exposed as a flag | Sensible defaults, progressive disclosure, environment-specific overrides |
| Test suites | 100% coverage with mocks everywhere | Behavior testing, realistic fixtures, minimal mocking |
| Logging | Printf debugging and wall-of-text | Structured logs, correlation IDs, appropriate levels, actionable alerts |
| Database schemas | Fully normalized, no indexes | Query-driven design, appropriate denormalization, considered access patterns |
| Documentation | Auto-generated from code | Task-oriented, examples-first, explains the "why" |
| Commit messages | "Fixed bug" / "Updated files" | Context, motivation, what changed and why |
</excellence_examples>

<excellence_worked_example>
## Worked Example: Error Messages Skill

A condensed example showing the pattern in action:

```markdown
---
name: error-messages
description: Create helpful, actionable error messages that guide users to recovery. Use when building error handling, validation feedback, or failure responses.
---

This skill guides creation of error messages that help users recover, not just inform them something broke.

<error_design_thinking>
## Design Thinking

Before writing error messages:
- **Audience**: Developer debugging? End user recovering? Both?
- **Context**: CLI stderr? API JSON? UI toast?
- **Recovery**: What can the user actually do about it?
- **Severity**: Fatal? Retryable? Warning?

Error messages are micro-documentation. Treat them with the same care.
</error_design_thinking>

<error_guidelines>
## Guidelines

### Always Include a Recovery Path

<example_good title="Actionable error">
Error: Cannot connect to database at localhost:5432

Possible causes:
- PostgreSQL is not running
- Wrong port (check DATABASE_URL)
- Firewall blocking connection

Try: pg_isready -h localhost -p 5432
Docs: https://docs.app.com/troubleshooting/db
</example_good>

<example_bad title="Dead-end error">
Error: Connection failed
</example_bad>

### Name the Specific Problem

<example_good title="Specific error">
Error: File 'config.yaml' not found in /app/config/

Expected location: /app/config/config.yaml
Current directory: /app/src/

Did you mean: /app/config/config.yml (found)
</example_good>

<example_bad title="Vague error">
Error: Invalid configuration
</example_bad>
</error_guidelines>

<error_anti_patterns>
## Patterns to Avoid

- "An error occurred" → Name the specific error and its cause
- Stack traces to end users → Log internally, show human message
- Error codes only → Include human-readable message first
- "Please try again" without context → Explain what to try differently
- "Contact support" as first option → Offer self-service recovery first
</error_anti_patterns>

<error_success_criteria>
## Success Criteria

1. **Self-diagnosable**: User can identify the cause without external help
2. **Actionable**: At least one concrete recovery step provided
3. **Contextual**: Error includes relevant state (paths, values, IDs)
4. **Appropriate**: Tone matches audience (dev vs end-user)
</error_success_criteria>

<error_complexity>
## Match Complexity to Scope

CLI script stderr: One-line message with cause. No docs links, no structured data.

User-facing API: Structured JSON with error code, human message, and documentation URL.

Internal service: Structured logs with correlation IDs, stack traces, request context.

Don't add recovery suggestions to internal errors that users never see. Don't strip context from user-facing errors to "keep it simple."
</error_complexity>
```

This example demonstrates all seven sections: frontmatter with a "Use when" clause, design thinking, guidelines with example pairs, anti-patterns, success criteria, and complexity matching.
</excellence_worked_example>

<excellence_writing_tips>
## Writing Tips

**Length**: Long enough to encode taste, short enough to stay in context. Every section earns its place by changing the output compared with no skill; no section is padded to reach a size.

**Semantic tags**: Use XML-style tags (`<domain_guidelines>`) for each major section. Helps Claude's attention and makes sections navigable.

**Examples over explanation**: A good/bad example pair teaches more than a paragraph of prose. Show, don't tell.

**Specificity**: "Avoid overengineering" is useless. "Don't add a plugin system to a grep replacement" is actionable.

**Voice**: Write as the senior practitioner mentoring a capable junior. Confident, opinionated, helpful. No hedging.

**What to write instead**:

| Instead of | Write |
|------------|-------|
| Meta-commentary ("This skill helps you...") | Jump straight into domain guidance—Claude knows it's reading a skill |
| Hedging ("Consider maybe...") | Direct imperatives ("Use X", "Apply Y")—skills encode confident opinions |
| Generic advice ("Write clean code") | Domain-specific guidance ("Extract functions over 20 lines") |
| Placeholder text ("Insert example here") | Actual examples—Claude may use placeholders literally |

Write like a senior practitioner giving direct advice, not a textbook hedging its bets.

**Test your anti-patterns**: If you can't name 5+ specific anti-patterns Claude tends toward in this domain, you don't know the domain well enough yet.
</excellence_writing_tips>

<excellence_validation>
## Validating Your Skill

Test with at least 3 diverse prompts in the target domain:

1. **Invoke the skill** on a real task
2. **Compare output** against what Claude produces without the skill
3. **Check anti-patterns** - are they actually being avoided?
4. **Verify measurability** - can you objectively assess each success criterion?

If outputs are indistinguishable with/without the skill, your anti-patterns aren't specific enough.
</excellence_validation>

<excellence_iteration>
## When the Skill Isn't Working

Symptoms and fixes:

| Symptom | Diagnosis | Fix |
|---------|-----------|-----|
| Output looks the same with/without skill | Anti-patterns too vague | Name specific behaviors, not categories. "Avoid bad error messages" → "Avoid 'An error occurred' without context, cause, or recovery path" |
| Claude ignores sections | Triggers not matching | Name the missed user intent, as a category, in the description's "Use when" clause; check if skill is actually loading |
| Claude over-applies guidance | Complexity matching missing | Add explicit "don't do X for simple cases" guidance |
| Output feels mechanical | Design thinking questions too generic | Questions should force real decisions, not checkboxes |
| Anti-patterns aren't avoided | Too many anti-patterns | Prioritize 5-7 specific ones over 15 vague ones |

If you've iterated 3+ times without improvement, the domain may not benefit from an opinionated skill. Some domains genuinely have multiple valid approaches—consider a reference-style skill instead.
</excellence_iteration>

<excellence_closing>
## Closing Principle

The test is simple: if removing your skill produces identical output, you wrote documentation. If it produces noticeably worse output, you wrote a skill.

Skills encode judgment. References encode facts. Know the difference, and write accordingly.
</excellence_closing>