gamut-create-skill

name	gamut-create-skill
description	Blueprint — use this skill when authoring a new Gamut agent skill from scratch, from component source research through Storybook integration. Not for general Gamut development (see individual component skills).

Gamut Create Skill

Blueprint playbook for authoring a new Gamut agent skill.

Reference skills: gamut-buttons — reference for a tight component skill. gamut-datatable — reference for an organism skill with full API surface. gamut-review — reference for an audit/workflow skill.

Storybook: Meta / AI Tooling / Gamut plugin / Best practices

Claude Code skill authoring reference: Claude Code skills documentation

Skill quality review: use /writing-great-skills in Claude Code to audit a draft against information hierarchy, leading words, no-ops, and pruning before committing.

---

Phase 1 — Research before writing

Do not write until you have read all of the following.

Component source

Read the component's TypeScript source and type definitions:

packages/gamut/src/{ComponentName}/

Extract: exported symbols, prop interfaces, default values, generic constraints, any hooks exported alongside the component.

Storybook MDX

Read the component's MDX documentation page:

packages/styleguide/src/lib/{Category}/{ComponentName}/{ComponentName}.mdx

Extract: design principles, "When to use" / "Do not use" guidance, usage notes. These belong in the skill verbatim or paraphrased — they encode the designer's intent.

Related skills

Identify 2–3 existing skills that overlap. Check for:

• Components this one wraps or is used alongside
• Skills that already cover adjacent concepts (e.g. gamut-accessibility for ARIA, gamut-color-mode for theming)

Existing callout

Check whether the component's Storybook MDX already has a <Callout> for the skill. If so, you only need to update the text, not add a new import.

---

Skill directory structure

There are two locations, depending on the intended audience:

Exported skills — shipped to app repos via gamut plugin install:

packages/gamut/agent-tools/skills/
  {skill-name}/
    SKILL.md

Contributor-only skills — available in this repo only, never exported:

.claude/skills/
  {skill-name}/
    SKILL.md

Commit these directly. Claude Code reads .claude/skills/ natively, and Cursor discovers the same files via its Claude-compatibility path — no sync step or separate Cursor copy is needed.

Rules (apply to both locations):

• Directory name is kebab-case and must exactly match the name: frontmatter field
• No other files in the directory

---

Frontmatter spec

---
name: gamut-{kebab-case-name}
description: Use this skill when {trigger 1}, {trigger 2}[, {trigger 3}] — {scope and features}[; not for {anti-pattern} (see {gamut-other-skill})].
---

description rules:

• Must start with "Use this skill when"
• List 2–6 concrete trigger scenarios (comma-separated)
• Follow with — then scope/features the skill teaches
• Add anti-patterns where the boundary with another skill is non-obvious
• Target: 1–2 sentences, ≤200 characters per sentence
• Use inline backticks for component/function names
• Do not wrap the value in quotes — bare YAML string, matching all other skills

---

Section template

Use this ordered structure. Omit sections that don't apply; do not reorder.

# {Title-Cased Skill Name}

{1–2 sentence purpose and scope. No "this skill covers…" framing.}

Source: `@codecademy/gamut` — [ComponentName.tsx]({github-url})

See also: [`gamut-x`](../gamut-x/SKILL.md) — {why}. [`gamut-y`](../gamut-y/SKILL.md) — {why}.

Storybook: [{Path / ComponentName}]({gamut.codecademy.com url})

## Components

