From 33628a9d24c0af0d2d63782df841b923b9a59129 Mon Sep 17 00:00:00 2001 From: Rahim Date: Mon, 26 Jan 2026 18:36:56 +1100 Subject: [PATCH] chore(claude): add /create-skill --- .claude/skills/README.md | 2 + .claude/skills/create-skill/SKILL.md | 190 ++++++++++++ .../create-skill/references/patterns.md | 276 ++++++++++++++++++ .../create-skill/references/principles.md | 134 +++++++++ .../create-skill/references/structure.md | 240 +++++++++++++++ 5 files changed, 842 insertions(+) create mode 100644 .claude/skills/create-skill/SKILL.md create mode 100644 .claude/skills/create-skill/references/patterns.md create mode 100644 .claude/skills/create-skill/references/principles.md create mode 100644 .claude/skills/create-skill/references/structure.md diff --git a/.claude/skills/README.md b/.claude/skills/README.md index 2fba165b..aba7b294 100644 --- a/.claude/skills/README.md +++ b/.claude/skills/README.md @@ -20,6 +20,7 @@ Specialized knowledge for AI agents working on Video.js 10. | Reviewing branch changes | `/review-branch` | | Analyzing GitHub issues | `/gh-issue` | | Updating AI docs | `/claude-update` | +| Creating new skills | `/create-skill` | ## Skills @@ -30,6 +31,7 @@ Specialized knowledge for AI agents working on Video.js 10. | [claude-update](claude-update/SKILL.md) | Update CLAUDE.md and skills when introducing new patterns | No | | [commit-pr](commit-pr/SKILL.md) | Commit changes and create/update PRs with conventions | No | | [component](component/SKILL.md) | Build headless UI components — compound patterns, state, styling | Yes | +| [create-skill](create-skill/SKILL.md) | Create new skills with proper structure and conventions | No | | [docs](docs/SKILL.md) | Write Video.js 10 documentation | Yes | | [gh-issue](gh-issue/SKILL.md) | Analyze GitHub issues and create implementation plans | No | | [git](git/SKILL.md) | Git workflow — commit messages, PRs, branch naming, scope inference | No | diff --git a/.claude/skills/create-skill/SKILL.md b/.claude/skills/create-skill/SKILL.md new file mode 100644 index 00000000..d09a22a9 --- /dev/null +++ b/.claude/skills/create-skill/SKILL.md @@ -0,0 +1,190 @@ +--- +name: create-skill +description: >- + Create new skills for Claude agents. Use when adding specialized knowledge, + workflows, or commands. Guides through structure, frontmatter, and conventions. + Triggers: "create skill", "new skill", "add skill", "write skill". +allowed-tools: Bash(mkdir:*), Bash(ls:*), Glob, Grep, Read, Write, Edit, question +context: fork +--- + +# Create Skill + +Create a new skill with proper structure and conventions. + +## Usage + +``` +/create-skill [name] +``` + +- `name` (optional): Skill identifier. If omitted, will prompt interactively. + +## Arguments + +$ARGUMENTS + +## When to Create a Skill + +**Create a skill when:** + +- Domain-specific knowledge that Claude doesn't inherently have +- Multi-step workflows that benefit from procedural guidance +- Automated commands that should run in isolated context +- Patterns used repeatedly across conversations + +**Don't create a skill when:** + +- Cross-cutting convention (naming, utilities) → add to CLAUDE.md Code Rules +- One-off task → just do it +- Information Claude already knows well → unnecessary context bloat + +**Decision tree:** + +``` +Is this domain-specific knowledge? +├─ No → Does it affect multiple domains? +│ ├─ Yes → CLAUDE.md Code Rules +│ └─ No → Probably don't need anything +└─ Yes → Create a skill + ├─ Reference material for a domain? → Knowledge skill + ├─ Conventions and processes? → Workflow skill + └─ Automated multi-step task? → Command skill +``` + +## Skill Types + +| Type | Characteristics | Examples | +| ------------- | ------------------------------------------------------------ | ------------------------------------- | +| **Knowledge** | Domain expertise, reference-heavy, may have review workflow | `api`, `component`, `aria`, `docs` | +| **Workflow** | Conventions, processes, templates | `git`, `rfc` | +| **Command** | Procedural steps, forked context, restricted tools | `commit-pr`, `gh-issue`, `review-branch` | + +## Quick Reference + +**Frontmatter (required):** + +```yaml +name: skill-name +description: >- + What it does. Use when X. Triggers: "phrase1", "phrase2". +``` + +**Frontmatter (optional):** + +```yaml +context: fork # Isolated sub-agent context +allowed-tools: Tool1, Tool2 # Restrict available tools +agent: plan # Plan mode (no edits) +disable-model-invocation: true # Prevent model calls +``` + +**Structure options:** + +``` +skill-name/ +├── SKILL.md # Always required +├── references/ # Detailed content (load on demand) +├── templates/ # Output templates +└── review/ # Review workflow (if applicable) +``` + +## Reference Material + +| Topic | Load | +| -------------------------------------------------- | --------------------------- | +| Core principles (conciseness, progressive disclosure) | `references/principles.md` | +| Full structure and frontmatter schema | `references/structure.md` | +| Complete examples of each skill type | `references/patterns.md` | + +## Your Tasks + +### Step 1: Validate Need + +Before creating, verify this should be a skill: + +1. Check if similar skill exists: `ls .claude/skills/` +2. Check if pattern belongs in CLAUDE.md instead +3. If skill name provided, check for conflicts with existing skills + +If the pattern is cross-cutting (affects all domains), suggest adding to CLAUDE.md Code Rules instead. + +### Step 2: Gather Requirements + +Ask the user (use `question` tool): + +1. **Skill type**: Knowledge, Workflow, or Command? +2. **Purpose**: What problem does this skill solve? +3. **Triggers**: What phrases should activate this skill? +4. **Scope**: What topics/tasks does it cover? +5. **Review capability**: Does it need a review workflow? +6. **Templates**: Does it need output templates? + +### Step 3: Plan Structure + +Based on requirements, determine: + +- Skill name (kebab-case) +- Which directories needed (`references/`, `templates/`, `review/`) +- Reference file names and purposes + +### Step 4: Create Skill + +1. Create skill directory: + + ```bash + mkdir -p .claude/skills/ + ``` + +2. Create SKILL.md with: + - Proper frontmatter (name, description, optional fields based on type) + - Section headers with guidance comments + - Reference table (if using references/) + - Related Skills section + +3. Create subdirectories if needed: + + ```bash + mkdir -p .claude/skills//references + mkdir -p .claude/skills//templates + mkdir -p .claude/skills//review + ``` + +4. Create placeholder reference files with: + - Clear purpose header + - Section structure + - TODO markers for content + +### Step 5: Update README + +Add the new skill to `.claude/skills/README.md`: + +1. Add to "Quick Reference" table (if it's a workflow) +2. Add to "Skills" table with purpose and review status + +### Step 6: Report + +Output: + +- Created file structure +- Next steps (fill in content, test triggers) +- Reminder to load `principles.md` when writing content + +## What NOT to Include + +Skills should only contain what Claude needs to do the job: + +- No README.md, INSTALLATION_GUIDE.md, CHANGELOG.md +- No setup and testing procedures +- No user-facing documentation about the skill +- No duplicate information (lives in SKILL.md OR references, not both) + +## After Creating + +Checklist: + +- [ ] Fill in SKILL.md content +- [ ] Write reference files (if any) +- [ ] Test trigger phrases work +- [ ] Verify skill loads correctly +- [ ] Update README.md tables diff --git a/.claude/skills/create-skill/references/patterns.md b/.claude/skills/create-skill/references/patterns.md new file mode 100644 index 00000000..e776ff7e --- /dev/null +++ b/.claude/skills/create-skill/references/patterns.md @@ -0,0 +1,276 @@ +# Skill Patterns + +Complete examples of each skill type. + +## Knowledge Skill Example + +Based on `component` skill — domain expertise with review capability. + +```markdown +--- +name: component +description: >- + Build accessible, headless UI components with modern architecture patterns. + Use when creating component libraries, design systems, or reusable UI primitives. + Handles compound components, state management, accessibility, styling hooks. + Includes Lit (controllers, ReactiveElement) and React (hooks, context) patterns. +--- + +# Component Architecture Patterns + +Build accessible, headless UI components using proven patterns. + +**Primary sources:** +- [Base UI Handbook](https://base-ui.com/react/handbook/overview) +- [Ark UI](https://ark-ui.com/) + +--- + +## Core Principles + +1. **Headless over styled** — Separate behavior from presentation +2. **Compound over monolithic** — Small composable parts +3. **Accessible by default** — ARIA, keyboard, focus built-in + +--- + +## Pattern 1: Compound Components + +**What:** Components as related parts sharing state through context. + +**Why:** Declarative, independently styleable, maps to ARIA roles. + +--- + +## Reference Files + +| File | Contents | +|------|----------| +| [lit.md](references/lit.md) | Lit controllers, mixins | +| [react.md](references/react.md) | React hooks, context | +| [props.md](references/props.md) | Prop naming conventions | + +## Review + +For component reviews, load `review/workflow.md`. + +## Related Skills + +| Need | Use | +|------|-----| +| Accessibility | `aria` skill | +| API design | `api` skill | +``` + +**Key characteristics:** + +- Rich description with multiple trigger phrases +- Quick reference section with core principles +- Reference table for detailed content +- Review section linking to workflow +- Related skills for cross-domain work + +--- + +## Workflow Skill Example + +Based on `git` skill — conventions and processes. + +```markdown +--- +name: git +description: >- + Git workflow conventions for Video.js 10. Commit messages, PR descriptions, + branch naming, and scope inference. Triggers: "commit", "push", "create PR", + "conventional commit", "branch name". +context: fork +--- + +# Git + +Git workflow conventions for Video.js 10. + +## Reference Material + +| Task | Load | +|------|------| +| Writing commits | `references/commit.md` | +| Inferring scope | `references/scope.md` | +| Creating PRs | `references/pr.md` | +| Naming branches | `references/branch.md` | + +## Quick Reference + +**Commit:** `type(scope): lowercase description` + +**Branch:** `type/short-description` + +**PR Title:** Same as commit + +## Process + +1. Create branch following naming convention +2. Make changes +3. Commit with conventional message +4. Push and create PR +``` + +**Key characteristics:** + +- `context: fork` for isolated execution +- Reference table organized by task +- Quick reference with condensed conventions +- Simple linear process + +--- + +## Command Skill Example + +Based on `commit-pr` skill — automated multi-step task. + +```markdown +--- +name: commit-pr +description: >- + Commit all changes and create or update a PR following project conventions. + Triggers: "commit and pr", "push changes", "create pull request". +allowed-tools: Bash(git:*), Bash(gh:*), Glob, Grep, Read, question, mcp__github__* +context: fork +--- + +# Commit & PR + +Stage all changes, create a conventional commit, and open a pull request. + +## Usage + +\`\`\` +/commit-pr [refs] +\`\`\` + +- `refs` (optional): Issue/PR references (e.g., `#123`, `fixes #456`) + +## Arguments + +$ARGUMENTS + +## Conventions + +Load the `git` skill for commit and PR conventions. + +## Your Tasks + +### Step 1: Load Conventions + +Load the `git` skill. + +### Step 2: Analyze Changes + +1. Run `git status` +2. Run `git diff --staged` and `git diff` +3. Read files if needed for context + +### Step 3: Determine Commit Type and Scope + +Based on changes and `git` skill conventions. + +### Step 4: Create Commit + +1. Stage: `git add -A` +2. Commit: `git commit -m "type(scope): description"` + +### Step 5: Push and Create/Update PR + +1. Push: `git push -u origin HEAD` +2. Check for existing PR +3. Create or update as needed + +### Step 6: Report + +Output PR URL and status. + +## Important + +- Always stage ALL changes +- Check for existing PR before creating +- Follow PR description principles +``` + +**Key characteristics:** + +- `allowed-tools` restricts to git/GitHub tools +- `context: fork` for isolated execution +- `$ARGUMENTS` placeholder for user input +- Step-by-step "Your Tasks" section +- Loads other skills for domain knowledge +- "Important" section with constraints + +--- + +## Review Workflow Pattern + +Structure for skills with review capability: + +``` +skill/ +└── review/ + ├── workflow.md # Main entry point + ├── checklist.md # Quick checklist + ├── templates.md # Output formats + └── agents.md # Sub-agent prompts (optional) +``` + +### workflow.md Template + +```markdown +# Skill Review Workflow + +Review X for quality and correctness. + +## When to Use + +- Before merging PRs that touch X +- When auditing existing X +- When requested by user + +## Process + +### Single-Agent Review + +1. Load checklist from `checklist.md` +2. Review against each item +3. Output issues using format from `templates.md` + +### Multi-Agent Review (Large Scope) + +1. Load agent prompts from `agents.md` +2. Spawn agents for each domain +3. Merge findings +4. Output consolidated report + +## Severity Levels + +| Level | Description | +|-------|-------------| +| Critical | Must fix before merge | +| Warning | Should fix, may defer | +| Note | Suggestion for improvement | +``` + +### checklist.md Template + +```markdown +# Skill Review Checklist + +Quick checklist for single-agent review. + +## Category A + +- [ ] Check item 1 +- [ ] Check item 2 + +## Category B + +- [ ] Check item 3 +- [ ] Check item 4 +``` diff --git a/.claude/skills/create-skill/references/principles.md b/.claude/skills/create-skill/references/principles.md new file mode 100644 index 00000000..3afefdc0 --- /dev/null +++ b/.claude/skills/create-skill/references/principles.md @@ -0,0 +1,134 @@ +# Skill Principles + +Core principles for writing effective skills. + +## Concise is Key + +The context window is a shared resource. Skills compete with system prompts, conversation history, and user requests. + +**Guidelines:** + +- Claude is already smart — only add knowledge Claude doesn't have +- Challenge each paragraph: "Does this justify its token cost?" +- Prefer concise examples over verbose explanations +- If Claude can figure it out, don't explain it + +**Example:** + +```markdown +// ❌ Verbose +In order to create a new component, you'll need to first understand +the component architecture patterns. Components in this codebase follow +the compound component pattern, which means... + +// ✅ Concise +Components use compound pattern. See `component` skill for details. +``` + +## Degrees of Freedom + +Match specificity to task fragility: + +| Freedom | When to Use | Format | +| ---------- | ---------------------------------------------- | ------------------------------------- | +| **High** | Multiple valid approaches, context-dependent | Text instructions | +| **Medium** | Preferred pattern exists, some variation OK | Pseudocode, templates with parameters | +| **Low** | Fragile operations, consistency critical | Specific steps, exact commands | + +**Metaphor:** A narrow bridge needs guardrails (low freedom). An open field allows many routes (high freedom). + +**Examples:** + +```markdown +// High freedom — many valid approaches +Write documentation following the tone and style guidelines. + +// Medium freedom — preferred pattern +Use this template structure: +## Overview +## Usage +## API Reference + +// Low freedom — exact sequence required +1. Run `git add -A` +2. Run `git commit -m "type(scope): message"` +3. Run `git push -u origin HEAD` +``` + +## Progressive Disclosure + +Skills use a three-level loading system: + +| Level | What | When Loaded | Target Size | +| ----- | -------------------------------- | -------------------- | ------------ | +| 1 | Metadata (name + description) | Always | ~100 words | +| 2 | SKILL.md body | When skill triggers | <500 lines | +| 3 | references/ files | On demand | Unlimited | + +**Key insight:** Description is the ONLY thing Claude sees before deciding to load a skill. All "when to use" info MUST be in the description, not the body. + +## Progressive Disclosure Patterns + +### Pattern 1: High-Level Guide with References + +Keep SKILL.md focused, link to details: + +```markdown +## Quick Reference + +Create components using compound pattern with data attributes for styling. + +## Detailed Guides + +- **Props conventions**: See [props.md](references/props.md) +- **Styling patterns**: See [styling.md](references/styling.md) +- **Accessibility**: See [aria.md](references/aria.md) +``` + +### Pattern 2: Domain-Specific Organization + +Organize by domain to avoid loading irrelevant content: + +``` +skill/ +├── SKILL.md (overview + navigation) +└── references/ + ├── react.md # React-specific patterns + ├── lit.md # Lit-specific patterns + └── vanilla.md # Vanilla JS patterns +``` + +When user asks about React, Claude only loads `react.md`. + +### Pattern 3: Conditional Details + +Show basics, link to advanced: + +```markdown +## Creating Components + +Use compound pattern with Root, Trigger, and Content parts. + +**For animations**: See [animation.md](references/animation.md) +**For collections**: See [collection.md](references/collection.md) +``` + +## Information Placement + +Information lives in ONE place: + +| Content Type | Location | +| ------------------------------------ | ------------ | +| Quick reference, process overview | SKILL.md | +| Detailed patterns, examples, schemas | references/ | +| Output formats, boilerplate | templates/ | +| Review checklists, agent prompts | review/ | + +**Anti-pattern:** Duplicating information between SKILL.md and references. This wastes tokens and creates maintenance burden. + +## Reference File Guidelines + +- Keep references one level deep from SKILL.md +- Files >100 lines should have a table of contents +- Structure by domain or variant, not by "type of content" +- Include code examples — they're often more concise than prose diff --git a/.claude/skills/create-skill/references/structure.md b/.claude/skills/create-skill/references/structure.md new file mode 100644 index 00000000..ff2ed042 --- /dev/null +++ b/.claude/skills/create-skill/references/structure.md @@ -0,0 +1,240 @@ +# Skill Structure + +Complete reference for skill structure and frontmatter. + +## Frontmatter Schema + +### Required Fields + +| Field | Type | Description | +| ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | +| `name` | string | Skill identifier. Used with `skill` tool. Kebab-case, lowercase. | +| `description` | string | When to use and trigger phrases. This is the PRIMARY mechanism for skill selection — Claude only sees this before deciding to load. | + +### Optional Fields + +| Field | Type | Default | Description | +| -------------------------- | --------- | ------- | ----------------------------------------------------------------------------------------------------- | +| `context` | `fork` | — | Creates isolated sub-agent context. Use for command skills that run autonomously. | +| `allowed-tools` | string | all | Restricts available tools. Format: `Tool1, Tool2, Bash(cmd:*)`. Use for command skills. | +| `agent` | `plan` | — | Sets agent to plan/research mode. Agent cannot make edits, only read and analyze. | +| `disable-model-invocation` | boolean | false | Prevents skill from invoking other models. Use for skills that should only provide guidance. | + +### Description Best Practices + +```yaml +# ❌ Too brief — won't trigger correctly +description: Component patterns + +# ❌ Triggers in body — won't work (body loads AFTER triggering) +description: Component patterns +--- +## When to Use +Use this skill when building components... + +# ✅ Complete — triggers included +description: >- + Build accessible, headless UI components with modern architecture patterns. + Use when creating component libraries, design systems, or reusable UI primitives. + Handles compound components, state management, accessibility, styling hooks. + Triggers: "create component", "component architecture", "compound component". +``` + +## Directory Structure + +### Minimal (Command/Simple Workflow) + +``` +skill-name/ +└── SKILL.md +``` + +Use for: Simple commands, straightforward workflows. + +Examples: `commit-pr`, `claude-update` + +### With References (Knowledge/Complex Workflow) + +``` +skill-name/ +├── SKILL.md +└── references/ + ├── topic-a.md + ├── topic-b.md + └── topic-c.md +``` + +Use for: Domain expertise, detailed patterns, multiple topics. + +Examples: `api`, `component`, `aria` + +### With Templates (Output-Focused) + +``` +skill-name/ +├── SKILL.md +├── references/ +└── templates/ + ├── output-type-a.md + ├── output-type-b.md + └── output-type-c.md +``` + +Use for: Skills that produce structured outputs (docs, RFCs, etc.). + +Examples: `docs`, `rfc` + +### With Review Capability + +``` +skill-name/ +├── SKILL.md +├── references/ +└── review/ + ├── workflow.md # Review process, when to use + ├── checklist.md # Quick single-agent checklist + ├── templates.md # Output formats for issues/reports + └── agents.md # Sub-agent prompts (if multi-agent) +``` + +Use for: Skills that can review existing code/content. + +Examples: `api`, `component`, `aria`, `docs` + +## SKILL.md Structure + +### Knowledge Skill Template + +```markdown +--- +name: skill-name +description: >- + Domain description. Use when X, Y, Z. + Triggers: "phrase1", "phrase2", "phrase3". +--- + +# Skill Title + +Brief overview (1-2 sentences). + +## Quick Reference + +Most important patterns/rules in condensed form. + +## Reference Files + +| File | Contents | +|------|----------| +| [references/topic-a.md](references/topic-a.md) | Description | +| [references/topic-b.md](references/topic-b.md) | Description | + +## Review + +For reviewing X, load `review/workflow.md`. + +## Related Skills + +| Need | Use | +|------|-----| +| Related domain | `other-skill` skill | +``` + +### Command Skill Template + +```markdown +--- +name: skill-name +description: >- + What command does. Triggers: "phrase1", "phrase2". +allowed-tools: Tool1, Tool2, Bash(cmd:*) +context: fork +--- + +# Command Name + +Brief description of what the command does. + +## Usage + +\`\`\` +/skill-name [args] +\`\`\` + +- `arg` (optional/required): Description + +## Arguments + +$ARGUMENTS + +## Your Tasks + +### Step 1: Task Name + +Instructions... + +### Step 2: Task Name + +Instructions... + +## Important + +- Key constraint 1 +- Key constraint 2 +``` + +### Workflow Skill Template + +```markdown +--- +name: skill-name +description: >- + Workflow description. Triggers: "phrase1", "phrase2". +context: fork +--- + +# Workflow Name + +Brief overview. + +## Reference Material + +| Task | Load | +|------|------| +| Task type A | `references/a.md` | +| Task type B | `references/b.md` | + +## Quick Reference + +Key conventions in condensed form. + +## Process + +1. Step one +2. Step two +3. Step three +``` + +## Naming Conventions + +| Element | Convention | Example | +| ---------------- | ----------- | -------------------- | +| Skill directory | kebab-case | `create-skill/` | +| Skill name | kebab-case | `create-skill` | +| Reference files | kebab-case | `anti-patterns.md` | +| Template files | kebab-case | `component-page.md` | + +## Tool Restriction Patterns + +```yaml +# Git and GitHub only +allowed-tools: Bash(git:*), Bash(gh:*), Glob, Grep, Read, mcp__github__* + +# Read-only exploration +allowed-tools: Glob, Grep, Read + +# File creation allowed +allowed-tools: Bash(mkdir:*), Glob, Grep, Read, Write, Edit + +# With user interaction +allowed-tools: Bash(git:*), Glob, Grep, Read, question +```