claude-skills-cli 0.0.3 → 0.0.4

package/skills/skill-creator/SKILL.md

@@ -1,345 +1,106 @@
 ---
 name: skill-creator
-description: Guide for creating effective Claude skills for devhub-crm. Use when users want to create a new skill or update an existing skill that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.
+description: Create Claude Skills using claude-skills-cli. Use when building new skills, running validation, or packaging skills for distribution with TypeScript/Node.
 ---
 
 # Skill Creator
 
-Guide for creating effective Claude skills following Anthropic's best practices, adapted for devhub-crm.
-
-## Overview
-
-Skills are modular packages that extend Claude's capabilities with specialized knowledge, workflows, and tools. Think of them as onboarding guides for specific domains that transform Claude from a general-purpose agent into a specialist equipped with procedural knowledge.
-
-## The 6-Step Creation Process
-
-### Step 1: Understanding with Concrete Examples
-
-**Goal**: Clearly understand how the skill will be used in practice.
-
-**Questions to ask**:
-
-- "What specific task needs this skill?"
-- "Can you give 3-5 concrete examples of using this?"
-- "What would trigger Claude to use this skill?"
-- "What context are you repeatedly providing?"
-
-**Example**:
-
-```
-User: "I need a database skill"
-Claude: "What specific database operations would you use this for?"
-User: "Querying contacts, managing relationships, writing migrations"
-Claude: "Can you give me actual query examples you use frequently?"
-```
-
-**Output**: 3-5 concrete usage examples before proceeding.
-
----
-
-### Step 2: Planning Reusable Contents
-
-**Goal**: Determine what goes in the skill.
-
-**For each example, identify**:
-
-1. What code is rewritten repeatedly? → `scripts/`
-2. What context is repeated? → `SKILL.md` or `references/`
-3. What templates are reused? → `assets/`
-
-**Decision Matrix**:
-
-| Content        | Location    | Example                          |
-| -------------- | ----------- | -------------------------------- |
-| Core workflows | SKILL.md    | "Use prepared statements"        |
-| Detailed docs  | references/ | Complete schema with all columns |
-| Repeated code  | scripts/    | Validation logic, generators     |
-| Templates      | assets/     | Boilerplate files, images        |
-
-**Output**: List of files to create with their purposes.
-
----
-
-### Step 3: Initialize the Skill
-
-**Use the init script**:
-
-```bash
-python .claude/scripts/init_skill.py \
-  --name skill-name \
-  --description "What it does and when to use it"
-```
-
-**This creates**:
-
-```
-.claude/skills/skill-name/
-├── SKILL.md
-├── README.md
-├── references/detailed-guide.md
-├── scripts/example.py
-└── assets/
-```
-
-**Next**: Customize or delete example files as needed.
-
----
-
-### Step 4: Edit the Skill
-
-**Writing Guidelines**:
-
-- ✅ Use imperative voice: "Use prepared statements"
-- ❌ Not second person: "You should use prepared statements"
-- ✅ Be specific: "Generate IDs with nanoid()"
-- ❌ Not vague: "Use appropriate IDs"
-
-**SKILL.md Structure**:
-
-```markdown
----
-name: skill-name
-description: [What it does + when to use it, keywords for discovery]
----
-
-# Skill Title
-
-## Overview
-
-[2-3 sentences on purpose]
+Create effective Claude Skills using the `claude-skills-cli` tool (TypeScript/Node).
 
 ## Quick Start
 
-[Minimal working example]
-
-## Core Patterns
-
-### Pattern 1
-
-[Common workflow with code]
-
-### Pattern 2
-
-[Another common workflow]
-
-## Advanced Usage
-
-For detailed information:
-
-- [references/file1.md](references/file1.md)
-- [references/file2.md](references/file2.md)
-
-## Scripts
-
-- `scripts/validate.py`: Description
-- `scripts/generate.py`: Description
+```bash
+# Create skill
+npx claude-skills init --name my-skill \
+  --description "What it does. Use when [trigger keywords]"
 
