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

Ecosystem

Part of a connected suite of tools for Claude Code power users. These projects work together to give Claude Code persistent memory, better search, framework expertise, and self-improving skills.

Skills & Plugins

Create, share, and use Claude Code skills with reliable activation.

Project	What it does
claude-code-toolkit	Performance plugins, productivity skills, and ecosystem guide
svelte-skills-kit	Production-ready Svelte 5 & SvelteKit skills (90%+ verified accuracy)
claude-skills-cli	Create skills with progressive disclosure validation and 84% activation hooks
svelte-claude-skills	Original Svelte skills collection - now consolidated into svelte-skills-kit

MCP Servers & Tools

Extend Claude Code's capabilities with MCP servers for search, databases, and usage tracking.

Project	What it does
mcp-omnisearch	Unified search across Tavily, Brave, Kagi, Perplexity, and GitHub
mcp-sqlite-tools	Safe SQLite operations with schema inspection and query building
mcpick	Toggle MCP servers on/off without restarting - reduce context bloat
cclog	Sync Claude Code transcripts to SQLite for usage analytics and search