---
name: catalyst-skill-creator
description: >
  Creates new AI agent skills following the Agent Skills spec. Trigger: When user asks to create a
  new skill, add agent instructions, or document patterns for AI.
license: MIT
metadata:
  author: aurora
  version: '1.1'
  auto_invoke: 'Creating new skills, documenting patterns, adding AI instructions'
allowed-tools: Read, Edit, Write, Glob, Grep, Bash, WebFetch, WebSearch, Task
---

## Skill Location (MANDATORY — Resolve BEFORE Anything Else)

Every skill belongs to exactly ONE scope. **You MUST determine the scope before creating or
modifying a skill.** If the user does not specify, **STOP and ask**. Do NOT assume or continue
without a clear answer.

| Scope               | Base path                  | When to use                                                                                                             |
| ------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| **Monorepo (root)** | `.claude/skills/`          | Cross-cutting concerns shared by both backend and frontend (formatting, commits, project structure, schema definitions) |
| **Backend**         | `backend/.claude/skills/`  | Patterns exclusive to the NestJS backend (API design, Sequelize, GraphQL resolvers, services, guards)                   |
| **Frontend**        | `frontend/.claude/skills/` | Patterns exclusive to the Angular frontend (components, Material, Fuse template, state management)                      |

### Decision Flow

```
Does the skill apply to BOTH backend and frontend?
  YES → Monorepo root (.claude/skills/)
  NO  → Is it backend-only (NestJS, Sequelize, REST/GraphQL API)?
          YES → backend/.claude/skills/
          NO  → frontend/.claude/skills/
```

### CRITICAL

- If the user says "create a skill" without specifying scope → **ASK**: "Where should this skill be
  located? Options: monorepo (root), backend, or frontend?"
- Never guess the scope. The user must confirm explicitly or the scope must be unambiguous from
  context (e.g., "skill for Angular components" → frontend).
- Once determined, use the full base path consistently throughout creation and registration.

---

## When to Create a Skill

Create a skill when:

- A pattern is used repeatedly and AI needs guidance
- Project-specific conventions differ from generic best practices
- Complex workflows need step-by-step instructions
- Decision trees help AI choose the right approach

**Don't create a skill when:**

- Documentation already exists (create a reference instead)
- Pattern is trivial or self-explanatory
- It's a one-off task

---

## Skill Structure

```
{base-path}/skills/{skill-name}/
├── SKILL.md              # Required - main skill file
├── scripts/              # Optional - executable code for deterministic/repetitive tasks
├── references/           # Optional - docs loaded into context as needed
└── assets/               # Optional - files used in output (templates, schemas, icons)
```

Where `{base-path}` is `.claude`, `backend/.claude`, or `frontend/.claude` depending on the resolved
scope.

### Progressive Disclosure (core principle)

Skills load in three levels:

1. **Metadata** (`name` + `description`) — ALWAYS in context (~100 words). This is what determines
   whether Claude invokes the skill.
2. **SKILL.md body** — loaded when the skill triggers. **Keep it under 500 lines**.
3. **Bundled resources** (`scripts/`, `references/`, `assets/`) — loaded only when the SKILL.md body
   explicitly references them.

If your SKILL.md approaches 500 lines, **move depth into `references/`** with clear pointers from
SKILL.md (e.g., "for case X, read `references/X.md`"). The body should hold the essential rules;
depth loads on demand.

For skills with variants, organize by variant in `references/`:

```
cloud-deploy/
├── SKILL.md             # General workflow + variant selector
└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md
```

Claude reads only the relevant reference — not all three.

---

## SKILL.md Template

````markdown
---
name: { skill-name }
description: >
  {One-line description of what this skill does}. Trigger: {When the AI should load this skill}.
license: MIT
metadata:
  author: aurora
  version: '1.0'
---

## When to Use

{Bullet points of when to use this skill}

## Critical Patterns

{The most important rules - what AI MUST know}

## Code Examples

{Minimal, focused examples}

## Commands

```bash
{Common commands}
```
````

## Resources

- **Templates**: See [assets/](assets/) for {description}
- **Documentation**: See [references/](references/) for local docs