-## Notes
+# Validate
+npx claude-skills validate .claude/skills/my-skill
 
-- Important consideration 1
-- Important consideration 2
+# Package
+npx claude-skills package .claude/skills/my-skill
 ```
 
-**Key Questions to Answer**:
-
-1. What is the purpose? (2-3 sentences)
-2. When should this be used? (triggers/contexts)
-3. How should Claude use this? (step-by-step)
-4. What resources are bundled? (references, scripts, assets)
-
-**References Guidelines**:
-
-- One topic per file
-- Descriptive names: `authentication-flow.md` not `auth.md`
-- Include examples and code
-- Link from SKILL.md
-
-**Scripts Guidelines**:
+## Progressive Disclosure System
 
-- Include shebang (`#!/usr/bin/env python3`)
-- Make executable (`chmod +x`)
-- Add usage documentation
-- Handle errors gracefully
+Skills load in 3 levels:
 
-**Assets Guidelines**:
+| Level                       | When Loaded    | Token Budget |
+| --------------------------- | -------------- | ------------ |
+| **Level 1** - Metadata      | Always         | ~100 tokens  |
+| **Level 2** - SKILL.md body | When triggered | <5k tokens   |
+| **Level 3** - Bundled files | As needed      | Unlimited    |
 
-- Templates that get copied/modified
-- Images used in output
-- Boilerplate code
-- Configuration files
-
----
+**Key principle**: Keep Level 1 & 2 lean. Move details to Level 3.
 
-### Step 5: Validate and Package
+## CLI Commands
 
-**Validate first**:
+### init - Create Skill
 
 ```bash
-python .claude/scripts/validate_skill.py .claude/skills/skill-name
+npx claude-skills init --name skill-name \
+  --description "Brief description with trigger keywords"
 ```
 
-**Fix any errors**, then package:
-
-```bash
-python .claude/scripts/package_skill.py .claude/skills/skill-name
-```
+Creates: `SKILL.md`, `README.md`, `references/`
 
-**Creates**: `dist/skill-name.zip` ready for distribution.
-
-**Validation checks**:
-
-- YAML frontmatter format
-- Required fields present
-- Name matches directory
-- References mentioned in SKILL.md
-- Scripts are executable
-- No TODO placeholders
-
----
-
-### Step 6: Test and Iterate
-
-**Testing**:
-
-1. Use skill in real conversations
-2. Notice struggles or inefficiencies
-3. Update based on observations
-
-**Iteration workflow**:
+### validate - Check Quality
 
 ```bash
-# Edit skill
-vim .claude/skills/skill-name/SKILL.md
-
-# Validate
-python .claude/scripts/validate_skill.py .claude/skills/skill-name
-
-# Test in conversation
-# (Skills auto-reload in Claude Code)
-
-# Package if sharing
-python .claude/scripts/package_skill.py .claude/skills/skill-name
+npx claude-skills validate .claude/skills/skill-name
+npx claude-skills validate .claude/skills/skill-name --strict
 ```
 
-**Common improvements**:
+Checks progressive disclosure compliance.
 
-- Add more examples
-- Move details to references
-- Create scripts for repeated patterns
-- Clarify confusing instructions
-- Enhance "when to use" guidance
+### package - Create Zip
 
