skills/plugins/suaveplan-skill-creator/skills/skill-creator/SKILL.md

name, description

name	description
skill-creator	Create new Claude Code skills for the Suaveplan monorepo plugin marketplace following project conventions, progressive disclosure, and degrees-of-freedom principles

Skill Creator for Suaveplan

Create new Claude Code skills (SKILL.md files) within the Suaveplan plugin marketplace at .claude/plugins/suaveplan-plugins/. Each skill is a focused instruction set that teaches Claude how to perform a specific task within the Suaveplan monorepo, following established patterns for React 19, TypeScript, Tailwind CSS, Biome, Vitest, and the monorepo architecture.

Marketplace Structure

The Suaveplan skill marketplace lives at:

.claude/plugins/suaveplan-plugins/
  .claude-plugin/                     # Marketplace metadata directory
  plugins/
    suaveplan-<skill-group>/          # Plugin container
      .claude-plugin/                 # Plugin metadata directory
      skills/
        <skill-name>/
          SKILL.md                    # The skill definition file

Existing Plugins

Plugin Directory	Skill(s)	Purpose
suaveplan-webapp-testing	webapp-testing	Playwright + Storybook E2E testing
suaveplan-web-artifacts	web-artifacts-builder	React component and page building
suaveplan-mcp-builder	mcp-builder	MCP server plugins
suaveplan-doc-coauthoring	doc-coauthoring	Module documentation
suaveplan-skill-creator	skill-creator	Creating new skills (this skill)
suaveplan-theme-factory	theme-factory	Tailwind/shadcn theme generation
suaveplan-frontend-design	frontend-design	UI/UX design patterns
suaveplan-threejs	Multiple	Three.js/R3F sub-skills
suaveplan-webgpu	webgpu-threejs-tsl	WebGPU shader language

Creating a New Skill

Step 1: Plan the Skill

Before writing, answer these questions:

1. What task does this skill accomplish? (one sentence)
2. Which Suaveplan packages does it touch? (list them)
3. What existing patterns should it reference? (file structure, testing, linting)
4. What are the degrees of freedom? (what can the user customize vs. what is fixed)

Step 2: Create the Directory Structure

# Create the plugin container and skill directory
mkdir -p .claude/plugins/suaveplan-plugins/plugins/suaveplan-<group>/skills/<skill-name>
mkdir -p .claude/plugins/suaveplan-plugins/plugins/suaveplan-<group>/.claude-plugin

Step 3: Write the SKILL.md

Every SKILL.md follows this structure:

---
name: <skill-name>
description: <One line describing the skill in context of Suaveplan, React 19, TypeScript, Tailwind>
---

# <Skill Title> for Suaveplan

<Opening paragraph: what this skill does, when to use it, 2-3 sentences max>

## Architecture
<Technology table or diagram showing how this fits into Suaveplan>

## File Structure
<Show the directory layout this skill produces or works with>

## Patterns
<The core patterns and code templates, with TypeScript examples>

## Constraints
<Hard rules: line limits, coverage requirements, tooling choices>

## Checklist
<Numbered list of verification steps before marking work complete>

Step 4: Enable the Plugin

Add the plugin to .claude/settings.local.json:

{
  "enabledPlugins": {
    "suaveplan-<group>@suaveplan-plugins": true
  }
}

Core Principles for Writing Skills

1. Conciseness

Every sentence must teach something. Remove filler words, motivational language, and redundant explanations.

Wrong:

This powerful and flexible skill enables you to build amazing components that leverage the full power of React 19's cutting-edge features.

Right:

Build React 19 components within the Suaveplan monorepo using TypeScript, Tailwind CSS, and shadcn/ui from @suaveplan/react-ui.

2. Progressive Disclosure

Start with the simplest correct usage, then layer complexity. Structure information so a reader can stop at any point and have enough to begin work.

1. One-sentence purpose
2. Technology table (what tools are used)
3. File structure (where things go)
4. Basic pattern (simplest correct example)
5. Advanced pattern (composition, configuration, edge cases)
6. Constraints (hard rules)
7. Checklist (verification steps)

3. Degrees of Freedom

Clearly distinguish between:

• Fixed -- things the developer cannot change (linter, test framework, file naming)
• Configurable -- things with sensible defaults that can be overridden
• Open -- things the developer decides entirely