```

---

## Writing the description (trigger optimization)

The `description` field in the frontmatter is the primary mechanism that decides whether Claude
invokes the skill. Invest disproportionate care here — a skill with a perfect body but an ambiguous
description will NEVER be invoked.

### "Pushy" pattern

Claude tends to **undertrigger** — it fails to invoke skills when it should. To counter this,
descriptions must be assertive and mention **explicit contexts** where the skill applies, even if
the user doesn't ask for them literally.

**Weak** (undertriggers):

> "How to build a simple dashboard."

**Strong** (pushy):

> "How to build a simple dashboard. Make sure to use this skill whenever the user mentions
> dashboards, data visualization, internal metrics, or wants to display any kind of company data,
> EVEN IF they don't explicitly ask for a 'dashboard'."

### Recommended structure

```
{What the skill does, one line}. Trigger: {specific contexts, files, verbs, domain terms}.
{Optional: cases where it should NOT trigger, to disambiguate from competing skills}.
```

### Resolving ambiguity between competing skills

If two skills can fire in the same context (e.g., consuming vs authoring components), each
description must explicitly state **when it does NOT apply**. Without that, Claude picks at random.

---

## Naming Conventions

| Type | Pattern | Examples |
|------|---------|----------|
| Generic skill | `{technology}` | `typescript`, `prettier`, `playwright` |
| Aurora-specific | `catalyst-{component}` | `catalyst-schema`, `catalyst-component-catalog`, `catalyst-data-table-management` |
| Testing skill | `aurora-test-{component}` | `aurora-test-api`, `aurora-test-e2e` |
| Workflow skill | `{action}-{target}` | `catalyst-skill-creator`, `commit-pr` |

---

## Decision: assets/ vs references/

```

Need code templates? → assets/ Need JSON schemas? → assets/ Need example configs? → assets/ Link to
existing docs? → references/ Link to external guides? → references/ (with local path)

```

**Key Rule**: `references/` should point to LOCAL files (`docs/developer-guide/*.mdx`), not web URLs.

---

## Decision: Aurora-Specific vs Generic

```

Patterns apply to ANY project? → Generic skill (e.g., typescript, prettier) Patterns are
Aurora-specific? → aurora-{name} skill Generic skill needs Aurora info? → Add references/ pointing
to Aurora docs

```

---

## Frontmatter Fields

| Field | Required | Description |
|-------|----------|-------------|
| `name` | Yes | Skill identifier (lowercase, hyphens) |
| `description` | Yes | What + Trigger in one block |
| `license` | Yes | `MIT` |
| `metadata.author` | Yes | `aurora` |
| `metadata.version` | Yes | Semantic version as string |

---

## Writing Style Principles

### Explain the WHY, not just the WHAT

Modern LLMs are intelligent — with good context, they reason through edge cases. Rather than
imposing rigid rules, explain the **reasoning**.

**Weak**:

> "ALWAYS use TypeScript strict mode. NEVER use `any`."

**Strong**:

> "We use strict mode because the codegen produces precise types, and `any` propagates errors to
> the client. If you find an `any` in legacy code, preserve the behavior but leave a TODO to type
> it progressively."

### Avoid all-caps MUSTs as your first tool

If you catch yourself writing `ALWAYS`, `NEVER`, or `MUST` in caps, that's a **yellow flag**.
Reframing as explanation + reasoning is more humane and more effective. Reserve absolute MUSTs for
rules that literally admit no exception (e.g., "NEVER commit secrets").

### Imperative form + theory of mind

Use the imperative ("read X before writing") instead of the descriptive ("X should be read"). Write
as if addressing an intelligent model that wants to help, not a machine that must be forced.

### Reread with fresh eyes

After drafting, step away and reread. Look for redundancies, rules that don't pull their weight,
examples that aren't needed. A lean skill beats an exhaustive one.

---

## Content Guidelines

### DO
- Start with the most critical patterns
- Use tables for decision trees
- Keep code examples minimal and focused
- Include Commands section with copy-paste commands

### DON'T
- Add Keywords section (agent searches frontmatter, not body)
- Duplicate content from existing docs (reference instead)
- Include lengthy explanations (link to docs)
- Add troubleshooting sections (keep focused)
- Use web URLs in references (use local paths)

---

## Registering the Skill

After creating the skill, register it in the CLAUDE.md of the corresponding scope:

| Scope | Register in |
|-------|-------------|
| Monorepo | Root `CLAUDE.md` — Skills table and Skills Index |
| Backend | `backend/CLAUDE.md` — Skills table |
| Frontend | `frontend/CLAUDE.md` — Skills table |

---

## Checklist Before Creating

- [ ] **Scope resolved** (monorepo / backend / frontend) — MANDATORY first step
- [ ] Skill doesn't already exist (check `{base-path}/skills/`)
- [ ] Pattern is reusable (not one-off)
- [ ] Name follows conventions
- [ ] Frontmatter is complete (description includes trigger keywords)
- [ ] Critical patterns are clear
- [ ] Code examples are minimal
- [ ] Commands section exists
- [ ] Registered in the corresponding CLAUDE.md

## Resources

- **Templates**: See [assets/](assets/) for SKILL.md template
```