----
-
-## Progressive Disclosure Principle
-
-Skills load in three levels:
-
-### Level 1: Metadata (~100 tokens)
-
-**Always in context**
-
-```yaml
-name: skill-name
-description: What it does and when to use it
+```bash
+npx claude-skills package .claude/skills/skill-name
 ```
 
-### Level 2: Instructions (<5k tokens)
-
-**Loaded when triggered**
-
-- SKILL.md body with core patterns
-- Links to references and scripts
-
-### Level 3: Resources (unlimited)
-
-**Loaded as needed**
-
-- references/: Documentation Claude reads
-- scripts/: Code Claude executes
-- assets/: Files Claude uses in output
-
-## Best Practices
-
-### Do:
+Creates uploadable zip for Claude.ai or API.
 
-✅ Start with concrete examples
-✅ Use imperative voice
-✅ Keep SKILL.md under 5k words
-✅ Link to references for details
-✅ Include "when to use" in description
-✅ Test on real tasks
-✅ Iterate based on usage
+## Writing Tips
 
-### Don't:
+**Level 1 (Description)**:
 
-❌ Use second person ("you")
-❌ Duplicate content across files
-❌ Include everything inline
-❌ Use generic descriptions
-❌ Leave TODO placeholders
-❌ Skip validation
+- Format: `[Tech] + [Operations] + [Trigger]`
+- Target: <200 chars
+- Include: "Use when...", "Use for...", "Use to..."
 
-## devhub-crm Skill Patterns
+**Level 2 (SKILL.md Body)**:
 
-### Database Skills
+- Target: ~50 lines
+- Structure: Quick Start, Core Patterns (3-5), Links to references
+- Voice: Imperative ("Use X"), not second person ("You should use X")
 
-- Schema in references/schema.md
-- Query patterns in SKILL.md
-- Validation scripts for consistency
-- Migration helpers
+**Level 3 (References)**:
 
-### Component Skills
-
-- Basic templates in SKILL.md
-- Component catalog in references/
-- Example components in assets/
-- Type definitions included
-
-### Integration Skills
-
-- Auth patterns in SKILL.md
-- API docs in references/
-- Connection tests in scripts/
-- Rate limit handling
-
-### Styling Skills
-
-- Core conventions in SKILL.md
-- Complete reference in references/
-- Theme examples in assets/
-- Validation for consistency
-
-## Quick Reference Commands
-
-```bash
-# Create new skill
-python .claude/scripts/init_skill.py --name my-skill --description "..."
-
-# Validate skill
-python .claude/scripts/validate_skill.py .claude/skills/my-skill
-
-# Package skill
-python .claude/scripts/package_skill.py .claude/skills/my-skill
-
-# Validate strictly (warnings = errors)
-python .claude/scripts/validate_skill.py .claude/skills/my-skill --strict
-```
+- Move detailed docs to `references/`
+- Link from SKILL.md
+- Unlimited size
 
-## Resources
+## Reference Documentation
 
-See also:
+For detailed guidance:
 
-- [references/skill-examples.md](references/skill-examples.md) - Real examples from Anthropic
-- [references/writing-guide.md](references/writing-guide.md) - Detailed writing guidelines
-- [../../docs/SKILLS-ARCHITECTURE.md](../../docs/SKILLS-ARCHITECTURE.md) - Complete architecture
-- [../../docs/SKILL-DEVELOPMENT.md](../../docs/SKILL-DEVELOPMENT.md) - Development workflow
+- [cli-reference.md](references/cli-reference.md) - Complete CLI commands and options
+- [cli-feedback.md](references/cli-feedback.md) - Real-world usage patterns and tips
+- [anthropic-resources.md](references/anthropic-resources.md) - Official Anthropic best practices
+- [writing-guide.md](references/writing-guide.md) - Voice, structure, and code examples
+- [skill-examples.md](references/skill-examples.md) - Example skills and patterns
 
 ## Notes
 
-- Skills are never truly "done" - iterate based on usage
-- Start minimal, add complexity as needed
-- Test early and often
-- Real examples beat invented ones
-- Write for Claude, not humans
-- Description drives discovery - make it count
+- Skills are iterative - start minimal, refine based on usage
+- Description drives discovery - make it keyword-rich
+- Validate frequently during development
+- Test in real conversations
+
+<!--
+PROGRESSIVE DISCLOSURE:
+- This is Level 2 - keep lean and scannable
+- Move detailed content to references/
+- Target: ~50 lines for optimal scannability
+-->