Example:

Fixed:       Biome for linting (not ESLint), Vitest for tests, .spec.ts for E2E
Configurable: Component variant styles (via cva), Storybook port numbers
Open:        Component API design, business logic, state management approach

4. Suaveplan Context

Every skill must reference the monorepo conventions:

• React 19 with TypeScript strict mode
• Tailwind CSS with cn() from @suaveplan/react-ui
• Biome for linting (never ESLint)
• Vitest for unit tests, Playwright for E2E
• Bun as package manager, Turborepo for task orchestration
• No mocks -- real implementations in tests
• 95% test coverage minimum
• 250-line implementation file limit, 500-line test file limit
• Documentation -- .md file co-located with every implementation file, 200+ words, simple + advanced examples
• data-testid with sp- prefix for all Suaveplan components
• workspace:* for internal dependencies
• No tsc -- Vite/tsup handle compilation, TypeScript for type-checking only

5. Actionable Code Examples

Every pattern in a SKILL.md must include a TypeScript code example that:

• Uses real import paths (@suaveplan/react-ui, not ./utils)
• Compiles with the project's TypeScript configuration
• Follows Biome formatting rules
• Includes type annotations

SKILL.md Frontmatter

Every SKILL.md must start with YAML frontmatter:

---
name: <skill-name>          # Lowercase, hyphenated, matches directory name
description: <description>   # Must mention Suaveplan + relevant technologies
---

The name field must match the skill directory name exactly. The description should be under 150 characters and mention the primary technologies.

Validation Checklist for New Skills

Before considering a skill complete:

1. Frontmatter has name and description fields
2. name matches the directory name
3. description mentions Suaveplan and primary technologies
4. Opening paragraph explains what and when (not why or motivation)
5. Technology table lists all tools and frameworks
6. File structure shows actual monorepo paths
7. Code examples use real @suaveplan/* imports
8. Constraints section lists all hard rules (line limits, coverage, linting)
9. Checklist section provides verification steps
10. No marketing language, no emojis, no filler
11. All fixed conventions are stated (Biome, Vitest, Playwright, Bun)
12. Degrees of freedom are clear (what is fixed vs. configurable vs. open)

Example: Minimal Skill

---
name: csv-export
description: Export Suaveplan data tables to CSV using TypeScript streaming and React 19 download patterns
---

# CSV Export for Suaveplan

Generate CSV files from `@suaveplan/react-data-table` data using TypeScript streaming. Works client-side with Blob URLs or server-side with Node.js streams.

## Architecture

| Layer | Technology |
|-------|-----------|
| Data Source | `@suaveplan/react-data-table` column definitions |
| Encoding | TextEncoder streaming API |
| Download | Blob URL + anchor click (browser) |
| Testing | Vitest |

## File Structure

\`\`\`
src/utils/csv-export/
  csv-export.ts          # Implementation
  csv-export.test.ts     # Tests
  csv-export.types.ts    # Types
  csv-export.md          # Documentation
\`\`\`

## Basic Pattern

\`\`\`typescript
import { exportToCsv } from './csv-export';
import type { ColumnDef } from '@suaveplan/react-data-table';

const columns: ColumnDef[] = [
  { accessorKey: 'name', header: 'Name' },
  { accessorKey: 'email', header: 'Email' },
];

const data = [{ name: 'Alice', email: 'alice@example.com' }];
const csv = exportToCsv(columns, data);
// "Name,Email\nAlice,alice@example.com"
\`\`\`

## Constraints

- Max 250 lines per file
- 95% test coverage
- No external CSV libraries -- use TextEncoder
- Handle commas, quotes, and newlines in cell values per RFC 4180

## Checklist

1. Implementation handles all RFC 4180 edge cases
2. Tests cover: empty data, special characters, large datasets, Unicode
3. Documentation has simple + advanced examples
4. Biome lint clean
\`\`\`

Constraints

• Skills must be concise -- remove every unnecessary word
• No Python scripts or external tooling -- manual directory creation only
• Every skill must reference Suaveplan monorepo conventions
• Code examples must compile with project TypeScript config
• No emojis in SKILL.md files
• Progressive disclosure: simplest information first, complexity layers later
• One skill per directory -- no multi-skill files