claude-skills-cli 0.0.6 → 0.0.8

package/docs/SKILL-DEVELOPMENT.md

@@ -1,460 +0,0 @@
-# Skill Development Workflow
-
-## Quick Start
-
-```bash
-# Create a new skill
-claude-skills init --name my-skill --description "What it does"
-
-# Validate the skill
-claude-skills validate .claude/skills/my-skill
-
-# Package for distribution
-claude-skills package .claude/skills/my-skill
-```
-
-## The 6-Step Process
-
-Based on Anthropic's skill-creator methodology, adapted for
-devhub-crm.
-
-### Step 1: Understanding with Concrete Examples
-
-**Goal**: Clearly understand how the skill will be used in practice.
-
-**Process**:
-
-1. Identify specific scenarios where skill is needed
-2. Collect real examples from your workflow
-3. Note what Claude struggles with currently
-4. Validate examples with actual usage
-
-**Example Questions**:
-
-- "What task am I repeating that needs this skill?"
-- "Can I give 3-5 concrete examples of using this?"
-- "What would trigger Claude to use this skill?"
-- "What information does Claude need that I keep providing?"
-
-**Output**: 3-5 concrete examples of skill usage
-
----
-
-### Step 2: Planning Reusable Contents
-
-**Goal**: Analyze examples to determine what to include in skill.
-
-**For each example, ask**:
-
-1. What would Claude need to execute this from scratch?
-2. What code is being rewritten repeatedly? → `scripts/`
-3. What context is repeated each time? → `SKILL.md` or `references/`
-4. What templates or assets are reused? → `assets/`
-
-**Decision Matrix**:
-
-| Content Type           | Goes In     | Example                          |
-| ---------------------- | ----------- | -------------------------------- |
-| Core workflow patterns | SKILL.md    | "Always use prepared statements" |
-| Detailed documentation | references/ | Complete API reference           |
-| Repeated code          | scripts/    | Validation logic                 |
-| Templates/resources    | assets/     | Boilerplate HTML                 |
-
-**Output**: List of files to create with their purposes
-
----
-
-### Step 3: Initializing the Skill
-
-**Command**:
-
-```bash
-claude-skills init \
-  --name database-patterns \
-  --description "Guide for SQLite operations..."
-```
-
-**What This Creates**:
-
-```
-.claude/skills/database-patterns/
-├── SKILL.md                    # With frontmatter template
-├── README.md                   # Human documentation
-├── references/
-│   └── detailed-guide.md       # Example reference
-├── scripts/
-│   └── example.js              # Example script
-└── assets/                     # Empty directory
-```
-
-**Next**: Customize or delete example files as needed
-
----
-
-### Step 4: Editing the Skill
-
-**Focus**: Write content for another instance of Claude to use
-effectively.
-
-#### Start with Reusable Contents
-
-1. **Add scripts** (if identified in Step 2)
-
-   ```bash
-   cd .claude/skills/database-patterns/scripts/
-   # Create validation, generation, or analysis scripts
-   ```
-
-2. **Add references** (if identified in Step 2)
-
-   ```bash
-   cd references/
-   # Create detailed documentation files
-   ```
-
-3. **Add assets** (if identified in Step 2)
-
-   ```bash
-   cd assets/
-   # Copy templates, images, or other resources
-   ```
-
-4. **Delete unused directories**
-   ```bash
-   # If you don't need scripts:
-   rm -rf scripts/
-   ```
-
-#### Update SKILL.md
-
-**Writing Guidelines**:
-
-- ✅ Use imperative/infinitive form: "Use prepared statements"
-- ❌ Not second person: "You should use prepared statements"
-- ✅ Be specific: "Generate IDs with nanoid()"
-- ❌ Not vague: "Use appropriate IDs"
-
-**Structure to Include**:
-
-```markdown
----
-name: skill-name
-description: [What it does + When to use it]
----
-
-# Skill Title
-
-## Overview
-
-[2-3 sentences on purpose]
-
-## Quick Start
-
-[Minimal example showing basic usage]
-
-## Core Patterns
-
-### Pattern 1
-
-[Common workflow with code example]
-
-### 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.js`: Description
-- `scripts/generate.js`: Description
-
-## Notes
-
-- Important consideration 1
-- Important consideration 2
-```
-
-**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 bundled resources exist? (references, scripts, assets)
-
----
-
-### Step 5: Packaging the Skill
-
-**Validation First**:
-
-```bash
-claude-skills validate .claude/skills/database-patterns
-
-# Output shows:
-# ✅ All required fields present
-# ✅ SKILL.md structure correct
-# ⚠️  Warning: Reference file not mentioned in SKILL.md
-```
-
-**Fix Validation Issues**, then package:
-
-```bash
-claude-skills package .claude/skills/database-patterns
-
-# Creates:
-# dist/database-patterns.zip
-```
-
-**The package includes**:
-
-- All files from skill directory
-- Maintains directory structure
-- Excludes hidden files and temp files
-- Ready to upload to Claude.ai or share
-
----
-
-### Step 6: Iterate
-
-**Test the Skill**:
-
-1. Use skill in real conversations
-2. Notice where it struggles or excels
-3. Collect feedback from actual usage
-4. Update SKILL.md or references based on observations
-
-**Iteration Workflow**:
-
-```bash
-# Edit skill content
-vim .claude/skills/database-patterns/SKILL.md
-
-# Validate changes
-claude-skills validate .claude/skills/database-patterns
-
-# Test in conversation
-# (Skills auto-reload in Claude Code)
-
-# Package new version if needed
-claude-skills package .claude/skills/database-patterns
-```
-
-**Common Iterations**:
-
-- Add more examples to SKILL.md
-- Move detailed content to references
-- Create new scripts for repeated tasks
-- Clarify confusing instructions
-- Add "when to use" guidance
-
----
-
-## Development Best Practices
-
-### Start Small
-
-Begin with minimal SKILL.md, add complexity only as needed:
-
-```markdown
-# Version 1: Just core patterns
-
-# Version 2: Add references
-
-# Version 3: Add scripts
-
-# Version 4: Add assets
-```
-
-### Test Early and Often
-
-Don't wait until skill is "complete":
-
-- Test after basic SKILL.md is written
-- Iterate based on actual usage
-- Skills are never truly "done"
-
-### Use Real Examples
-
-Pull examples from actual code, not invented scenarios:
-
-```typescript
-// ✅ Good: From your actual codebase
-const stmt = db.prepare('SELECT * FROM contacts WHERE user_id = ?');
-const contacts = stmt.all(user_id) as Contact[];
-
-// ❌ Bad: Generic example
-const result = database.query('SELECT * FROM table');
-```
-
-### Keep SKILL.md Lean
-
-When it grows beyond 5k words, split content:
-
-- Core workflows → stay in SKILL.md
-- Detailed docs → move to references/
-- API reference → definitely references/
-
-### Write for Claude, Not Humans
-
-Claude needs different information than developers:
-
-- ✅ Procedural: "To do X, follow these steps..."
-- ✅ Specific: "Use nanoid() to generate IDs"
-- ✅ Concrete: "Store timestamps as Date.now()"
-- ❌ Conceptual: "Think about data integrity..."
-- ❌ Opinion: "We prefer approach X over Y..."
-
-### Document Your Intent
-
-Add comments explaining WHY, not just WHAT:
-
-```markdown
-## ID Generation
-
-Generate IDs with nanoid() to ensure uniqueness without database
-overhead.
-
-<!-- Not just: "Use nanoid()" -->
-```
-
-### Validate Before Sharing
-
-Always run validation:
-
-```bash
-claude-skills validate .claude/skills/my-skill --strict
-```
-
-Strict mode treats warnings as errors - use before packaging for
-distribution.
-
----
-
-## Troubleshooting
-
-### Skill Not Triggering
-
-**Problem**: Claude doesn't use the skill when expected
-
-**Solutions**:
-
-1. Check description includes "when to use" keywords
-2. Make description more specific
-3. Test with explicit request: "Use the database-patterns skill to..."
-4. Verify SKILL.md frontmatter is valid YAML
-
-### Token Limit Exceeded
-
-**Problem**: Skill uses too many tokens
-
-**Solutions**:
-
-1. Move detailed content from SKILL.md to references/
-2. Use scripts for code instead of inline examples
-3. Split large references into focused files
-4. Link to references instead of duplicating content
-
-### Skill Conflicts
-
-**Problem**: Multiple skills trying to handle same task
-
-**Solutions**:
-
-1. Make descriptions more specific
-2. Define clear boundaries between skills
-3. Use skill composition intentionally
-4. Add "when NOT to use" guidance
-
-### Invalid Package
-
-**Problem**: Packaged skill doesn't work
-
-**Solutions**:
-
-1. Run validator before packaging
-2. Check YAML frontmatter syntax
-3. Ensure required fields present
-4. Test skill locally before packaging
-
----
-
-## File Templates
-
-### Minimal SKILL.md
-
-```markdown
----
-name: my-skill
-description: Brief description including when to use this skill
----
-
-# My Skill
-
-## Quick Start
-
-[Minimal working example]
-
-## Core Pattern
-
-[Most common usage]
-```
-
-### Reference File
-
-```markdown
-# Topic Reference
-
-## Overview
-
-[Brief intro]
-
-## Section 1
-
-[Detailed content]
-
-## Section 2
-
-[More detail]
-
-## Examples
-
-[Concrete examples]
-```
-
-### Script File
-
-```javascript
-#!/usr/bin/env node
-
-/**
- * Description of what this script does.
- *
- * Usage:
- *   node script_name.js [arguments]
- *
- * Example:
- *   node validate.js --check-all
- */
-
-function main() {
-	// Script logic here
-}
-
-main();
-```
-
----
-
-## Next Steps
-
-1. Read [SKILLS-ARCHITECTURE.md](SKILLS-ARCHITECTURE.md) for system
-   overview
-2. See [SKILL-EXAMPLES.md](SKILL-EXAMPLES.md) for real examples
-3. Create your first skill with `claude-skills init`
-4. Join skill development workflow for devhub-crm