claude-skills-cli

CLI for creating Claude Agent Skills with progressive disclosure validation. Built for Claude Code to use when humans ask it to create skills.

For Humans Using Claude Code

Tell Claude Code to create skills with specific package manager commands.

Using npm:

"Use npx -y claude-skills-cli to create a skill for my API client code"

Using pnpm:

"Use pnpx claude-skills-cli to create a skill for my API client code"

This CLI enforces progressive disclosure so Claude doesn't write 500-line documentation files.

Progressive Disclosure

Skills load in 3 levels to optimize token usage:

| Level | Content | When Loaded | Size Limit | | ----- | ------------------------------ | ------------------- | ---------- | | 1 | SKILL.md metadata (YAML) | Always in context | <200 chars | | 2 | SKILL.md body (Markdown) | When skill triggers | ~50 lines | | 3 | references/, scripts/, assets/ | As needed by Claude | Unlimited |

This CLI enforces these constraints through validation, keeping skills lean and scannable.

Commands

init

pnpx claude-skills-cli init --name my-skill --description "Brief description with trigger keywords"
pnpx claude-skills-cli init --name my-skill --description "..." --with-examples

Creates minimal skill scaffolding by default (SKILL.md, references/). Use --with-examples for example files.

validate

pnpx claude-skills-cli validate .claude/skills/my-skill
pnpx claude-skills-cli validate .claude/skills/my-skill --lenient
pnpx claude-skills-cli validate .claude/skills/my-skill --loose
pnpx claude-skills-cli validate .claude/skills/my-skill --strict
pnpx claude-skills-cli validate .claude/skills/my-skill --format json

Validation Modes:

| Mode | Max Lines | Use Case | | ----------- | --------- | ------------------------- | | (default) | 50 | Strict best practices | | --lenient | 150 | More flexibility | | --loose | 500 | Anthropic official limits |

Comprehensive validation including:

Structure & Format:

• Name format (kebab-case) and directory matching
• YAML frontmatter validity
• Required fields presence

Level 1 (Metadata):

• Description length (<200 chars optimal, ~30 tokens)
• Trigger phrase presence and specificity
• User phrasing (third-person, action-oriented, gerunds)
• Keyword richness and alignment with content

Level 2 (SKILL.md Body):

• Line count (50 max default, use --lenient for 150, --loose for 500)
• Word count (<1000 max default)
• Token estimates (<6500 budget)
• Code blocks (1-2 optimal)
• Sections (3-5 recommended)

Level 3 (References):

• Referenced files exist (no broken links)
• Orphaned files detection
• Nesting depth analysis
• Progressive disclosure structure

Use --strict to fail on warnings, --lenient/--loose for relaxed limits, --format json for programmatic use.

doctor

pnpx claude-skills-cli doctor .claude/skills/my-skill

Automatically fixes common skill issues:

• Multi-line descriptions: Adds # prettier-ignore and reflows description to single line
• Ensures Claude Code can recognize the skill

Run after formatting or if validation warns about multi-line descriptions.

stats

pnpx claude-skills-cli stats .claude/skills

Shows overview of all skills with validation status, sizes, and quality ratings.

package

pnpx claude-skills-cli package .claude/skills/my-skill

Creates uploadable zip for Claude.ai. Validates first unless --skip-validation specified.

add-hook

# Default: forced-eval hook (84% success), global scope
pnpx claude-skills-cli add-hook

# Specify hook type and scope
pnpx claude-skills-cli add-hook --type llm-eval          # LLM eval, global
pnpx claude-skills-cli add-hook --type forced-eval --project   # Forced eval, project
pnpx claude-skills-cli add-hook --type simple-script --local   # Simple script, local

Adds skill activation hook to improve reliability. Generates hook scripts in .claude/hooks/ and updates settings.json.

Hook Types (--type):

| Type | Success Rate | Description | Notes | | --------------- | ------------ | --------------------------- | ---------------------------- | | forced-eval | 84% | Mandatory 3-step evaluation | Default, most consistent | | llm-eval | 80% | Claude API pre-evaluation | Requires ANTHROPIC_API_KEY | | simple-script | 20% | Basic script file | For reference/debugging | | simple-inline | 20% | Echo in settings.json | Legacy, backwards compatible |

Scopes:

• Global (default): ~/.claude/settings.json - All projects
• Project (--project): ./.claude/settings.json - Committed, team-shared
• Local (--local): ./.claude/settings.local.json - Gitignored, personal

Skill Activation in Claude Code

Skills are designed to auto-activate in Claude Code, but in practice, activation is unreliable without explicit hooks. Despite documentation claiming skills are "model-invoked," Claude often bypasses skills unless directly instructed.

The Solution: Activation Hooks

Use the add-hook command to add skill activation instructions:

# Recommended: forced-eval hook (84% success)
pnpx claude-skills-cli add-hook

After extensive testing (200+ prompts), two approaches emerged as significantly better than basic instructions:

Forced Eval Hook (84% success) - Creates a mandatory 3-step process:

1. Explicitly evaluate each skill (YES/NO with reasoning)
2. Activate matching skills using Skill() tool
3. Only then proceed with implementation

LLM Eval Hook (80% success) - Pre-evaluates skills via Claude API:

• Costs ~$0.0004 per prompt (0.04 cents)
• 10% cheaper and 17% faster than forced eval
• Can miss certain prompt types but "smarter" when it works
• Requires ANTHROPIC_API_KEY environment variable

Both approaches are massively better than simple instructions (20% success rate).

Why explicit commitment matters:

Simple hooks like "If the prompt matches any skill keywords, use Skill(skill-name)" are passive suggestions that Claude often ignores. The forced-eval hook creates a commitment mechanism - Claude must write out its evaluation before proceeding, making it harder to skip activation.

Read more:

• How to Make Claude Code Skills Activate Reliably - Full testing methodology and results
• Why Claude Code Skills Don't Auto-Activate - Original problem analysis

Resources

Included docs:

• docs/SKILLS-ARCHITECTURE.md - Progressive disclosure system
• docs/SKILL-DEVELOPMENT.md - Skill creation workflow
• docs/SKILL-EXAMPLES.md - Real-world examples
• .claude/skills/skill-creator/ - Skill for creating skills (validated example)

Official Anthropic docs:

• Agent Skills Overview
• Engineering Blog
• Skills Repository