claude-skills-cli 0.0.6 → 0.0.8

package/dist/skills/skill-creator/references/development-process.md

@@ -0,0 +1,208 @@
+# Development Process
+
+Step-by-step workflow for creating effective Claude Skills.
+
+## The Seven Steps
+
+### 1. Recognize
+
+Notice when you're repeatedly providing the same context or domain
+knowledge:
+
+- Explaining the same database schema multiple times
+- Providing API integration details in every conversation
+- Sharing framework-specific conventions repeatedly
+- Teaching the same domain concepts
+
+**Signal**: "I've explained this 3+ times in different conversations"
+
+### 2. Gather
+
+Collect 3-5 concrete examples of how you've used this knowledge:
+
+- Save conversation snippets showing the repeated context
+- Document the specific questions or tasks that triggered the need
+- Note the exact information you provided each time
+- Identify common patterns across usage
+
+**Output**: A collection of real usage examples
+
+### 3. Plan
+
+Decide information hierarchy:
+
+**SKILL.md (Level 2)** - Core patterns only:
+
+- What the skill does
+- When to use it
+- Essential structure/commands
+- Links to references
+
+**references/ (Level 3)** - Detailed docs:
+
+- Complete API documentation
+- Detailed examples and tutorials
+- Background and theory
+- Edge cases and troubleshooting
+
+**scripts/ (Level 3)** - Deterministic operations:
+
+- Validation logic
+- Code generation
+- File transformations
+- Data processing
+
+**assets/ (Level 3)** - Static resources:
+
+- Templates
+- Configuration files
+- Images and diagrams
+
+### 4. Structure
+
+Create the directory structure:
+
+```bash
+mkdir -p .claude/skills/my-skill/{references,scripts,assets}
+touch .claude/skills/my-skill/SKILL.md
+```
+
+### 5. Write
+
+#### Write Description First
+
+The description is critical for skill discovery. Format:
+
+```
+[Domain/Context] [operations/capabilities]. Use when [trigger scenarios].
+```
+
+Examples:
+
+- ✅ "PostgreSQL schema and query patterns. Use when designing
+  databases, writing queries, or optimizing performance."
+- ✅ "Next.js 14 App Router conventions. Use when building Next.js
+  apps, configuring routes, or implementing server components."
+- ❌ "A skill for databases" (too vague)
+- ❌ "This skill helps you work with PostgreSQL databases" (second
+  person)
+
+Target: <200 chars for optimal Level 1 efficiency
+
+#### Write SKILL.md Body
+
+Structure:
+
+1. **Brief intro** (1-2 lines) - What this skill provides
+2. **When to use** (3-5 bullets) - Triggering scenarios
+3. **Core patterns** (3-5 sections) - Essential knowledge
+4. **Links to references** - Point to detailed docs
+
+Guidelines:
+
+- Use imperative voice ("Use X for Y", not "You should use X")
+- Provide concrete examples, not abstract concepts
+- Keep it scannable with clear headings
+- Target ~50 lines, max ~150 lines
+- Link liberally to references/
+
+#### Write References
+
+No size limits - be as detailed as needed:
+
+- Use descriptive filenames (api-endpoints.md, not reference.md)
+- Structure with clear headings
+- Include code examples
+- Cover edge cases
+- Provide context and rationale
+
+### 6. Enhance
+
+Add progressive enhancements:
+
+**Scripts** - When operations are:
+
+- Deterministic (same input = same output)
+- Complex (would require Claude to generate code)
+- Reusable (used frequently)
+
+Examples: validators, code generators, formatters
+
+**Assets** - When you need:
+
+- Templates (boilerplate code, config files)
+- Static files (images, data files)
+- Resources that shouldn't be loaded into context
+
+### 7. Iterate
+
+Test and refine:
+
+**Testing**:
+
+- Start a new conversation
+- Trigger the skill naturally (don't force it)
+- Observe if Claude loads it appropriately
+- Check if the content is helpful and sufficient
+
+**Refining**:
+
+- If skill loads too often → Make description more specific
+- If skill never loads → Add trigger keywords to description
+- If Claude asks for info that's in references → Add links in SKILL.md
+- If SKILL.md feels bloated → Move content to references
+- If you're repeating the same complex operation → Create a script
+
+**Iteration Cycle**:
+
+1. Use skill in real conversations
+2. Note friction points and gaps
+3. Refactor structure and content
+4. Test again
+
+## Common Pitfalls
+
+**Starting Too Big**
+
+- ❌ Writing 500 lines before testing
+- ✅ Start with 30-line SKILL.md, iterate
+
+**Generic Descriptions**
+
+- ❌ "Helps with coding tasks"
+- ✅ "React hooks patterns and performance optimization. Use when
+  building React components or debugging re-renders."
+
+**Bloated SKILL.md**
+
+- ❌ Including complete API docs in SKILL.md
+- ✅ Core patterns in SKILL.md, full docs in references/
+
+**Missing Triggers**
+
+- ❌ Description with no "Use when..." clause
+- ✅ Clear triggering scenarios in description
+
+**Second Person Voice**
+
+- ❌ "You should use this pattern when you need..."
+- ✅ "Use this pattern when..."
+
+## Success Criteria
+
+A well-designed skill:
+
+- ✅ Loads automatically when relevant (no manual triggering)
+- ✅ Provides exactly the context needed (not too much, not too
+  little)
+- ✅ Improves with each conversation (you notice missing pieces)
+- ✅ Saves you time (no more re-explaining the same concepts)
+
+## Tips
+
+- **Start minimal**: Better to add than to remove
+- **Test early**: Don't perfect in isolation
+- **Use real examples**: Concrete beats abstract
+- **Trust progressive disclosure**: Claude will ask for references
+  when needed
+- **Iterate based on usage**: Let real conversations drive refinement

package/dist/skills/skill-creator/references/skill-examples.md

@@ -396,7 +396,7 @@ Before considering a skill "done":
 - [ ] Detailed docs in references/
 - [ ] Scripts for repeated code
 - [ ] Assets for templates
-- [ ] Validated with `npx claude-skills validate`
+- [ ] Validated with `npx claude-skills-cli validate`
 - [ ] Tested in real conversations
 - [ ] No TODO placeholders
 - [ ] Imperative voice throughout

package/dist/validators/alignment-validator.js

@@ -0,0 +1,54 @@
+/**
+ * Alignment validation - checks description and content alignment
+ */
+import { extract_keywords } from './text-analysis.js';
+/**
+ * Analyze description and content alignment
+ */
+export function analyze_alignment(description, body) {
+    const desc_keywords = extract_keywords(description);
+    const content_keywords = extract_keywords(body);
+    const overlap = desc_keywords.filter((k) => content_keywords.includes(k));
+    const desc_only = desc_keywords.filter((k) => !content_keywords.includes(k));
+    const content_only = content_keywords
+        .filter((k) => !desc_keywords.includes(k))
+        .slice(0, 20);
+    const overlap_ratio = desc_keywords.length > 0
+        ? overlap.length / desc_keywords.length
+        : 0;
+    let severity = 'good';
+    let explanation = 'Description aligns well with content';
+    if (overlap_ratio < 0.2 && desc_keywords.length > 5) {
+        severity = 'critical';
+        explanation = `Very low keyword overlap (${Math.round(overlap_ratio * 100)}%). Description may not match skill content.`;
+    }
+    else if (overlap_ratio < 0.3 && desc_keywords.length > 5) {
+        severity = 'moderate';
+        explanation = `Low keyword overlap (${Math.round(overlap_ratio * 100)}%). Description may not accurately reflect skill content.`;
+    }
+    const keywords = {
+        description_keywords: desc_keywords,
+        content_keywords: content_keywords.slice(0, 30),
+        overlap,
+        description_only: desc_only,
+        content_only,
+    };
+    const alignment = {
+        severity,
+        description_focus: desc_keywords.slice(0, 10),
+        content_focus: content_keywords.slice(0, 10),
+        matches: overlap,
+        mismatches: desc_only,
+        explanation,
+    };
+    const warnings = [];
+    if (overlap_ratio < 0.3 && desc_keywords.length > 5) {
+        warnings.push({
+            type: 'low_overlap',
+            message: `Low keyword overlap between description and content (${Math.round(overlap_ratio * 100)}%)\n` +
+                `  → Description may not accurately reflect skill content`,
+        });
+    }
+    return { keywords, alignment, warnings };
+}
+//# sourceMappingURL=alignment-validator.js.map

package/dist/validators/alignment-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alignment-validator.js","sourceRoot":"","sources":["../../src/validators/alignment-validator.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AActD;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAChC,WAAmB,EACnB,IAAY;IAEZ,MAAM,aAAa,GAAG,gBAAgB,CAAC,WAAW,CAAC,CAAC;IACpD,MAAM,gBAAgB,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;IAEhD,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAC1C,gBAAgB,CAAC,QAAQ,CAAC,CAAC,CAAC,CAC5B,CAAC;IACF,MAAM,SAAS,GAAG,aAAa,CAAC,MAAM,CACrC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,gBAAgB,CAAC,QAAQ,CAAC,CAAC,CAAC,CACpC,CAAC;IACF,MAAM,YAAY,GAAG,gBAAgB;SACnC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;SACzC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAEf,MAAM,aAAa,GAClB,aAAa,CAAC,MAAM,GAAG,CAAC;QACvB,CAAC,CAAC,OAAO,CAAC,MAAM,GAAG,aAAa,CAAC,MAAM;QACvC,CAAC,CAAC,CAAC,CAAC;IAEN,IAAI,QAAQ,GAAqC,MAAM,CAAC;IACxD,IAAI,WAAW,GAAG,sCAAsC,CAAC;IAEzD,IAAI,aAAa,GAAG,GAAG,IAAI,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrD,QAAQ,GAAG,UAAU,CAAC;QACtB,WAAW,GAAG,6BAA6B,IAAI,CAAC,KAAK,CAAC,aAAa,GAAG,GAAG,CAAC,8CAA8C,CAAC;IAC1H,CAAC;SAAM,IAAI,aAAa,GAAG,GAAG,IAAI,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5D,QAAQ,GAAG,UAAU,CAAC;QACtB,WAAW,GAAG,wBAAwB,IAAI,CAAC,KAAK,CAAC,aAAa,GAAG,GAAG,CAAC,2DAA2D,CAAC;IAClI,CAAC;IAED,MAAM,QAAQ,GAAoB;QACjC,oBAAoB,EAAE,aAAa;QACnC,gBAAgB,EAAE,gBAAgB,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC;QAC/C,OAAO;QACP,gBAAgB,EAAE,SAAS;QAC3B,YAAY;KACZ,CAAC;IAEF,MAAM,SAAS,GAAsB;QACpC,QAAQ;QACR,iBAAiB,EAAE,aAAa,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC;QAC7C,aAAa,EAAE,gBAAgB,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC;QAC5C,OAAO,EAAE,OAAO;QAChB,UAAU,EAAE,SAAS;QACrB,WAAW;KACX,CAAC;IAEF,MAAM,QAAQ,GAAuB,EAAE,CAAC;IAExC,IAAI,aAAa,GAAG,GAAG,IAAI,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrD,QAAQ,CAAC,IAAI,CAAC;YACb,IAAI,EAAE,aAAa;YACnB,OAAO,EACN,wDAAwD,IAAI,CAAC,KAAK,CAAC,aAAa,GAAG,GAAG,CAAC,MAAM;gBAC7F,0DAA0D;SAC3D,CAAC,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC;AAC1C,CAAC"}

package/dist/validators/content-validator.js

@@ -0,0 +1,144 @@
+/**
+ * Content validation (Level 2 progressive disclosure)
+ */
+import { count_words, estimate_tokens, strip_html_comments, } from './text-analysis.js';
+// Progressive disclosure limits (enforced as hard limits)
+const MAX_WORDS = 1000; // Hard limit (was recommended)
+const RECOMMENDED_WORDS = 500; // Warning threshold
+/**
+ * Analyze content structure and patterns
+ */
+export function analyze_content_structure(body) {
+    // Count code blocks
+    const code_block_matches = body.match(/```[\s\S]*?```/g);
+    const code_blocks = code_block_matches
+        ? code_block_matches.length
+        : 0;
+    // Count markdown sections (headings)
+    const heading_matches = body.match(/^#{1,6}\s/gm);
+    const sections = heading_matches ? heading_matches.length : 0;
+    // Count long paragraphs (>100 words)
+    const paragraphs = body.split(/\n\n+/);
+    const long_paragraphs = paragraphs.filter((p) => {
+        const words = count_words(p);
+        return words > 100;
+    }).length;
+    return { code_blocks, sections, long_paragraphs };
+}
+/**
+ * Validate progressive disclosure (word count, token budget, and line count)
+ */
+export function validate_content(body) {
+    const word_count = count_words(body);
+    const estimated_tokens = estimate_tokens(word_count);
+    // Strip HTML comments before counting lines (progressive disclosure guidance shouldn't inflate count)
+    const body_without_comments = strip_html_comments(body);
+    const line_count = body_without_comments.trim().split('\n').length;
+    // Analyze content structure
+    const structure = analyze_content_structure(body);
+    const validation = {
+        stats: {
+            word_count,
+            estimated_tokens,
+            line_count,
+            ...structure,
+        },
+        warnings: [],
+        errors: [],
+    };
+    // Hard limit check (error) - enforced at 1000 words
+    if (word_count > MAX_WORDS) {
+        validation.errors.push({
+            type: 'word_count',
+            message: `SKILL.md body has ${word_count} words (MAX: ${MAX_WORDS})\n` +
+                `  → Move detailed content to references/ directory for Level 3 loading\n` +
+                `  → This is a hard limit - skills must be concise`,
+        });
+    }
+    // Warning threshold at 500 words
+    else if (word_count > RECOMMENDED_WORDS) {
+        validation.warnings.push({
+            type: 'word_count',
+            message: `SKILL.md body has ${word_count} words (recommended: <${RECOMMENDED_WORDS}, max: ${MAX_WORDS})\n` +
+                `  → Consider moving examples/docs to references/ for better token efficiency`,
+        });
+    }
+    // Line count validation (Level 2 progressive disclosure)
+    // Hard limit: 50 lines (enforced)
+    if (line_count > 50) {
+        validation.errors.push({
+            type: 'line_count',
+            message: `SKILL.md body is ${line_count} lines (MAX: 50 for Level 2 progressive disclosure)\n` +
+                `  → Move detailed content to references/ directory\n` +
+                `  → This is a hard limit - skills must be concise`,
+        });
+    }
+    else if (line_count > 40) {
+        validation.warnings.push({
+            type: 'line_count',
+            message: `SKILL.md body is ${line_count} lines (recommended: ~40, max: 50)\n` +
+                `  → Consider moving examples to references/ for Level 3 loading`,
+        });
+    }
+    // Content analysis warnings
+    // Code blocks: Recommend 1-2, warn at >3
+    if (structure.code_blocks > 3) {
+        validation.warnings.push({
+            type: 'code_blocks',
+            message: `SKILL.md contains ${structure.code_blocks} code examples (recommended: 1-2)\n` +
+                `  → Move additional examples to references/examples.md for Level 3 loading`,
+        });
+    }
+    // Long paragraphs
+    if (structure.long_paragraphs > 3) {
+        validation.warnings.push({
+            type: 'long_paragraphs',
+            message: `SKILL.md contains ${structure.long_paragraphs} lengthy paragraphs (>100 words)\n` +
+                `  → Consider moving detailed explanations to references/`,
+        });
+    }
+    // Sections: Recommend 3-5, warn at >8
+    if (structure.sections > 8) {
+        validation.warnings.push({
+            type: 'sections',
+            message: `SKILL.md contains ${structure.sections} sections (recommended: 3-5)\n` +
+                `  → Consider splitting into focused reference files`,
+        });
+    }
+    // Check for "Quick Start" section
+    if (!body.includes('## Quick Start') &&
+        !body.includes('## Quick start')) {
+        validation.warnings.push({
+            type: 'missing_quick_start',
+            message: `Missing "## Quick Start" section\n` +
+                `  → Add one minimal working example to help Claude get started quickly`,
+        });
+    }
+    // Check for references/ links when body is long
+    const has_references = body.includes('references/');
+    if (!has_references && line_count > 60) {
+        validation.warnings.push({
+            type: 'no_references',
+            message: `No references/ links found but SKILL.md is ${line_count} lines\n` +
+                `  → Consider splitting detailed content into reference files`,
+        });
+    }
+    // Check body content
+    if (body.trim().length < 100) {
+        validation.warnings.push({
+            type: 'short_body',
+            message: 'SKILL.md body is very short',
+        });
+    }
+    // Check for TODO placeholders
+    if (body.includes('TODO') ||
+        body.includes('[Add your') ||
+        body.includes('[Provide')) {
+        validation.warnings.push({
+            type: 'todo_placeholders',
+            message: 'SKILL.md contains TODO placeholders',
+        });
+    }
+    return validation;
+}
+//# sourceMappingURL=content-validator.js.map

package/dist/validators/content-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-validator.js","sourceRoot":"","sources":["../../src/validators/content-validator.ts"],"names":[],"mappings":"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"}

package/dist/validators/description-validator.js

@@ -0,0 +1,136 @@
+/**
+ * Description validation (Level 1 progressive disclosure)
+ */
+import { estimate_string_tokens, } from './text-analysis.js';
+/**
+ * Validate description length and quality
+ */
+export function validate_description_content(description) {
+    const desc_length = description.length;
+    const desc_tokens = estimate_string_tokens(description);
+    const validation = {
+        stats: {
+            description_length: desc_length,
+            description_tokens: desc_tokens,
+        },
+        warnings: [],
+        errors: [],
+    };
+    // Enforced limit: 300 chars (prevents Claude from bloating descriptions)
+    // Anthropic allows 1024, but that leads to verbose, inefficient descriptions
+    if (desc_length > 300) {
+        validation.errors.push({
+            type: 'length',
+            message: `Description is ${desc_length} characters (MAX: 300 for efficiency)\n` +
+                `  → Keep descriptions concise - quality over quantity`,
+        });
+    }
+    else if (desc_length > 200) {
+        validation.warnings.push({
+            type: 'length',
+            message: `Description is ${desc_length} characters (recommended: <200)\n` +
+                `  → Estimated ~${desc_tokens} tokens - consider shortening`,
+        });
+    }
+    // Check for trigger keywords
+    const lower_desc = description.toLowerCase();
+    const has_trigger = lower_desc.includes('use when') ||
+        lower_desc.includes('use for') ||
+        lower_desc.includes('use to');
+    if (!has_trigger) {
+        validation.warnings.push({
+            type: 'trigger',
+            message: `Description missing trigger keywords ('Use when...', 'Use for...', 'Use to...')\n` +
+                `  → Help Claude know when to activate this skill`,
+        });
+    }
+    // Check for list bloat (multiple commas indicating detailed lists)
+    // Only warn if BOTH long description AND many commas (allows concise technical lists)
+    const comma_count = (description.match(/,/g) || []).length;
+    if (desc_length > 150 && comma_count >= 5) {
+        validation.warnings.push({
+            type: 'list_bloat',
+            message: `Description contains long lists (${comma_count} commas, ${desc_length} chars)\n` +
+                `  → Move detailed lists to Level 2 (SKILL.md body) or Level 3 (references/)`,
+        });
+    }
+    // Short description check
+    if (desc_length < 20) {
+        validation.warnings.push({
+            type: 'short',
+            message: 'Description is very short (consider adding more detail)',
+        });
+    }
+    return validation;
+}
+/**
+ * Analyze trigger phrase in description
+ */
+export function analyze_trigger_phrase(description) {
+    const lower = description.toLowerCase();
+    const has_trigger = lower.includes('use when') ||
+        lower.includes('use for') ||
+        lower.includes('use to');
+    let trigger_phrase = null;
+    let trigger_type = 'missing';
+    if (has_trigger) {
+        const match = description.match(/(use when|use for|use to)[^.!?]*/i);
+        if (match) {
+            trigger_phrase = match[0].trim();
+            trigger_type =
+                trigger_phrase.length > 50 ? 'specific' : 'generic';
+        }
+    }
+    return {
+        has_explicit_trigger: has_trigger,
+        trigger_phrase,
+        trigger_type,
+    };
+}
+/**
+ * Analyze user phrasing style
+ */
+export function analyze_user_phrasing(description) {
+    const issues = [];
+    const warnings = [];
+    // Check for first person
+    const is_third_person = !/\b(I can|I will|I help|my|me)\b/i.test(description);
+    const first_person_patterns = /\b(I can|I will|I help|my|me)\b/i;
+    if (first_person_patterns.test(description)) {
+        const match = description.match(first_person_patterns);
+        if (match) {
+            warnings.push({
+                type: 'first_person',
+                message: `Description uses first person: "${match[0]}"\n` +
+                    `  → Prefer third person for clarity (not required but recommended)`,
+            });
+        }
+    }
+    // Check for vague terms
+    const vague_patterns = /\b(helper|utility|tool|various|several|some)\b/i;
+    if (vague_patterns.test(description)) {
+        const match = description.match(vague_patterns);
+        if (match) {
+            warnings.push({
+                type: 'vague',
+                message: `Description contains vague term: "${match[0]}"\n` +
+                    `  → Be specific about what the skill does`,
+            });
+        }
+    }
+    // Check for gerund form (verbs ending in -ing)
+    const uses_gerund = /\b\w+ing\b/i.test(description);
+    // Check for action-oriented (starts with action verbs)
+    const action_verbs = /^(create|build|design|analyze|test|validate|generate|process|manage|execute|handle|provide)/i;
+    const is_action_oriented = action_verbs.test(description.trim());
+    const analysis = {
+        style_checks: {
+            is_third_person,
+            uses_gerund_form: uses_gerund,
+            is_action_oriented,
+        },
+        issues,
+    };
+    return { analysis, warnings };
+}
+//# sourceMappingURL=description-validator.js.map

package/dist/validators/description-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"description-validator.js","sourceRoot":"","sources":["../../src/validators/description-validator.ts"],"names":[],"mappings":"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"}