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.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/spences10/claude-skills-cli with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/spences10/claude-skills-cli'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/spences10--claude-skills-cli)HTML
<a href="/listings/spences10--claude-skills-cli"><img src="/api/listings/spences10--claude-skills-cli/badge.svg" alt="findsafeskills safety rating" /></a>Install
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 266 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # 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
- ```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.
- ### validate
- ```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.
- ### doctor
- ```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.
- ### stats
- ```bash
- pnpx claude-skills-cli stats .claude/skills
- ```
- Shows overview of all skills with validation status, sizes, and
- quality ratings.
- ### package
- ```bash
- pnpx claude-skills-cli package .claude/skills/my-skill
- ```
- Creates uploadable zip for Claude.ai. Validates first unless
- `--skip-validation` specified.
- ### add-hook
- ```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](https://scottspence.com/posts/claude-code-skills-dont-auto-activate)**.
- 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:
- ```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](https://scottspence.com/posts/how-to-make-claude-code-skills-activate-reliably) -
- Full testing methodology and results
- - [Why Claude Code Skills Don't Auto-Activate](https://scottspence.com/posts/claude-code-skills-dont-auto-activate) -
- Original problem analysis
- ## Resources
- **Included docs:**
- - [docs/SKILLS-ARCHITECTURE.md](docs/SKILLS-ARCHITECTURE.md) -
- Progressive disclosure system
- - [docs/SKILL-DEVELOPMENT.md](docs/SKILL-DEVELOPMENT.md) - Skill
- creation workflow
- - [docs/SKILL-EXAMPLES.md](docs/SKILL-EXAMPLES.md) - Real-world
- examples
- - [.claude/skills/skill-creator/](.claude/skills/skill-creator/) -
- Skill for creating skills (validated example)
- **Official Anthropic docs:**
- - [Agent Skills Overview](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview)
- - [Engineering Blog](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)
- - [Skills Repository](https://github.com/anthropics/skills)
- ## 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](https://github.com/spences10/claude-code-toolkit) | Performance plugins, productivity skills, and ecosystem guide |
- | [svelte-skills-kit](https://github.com/spences10/svelte-skills-kit) | Production-ready Svelte 5 & SvelteKit skills (90%+ verified accuracy) |
- | [claude-skills-cli](https://github.com/spences10/claude-skills-cli) | Create skills with progressive disclosure validation and 84% activation hooks |
- | [svelte-claude-skills](https://github.com/spences10/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](https://github.com/spences10/mcp-omnisearch) | Unified search across Tavily, Brave, Kagi, Perplexity, and GitHub |
- | [mcp-sqlite-tools](https://github.com/spences10/mcp-sqlite-tools) | Safe SQLite operations with schema inspection and query building |
- | [mcpick](https://github.com/spences10/mcpick) | Toggle MCP servers on/off without restarting - reduce context bloat |
- | [cclog](https://github.com/spences10/cclog) | Sync Claude Code transcripts to SQLite for usage analytics and search |
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.