Move docs/ package mirror into document-navigator plugin
Relocate the ~6k-file docs tree from the repo root into plugins/document-navigator/docs/ so the plugin is self-contained and portable. docs/superpowers/ (specs and plans) stays at the repo root. Moved via cp+rm rather than git mv because directory rename() fails with EPERM on this WSL /mnt DrvFs mount; git rename-detection pairs the identical-content files at commit time. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,5 @@
|
||||
{
|
||||
"name": "suaveplan-skill-creator",
|
||||
"version": "1.0.0",
|
||||
"description": "Guide for creating project-local skills in the suaveplan-plugins marketplace"
|
||||
}
|
||||
269
plugins/suaveplan-skill-creator/skills/skill-creator/SKILL.md
Normal file
269
plugins/suaveplan-skill-creator/skills/skill-creator/SKILL.md
Normal file
@@ -0,0 +1,269 @@
|
||||
---
|
||||
name: skill-creator
|
||||
description: 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:
|
||||
|
||||
```text
|
||||
.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
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```markdown
|
||||
---
|
||||
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`:
|
||||
|
||||
```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.
|
||||
|
||||
```text
|
||||
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:
|
||||
|
||||
```text
|
||||
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:
|
||||
|
||||
```yaml
|
||||
---
|
||||
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
|
||||
|
||||
```markdown
|
||||
---
|
||||
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
|
||||
Reference in New Issue
Block a user