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

$3

`bash
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.

$3

`bash
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.

$3

`bash
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.

$3

`bash
pnpx claude-skills-cli stats .claude/skills
`

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

$3

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

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

$3

`bash


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.

$3

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

`bash


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.

$3

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 |

$3

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 |