Skip to content
Back to search

claude-skills-cli

SkillWorks with Claude CodeGitHub

🤖 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.

Checked today

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/spences10--claude-skills-cli/badge.svg)](/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

i

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)

  1. # claude-skills-cli
  2. CLI for creating Claude Agent Skills with progressive disclosure
  3. validation. Built for Claude Code to use when humans ask it to create
  4. skills.
  5. ## For Humans Using Claude Code
  6. Tell Claude Code to create skills with specific package manager
  7. commands.
  8. Using npm:
  9. ```
  10. "Use npx -y claude-skills-cli to create a skill for my API client code"
  11. ```
  12. Using pnpm:
  13. ```
  14. "Use pnpx claude-skills-cli to create a skill for my API client code"
  15. ```
  16. This CLI enforces progressive disclosure so Claude doesn't write
  17. 500-line documentation files.
  18. ## Progressive Disclosure
  19. Skills load in 3 levels to optimize token usage:
  20. | Level | Content | When Loaded | Size Limit |
  21. | ----- | ------------------------------ | ------------------- | ---------- |
  22. | **1** | SKILL.md metadata (YAML) | Always in context | <200 chars |
  23. | **2** | SKILL.md body (Markdown) | When skill triggers | ~50 lines |
  24. | **3** | references/, scripts/, assets/ | As needed by Claude | Unlimited |
  25. This CLI enforces these constraints through validation, keeping skills
  26. lean and scannable.
  27. ## Commands
  28. ### init
  29. ```bash
  30. pnpx claude-skills-cli init --name my-skill --description "Brief description with trigger keywords"
  31. pnpx claude-skills-cli init --name my-skill --description "..." --with-examples
  32. ```
  33. Creates minimal skill scaffolding by default (SKILL.md, references/).
  34. Use `--with-examples` for example files.
  35. ### validate
  36. ```bash
  37. pnpx claude-skills-cli validate .claude/skills/my-skill
  38. pnpx claude-skills-cli validate .claude/skills/my-skill --lenient
  39. pnpx claude-skills-cli validate .claude/skills/my-skill --loose
  40. pnpx claude-skills-cli validate .claude/skills/my-skill --strict
  41. pnpx claude-skills-cli validate .claude/skills/my-skill --format json
  42. ```
  43. **Validation Modes:**
  44. | Mode | Max Lines | Use Case |
  45. | ----------- | --------- | ------------------------- |
  46. | (default) | 50 | Strict best practices |
  47. | `--lenient` | 150 | More flexibility |
  48. | `--loose` | 500 | Anthropic official limits |
  49. Comprehensive validation including:
  50. **Structure & Format:**
  51. - Name format (kebab-case) and directory matching
  52. - YAML frontmatter validity
  53. - Required fields presence
  54. **Level 1 (Metadata):**
  55. - Description length (<200 chars optimal, ~30 tokens)
  56. - Trigger phrase presence and specificity
  57. - User phrasing (third-person, action-oriented, gerunds)
  58. - Keyword richness and alignment with content
  59. **Level 2 (SKILL.md Body):**
  60. - Line count (50 max default, use `--lenient` for 150, `--loose`
  61. for 500)
  62. - Word count (<1000 max default)
  63. - Token estimates (<6500 budget)
  64. - Code blocks (1-2 optimal)
  65. - Sections (3-5 recommended)
  66. **Level 3 (References):**
  67. - Referenced files exist (no broken links)
  68. - Orphaned files detection
  69. - Nesting depth analysis
  70. - Progressive disclosure structure
  71. Use `--strict` to fail on warnings, `--lenient`/`--loose` for relaxed
  72. limits, `--format json` for programmatic use.
  73. ### doctor
  74. ```bash
  75. pnpx claude-skills-cli doctor .claude/skills/my-skill
  76. ```
  77. Automatically fixes common skill issues:
  78. - **Multi-line descriptions**: Adds `# prettier-ignore` and reflows
  79. description to single line
  80. - Ensures Claude Code can recognize the skill
  81. Run after formatting or if validation warns about multi-line
  82. descriptions.
  83. ### stats
  84. ```bash
  85. pnpx claude-skills-cli stats .claude/skills
  86. ```
  87. Shows overview of all skills with validation status, sizes, and
  88. quality ratings.
  89. ### package
  90. ```bash
  91. pnpx claude-skills-cli package .claude/skills/my-skill
  92. ```
  93. Creates uploadable zip for Claude.ai. Validates first unless
  94. `--skip-validation` specified.
  95. ### add-hook
  96. ```bash
  97. # Default: forced-eval hook (84% success), global scope
  98. pnpx claude-skills-cli add-hook
  99. # Specify hook type and scope
  100. pnpx claude-skills-cli add-hook --type llm-eval # LLM eval, global
  101. pnpx claude-skills-cli add-hook --type forced-eval --project # Forced eval, project
  102. pnpx claude-skills-cli add-hook --type simple-script --local # Simple script, local
  103. ```
  104. Adds skill activation hook to improve reliability. Generates hook
  105. scripts in `.claude/hooks/` and updates settings.json.
  106. **Hook Types (--type):**
  107. | Type | Success Rate | Description | Notes |
  108. | --------------- | ------------ | --------------------------- | ---------------------------- |
  109. | `forced-eval` | **84%** | Mandatory 3-step evaluation | Default, most consistent |
  110. | `llm-eval` | **80%** | Claude API pre-evaluation | Requires `ANTHROPIC_API_KEY` |
  111. | `simple-script` | 20% | Basic script file | For reference/debugging |
  112. | `simple-inline` | 20% | Echo in settings.json | Legacy, backwards compatible |
  113. **Scopes:**
  114. - **Global** (default): `~/.claude/settings.json` - All projects
  115. - **Project** (`--project`): `./.claude/settings.json` - Committed,
  116. team-shared
  117. - **Local** (`--local`): `./.claude/settings.local.json` - Gitignored,
  118. personal
  119. ## Skill Activation in Claude Code
  120. Skills are designed to auto-activate in Claude Code, but in practice,
  121. **[activation is unreliable without explicit hooks](https://scottspence.com/posts/claude-code-skills-dont-auto-activate)**.
  122. Despite documentation claiming skills are "model-invoked," Claude
  123. often bypasses skills unless directly instructed.
  124. ### The Solution: Activation Hooks
  125. Use the `add-hook` command to add skill activation instructions:
  126. ```bash
  127. # Recommended: forced-eval hook (84% success)
  128. pnpx claude-skills-cli add-hook
  129. ```
  130. After extensive testing (200+ prompts), two approaches emerged as
  131. significantly better than basic instructions:
  132. **Forced Eval Hook (84% success)** - Creates a mandatory 3-step
  133. process:
  134. 1. Explicitly evaluate each skill (YES/NO with reasoning)
  135. 2. Activate matching skills using `Skill()` tool
  136. 3. Only then proceed with implementation
  137. **LLM Eval Hook (80% success)** - Pre-evaluates skills via Claude API:
  138. - Costs ~$0.0004 per prompt (0.04 cents)
  139. - 10% cheaper and 17% faster than forced eval
  140. - Can miss certain prompt types but "smarter" when it works
  141. - Requires `ANTHROPIC_API_KEY` environment variable
  142. Both approaches are **massively better** than simple instructions (20%
  143. success rate).
  144. **Why explicit commitment matters:**
  145. Simple hooks like "If the prompt matches any skill keywords, use
  146. Skill(skill-name)" are passive suggestions that Claude often ignores.
  147. The forced-eval hook creates a commitment mechanism - Claude must
  148. write out its evaluation before proceeding, making it harder to skip
  149. activation.
  150. **Read more:**
  151. - [How to Make Claude Code Skills Activate Reliably](https://scottspence.com/posts/how-to-make-claude-code-skills-activate-reliably) -
  152. Full testing methodology and results
  153. - [Why Claude Code Skills Don't Auto-Activate](https://scottspence.com/posts/claude-code-skills-dont-auto-activate) -
  154. Original problem analysis
  155. ## Resources
  156. **Included docs:**
  157. - [docs/SKILLS-ARCHITECTURE.md](docs/SKILLS-ARCHITECTURE.md) -
  158. Progressive disclosure system
  159. - [docs/SKILL-DEVELOPMENT.md](docs/SKILL-DEVELOPMENT.md) - Skill
  160. creation workflow
  161. - [docs/SKILL-EXAMPLES.md](docs/SKILL-EXAMPLES.md) - Real-world
  162. examples
  163. - [.claude/skills/skill-creator/](.claude/skills/skill-creator/) -
  164. Skill for creating skills (validated example)
  165. **Official Anthropic docs:**
  166. - [Agent Skills Overview](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview)
  167. - [Engineering Blog](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)
  168. - [Skills Repository](https://github.com/anthropics/skills)
  169. ## Ecosystem
  170. Part of a connected suite of tools for Claude Code power users. These
  171. projects work together to give Claude Code persistent memory, better
  172. search, framework expertise, and self-improving skills.
  173. ### Skills & Plugins
  174. Create, share, and use Claude Code skills with reliable activation.
  175. | Project | What it does |
  176. | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
  177. | [claude-code-toolkit](https://github.com/spences10/claude-code-toolkit) | Performance plugins, productivity skills, and ecosystem guide |
  178. | [svelte-skills-kit](https://github.com/spences10/svelte-skills-kit) | Production-ready Svelte 5 & SvelteKit skills (90%+ verified accuracy) |
  179. | [claude-skills-cli](https://github.com/spences10/claude-skills-cli) | Create skills with progressive disclosure validation and 84% activation hooks |
  180. | [svelte-claude-skills](https://github.com/spences10/svelte-claude-skills) | Original Svelte skills collection - now consolidated into svelte-skills-kit |
  181. ### MCP Servers & Tools
  182. Extend Claude Code's capabilities with MCP servers for search,
  183. databases, and usage tracking.
  184. | Project | What it does |
  185. | ----------------------------------------------------------------- | --------------------------------------------------------------------- |
  186. | [mcp-omnisearch](https://github.com/spences10/mcp-omnisearch) | Unified search across Tavily, Brave, Kagi, Perplexity, and GitHub |
  187. | [mcp-sqlite-tools](https://github.com/spences10/mcp-sqlite-tools) | Safe SQLite operations with schema inspection and query building |
  188. | [mcpick](https://github.com/spences10/mcpick) | Toggle MCP servers on/off without restarting - reduce context bloat |
  189. | [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 in

Free to use. If it’s helped, pass it on.