\`\`\`tsx
import { ComponentName } from '@codecademy/gamut';
\`\`\`

| Symbol          | Role           |
| --------------- | -------------- |
| `ComponentName` | {what it does} |

## When to use {ComponentName}

- {Positive case 1}
- {Positive case 2}

**Do not use {ComponentName} when:**

- {Anti-pattern 1} → use [{alternative}]({link})
- {Anti-pattern 2}

## Design principles

{Lifted from Storybook MDX. 3–5 bullets. Imperative, design-voice.}

## Props

| Prop       | Type   | Default   | Notes  |
| ---------- | ------ | --------- | ------ |
| `propName` | `type` | `default` | {note} |

> **{Non-obvious gotcha title}**: {explanation of surprising behavior, constraint, or invariant}.
> Only add this block when the behavior would genuinely surprise a reader.

## Basic usage

\`\`\`tsx
// {describe what this shows}
<ComponentName prop="value" />
\`\`\`

## {Pattern name} (repeat per pattern)

\`\`\`tsx
// correct
<ComponentName ... />

// wrong — {reason}
<ComponentName ... />
\`\`\`

## Accessibility

{Only if the component has ARIA or focus concerns beyond the universal rules.}

Do not repeat content from [`accessibility.mdc`](../../rules/accessibility.mdc) — link to it instead.

---

Token and context guidance

The description field is loaded on every skill invocation — token waste here is paid on every use.

Principle	Rule
Reference, don't repeat	Point to accessibility.mdc, related skills, or Storybook rather than copying content
Tables > prose	Use tables for prop references, option lists, and decision trees
Front-load	Lead each section with the most common case; edge cases last
Flat structure	Max one level of H3 subsections under each H2
Line target	100–180 lines for a component skill; 200–400 for a workflow skill
Gotcha blocks	Only for things that would genuinely surprise a reader (layout behavior, type constraints, focus side-effects)
Code examples	Language marker required (tsx, ts, jsx); show both correct and incorrect when the wrong pattern is common
Semantic tokens	All code examples use semantic color tokens (color="text", bg="background") — never hardcoded hex or raw palette names
No AI-speak	Write imperatively. No "this skill will help you…", "certainly", or meta-commentary

---

Consistency checklist

Run this against your draft before committing:

• name field matches directory name exactly (kebab-case)
• description starts with "Use this skill when" and lists ≥2 concrete trigger scenarios
• H1 title is present and matches skill purpose
• See also: block with ≥1 related skill and a one-line reason
• ≥1 Storybook link using a full gamut.codecademy.com URL
• All code blocks have a language marker
• "When to use" has both positive cases and a "Do not use when" sub-list
• No hardcoded hex (#...) or raw palette names in code examples
• No duplication of accessibility.mdc — link to it instead
• Props table includes: name, type, default, notes
• Non-obvious gotchas have a callout block
• No trailing "See also" list that duplicates the top See also: block
• Source code GitHub link present
• Draft reviewed with /writing-great-skills before committing

---

Storybook integration

Both steps are required after writing the skill.

Step 1 — Add to Best practices list

File: packages/styleguide/src/lib/Meta/AI Tooling/Gamut plugin/Best practices.mdx

- `gamut-{name}` — {one-line description, matching the skill's overview sentence}

Group the entry near related skills (e.g. new list/table skills go after gamut-datalist; new form skills go after gamut-forms).

Step 2 — Add Callout to component Storybook page

File: the component's MDX (e.g. packages/styleguide/src/lib/Organisms/.../ComponentName.mdx)

If Callout is not yet imported, add it to the ~styleguide/blocks import:

- import { ComponentHeader } from '~styleguide/blocks';
+ import { Callout, ComponentHeader } from '~styleguide/blocks';

Place the callout immediately after <ComponentHeader {...parameters} /> or <AboutHeader {...parameters} />:

<Callout text="Use the /gamut-{name} skill in Cursor or Claude Code for AI-assisted usage guidance, prop reference, and code patterns." />

For skills covering a concept rather than a single component (e.g. gamut-color-mode, gamut-layout), add the callout to the primary concept page (ColorMode.mdx, Layout.mdx, etc.) — not every page that tangentially touches the concept.

---

Reference skills by type

Type	Skill	Read it for
Tight component	gamut-buttons	Scope discipline, clean "When to use / not use"
Organism with full API	gamut-datatable	Props table + ColumnConfig + gotcha note pattern
Audit / workflow	gamut-review	Multi-phase check structure, remediation pointers
System / concept	gamut-color-mode	Semantic-first framing, cross-skill boundaries