claude-skills-cli 0.0.2 → 0.0.4

package/README.md

@@ -1,455 +1,270 @@
 # claude-skills-cli
 
-TypeScript CLI toolkit for creating, validating, and packaging Claude skills.
-
-**Status:** 🚧 In Development - See implementation plan below
-
----
+TypeScript CLI toolkit for creating, validating, and packaging Claude Agent Skills with **progressive disclosure validation**.
 
 ## What This Is
 
-A portable command-line tool for managing Claude Agent Skills, inspired by tools like `create-next-app` and `create-vite`. Install once, use anywhere:
+A command-line tool for managing Claude Agent Skills. It enforces the 3-level progressive disclosure system from [Anthropic's Skills documentation](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview), ensuring skills are token-efficient and scannable.
 
 ```bash
-pnpx claude-skills-cli init --name my-skill --description "..."
-pnpx claude-skills-cli validate .claude/skills/my-skill
-pnpx claude-skills-cli package .claude/skills/my-skill
+npx claude-skills init my-skill
+npx claude-skills validate .claude/skills/my-skill
+npx claude-skills validate .claude/skills/my-skill --strict
+npx claude-skills package .claude/skills/my-skill
 ```
 
-This replaces the Python scripts that were previously in project `.claude/scripts/` directories.
-
----
-
-## Repository Structure (Planned)
+## Commands
 
-Following the **mcpick** pattern:
+### `init` - Create a new skill
 
-```
-claude-skills-cli/
-├── package.json                     # CLI package config
-├── tsconfig.json                    # TypeScript ES modules config
-├── README.md                        # This file
-├── .gitignore                       # Ignore node_modules, dist, etc.
-├── .prettierrc                      # Code formatting
-├── .changeset/                      # Version management
-│   ├── README.md
-│   └── config.json
-├── src/
-│   ├── index.ts                     # CLI entry (#!/usr/bin/env node)
-│   ├── types.ts                     # TypeScript type definitions
-│   ├── commands/
-│   │   ├── init.ts                  # Create new skill structure
-│   │   ├── validate.ts              # Validate skill format
-│   │   └── package.ts               # Package skill to zip
-│   ├── core/
-│   │   ├── templates.ts             # SKILL.md templates as strings
-│   │   └── validator.ts             # Validation logic (class-based)
-│   └── utils/
-│       ├── fs.ts                    # File system helpers
-│       └── output.ts                # Emoji/formatting (chalk)
-├── templates/                       # Copied from devhub-crm
-│   ├── SKILL-TEMPLATE.md
-│   └── skill-structure/
-│       ├── README.md
-│       ├── references/
-│       ├── scripts/
-│       └── assets/
-├── docs/                            # Copied from devhub-crm
-│   ├── SKILLS-ARCHITECTURE.md
-│   ├── SKILL-DEVELOPMENT.md
-│   └── SKILL-EXAMPLES.md
-└── skills/                          # Portable example skills
-    └── skill-creator/               # Meta-skill from devhub-crm
-        ├── SKILL.md
-        └── references/
+```bash
+claude-skills init my-skill
+claude-skills init my-skill --description "Brief description with trigger keywords"
 ```
 
----
+Creates a skill directory with:
 
-## Files to Move from devhub-crm
+- **SKILL.md** - Streamlined ~50 line template with progressive disclosure guidelines
+- **README.md** - Skill documentation
+- **references/** - Directory for Level 3 detailed documentation
+- **scripts/** - Directory for executable JavaScript/shell scripts
+- **assets/** - Directory for templates and resources
 
-The `.claude/` directory was copied wholesale, but needs reorganization:
+The generated SKILL.md template follows best practices:
 
-### ✅ Keep and Move to Root:
+- 1-2 code blocks maximum
+- Clear "Quick Start" section
+- Links to references/ for detailed content
+- Progressive disclosure comments inline
 
-```
-devhub-crm/.claude/docs/             → claude-skills-cli/docs/
-devhub-crm/.claude/templates/        → claude-skills-cli/templates/
-devhub-crm/.claude/skills/skill-creator/  → claude-skills-cli/skills/skill-creator/
+### `validate` - Validate skill structure
+
+```bash
+claude-skills validate .claude/skills/my-skill
+claude-skills validate .claude/skills/my-skill --strict
 ```
 
-### ✅ Convert to TypeScript:
+**Progressive Disclosure Validation** (3-Level System):
 
-```
-devhub-crm/.claude/scripts/init_skill.py      → src/commands/init.ts
-devhub-crm/.claude/scripts/validate_skill.py  → src/commands/validate.ts
-devhub-crm/.claude/scripts/package_skill.py   → src/commands/package.ts
-```
+| Level                      | Content           | Checks                                                                                                                                                                                                              |
+| -------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Level 1: Metadata**      | YAML frontmatter  | Description <200 chars (warn), <300 chars (error)<br>Trigger keywords present ("Use when/for/to")<br>No list bloat (>3 commas)                                                                                      |
+| **Level 2: SKILL.md Body** | Main instructions | Line count ~50 (warn >80, error >150)<br>Word count <1000 (warn), <5000 (error)<br>Code blocks ≤3 (recommend 1-2)<br>Sections ≤8 (recommend 3-5)<br>"Quick Start" section present<br>Links to references/ when long |
+| **Level 3: References**    | Bundled files     | Referenced files exist (error on broken links)<br>No empty directories                                                                                                                                              |
 
-### ❌ Delete (Not Needed):
+**Validation Output:**
+
+The validator displays a detailed progressive disclosure stats breakdown:
 
 ```
-devhub-crm/.claude/settings.local.json        # Project-specific
-devhub-crm/.claude/skills/database-patterns/  # Project-specific
-devhub-crm/.claude/TYPESCRIPT-CONVERSION-PROMPT.md  # Completed
-```
+📊 Progressive Disclosure Stats:
 
----
+  Level 1 (Metadata - Always Loaded):
+    Description: 156 chars, ~18 tokens ✅ Optimal
+    (Target: <200 chars, <30 tokens for Level 1 efficiency)
 
-## package.json Configuration
-
-```json
-{
-  "name": "claude-skills-cli",
-  "version": "0.0.1",
-  "description": "CLI toolkit for creating and managing Claude Agent Skills",
-  "type": "module",
-  "main": "./dist/index.js",
-  "bin": {
-    "claude-skills-cli": "./dist/index.js"
-  },
-  "engines": {
-    "node": ">=22.0.0"
-  },
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "start": "node ./dist/index.js",
-    "format": "prettier --write .",
-    "format:check": "prettier --check .",
-    "changeset": "changeset",
-    "version": "changeset version",
-    "release": "pnpm run build && changeset publish"
-  },
-  "keywords": ["claude", "skills", "cli", "agent", "anthropic", "claude-code"],
-  "author": "Scott Spence",
-  "license": "MIT",
-  "dependencies": {
-    "@clack/prompts": "^0.11.0",
-    "chalk": "^5.3.0",
-    "archiver": "^7.0.0"
-  },
-  "devDependencies": {
-    "@changesets/cli": "^2.29.7",
-    "@types/node": "^24.7.0",
-    "@types/archiver": "^6.0.0",
-    "prettier": "^3.6.2",
-    "typescript": "^5.9.3"
-  }
-}
-```
+  Level 2 (SKILL.md Body - Loaded when triggered):
+    Lines: 48 (target: ~50, max: ~150) ✅ Excellent
+    Words: 342 (recommended: <1000, max: <5000) ✅ Excellent
+    Est. tokens: ~445 (budget: <6500) within budget
+    Code blocks: 1 ✅
+    Sections: 5 ✅
 
----
+  Level 3+ (References - Loaded as needed):
+    Use references/ directory for detailed docs (unlimited size)
 
-## tsconfig.json Configuration
-
-```json
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "nodenext",
-    "moduleResolution": "nodenext",
-    "strict": true,
-    "outDir": "./dist",
-    "sourceMap": true,
-    "esModuleInterop": true,
-    "allowSyntheticDefaultImports": true,
-    "skipLibCheck": true
-  },
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist"]
-}
+  Overall Assessment:
+    ✅ Excellent progressive disclosure!
 ```
 
----
+**Exit codes:**
 
-## Dependencies Explained
+- 0 = Valid (or valid with warnings)
+- 1 = Validation errors
+- 1 with `--strict` = Warnings treated as errors
 
-### Runtime Dependencies:
+### `package` - Create uploadable zip
 
-- **@clack/prompts** - Interactive CLI prompts (like mcpick uses)
-- **chalk** - Terminal string styling and colors
-- **archiver** - Create zip files (replaces Python's zipfile)
+```bash
+claude-skills package .claude/skills/my-skill
+claude-skills package .claude/skills/my-skill --output dist/
+claude-skills package .claude/skills/my-skill --skip-validation
+```
 
-### Dev Dependencies:
+Creates a zip file ready to upload to Claude.ai, excluding:
 
-- **@changesets/cli** - Version management and changelog
-- **@types/node** - TypeScript types for Node.js
-- **@types/archiver** - TypeScript types for archiver
-- **prettier** - Code formatting
-- **typescript** - TypeScript compiler
+- Hidden files (.\*)
+- Build artifacts (dist/, build/)
+- Swap files (~, .swp)
 
----
+Runs validation first unless `--skip-validation` is specified.
 
-## CLI Interface (Must Match Python Version)
+## The Progressive Disclosure System
 
-### Command: init
+Claude Skills use a 3-level loading system to optimize token usage:
 
-```bash
-claude-skills init --name my-skill --description "What it does and when to use it"
-claude-skills init --path /custom/path/my-skill
-```
+| Level  | File                           | Context Window             | Token Budget |
+| ------ | ------------------------------ | -------------------------- | ------------ |
+| **1**  | SKILL.md Metadata (YAML)       | Always loaded              | ~100 tokens  |
+| **2**  | SKILL.md Body (Markdown)       | Loaded when skill triggers | <5k tokens   |
+| **3+** | references/, scripts/, assets/ | Loaded as-needed by Claude | Unlimited    |
 
-**Creates:**
+### Why This Matters
 
-- SKILL.md with YAML frontmatter
-- README.md
-- references/detailed-guide.md
-- scripts/example.py (executable)
-- assets/ directory
+- **Level 1** is always in Claude's context, so keep descriptions <200 chars
+- **Level 2** loads when Claude thinks the skill is relevant, so keep it scannable (~50 lines)
+- **Level 3** loads on-demand, so move detailed docs, examples, and schemas there
 
-**Output:**
+The validator enforces these constraints to ensure skills are token-efficient.
 
-```
-✅ Skill created at: .claude/skills/my-skill
+## Installation
 
-Next steps:
-1. Edit .claude/skills/my-skill/SKILL.md with your skill instructions
-2. Add detailed documentation to references/
-3. Add executable scripts to scripts/
-4. Remove example files you don't need
+### As a project dependency:
 
-Validate with: claude-skills validate .claude/skills/my-skill
+```bash
+npm install claude-skills-cli --save-dev
 ```
 
-### Command: validate
+### Global installation:
 
 ```bash
-claude-skills validate .claude/skills/my-skill
-claude-skills validate .claude/skills/my-skill --strict
+npm install -g claude-skills-cli
 ```
 
-**Checks:**
-
-- SKILL.md exists
-- YAML frontmatter format
-- Required fields (name, description)
-- Name format (kebab-case, max 64 chars)
-- Description length (max 1024 chars)
-- References mentioned in SKILL.md
-- Scripts are executable
-- No TODO placeholders
-
-**Output:**
+### Using npx (no install):
 
+```bash
+npx claude-skills-cli init my-skill
 ```
-📋 Validating skill: my-skill
-============================================================
 
-⚠️  Warnings:
-  ⚠️  Reference file 'schema.md' not mentioned in SKILL.md
+## Example Workflow
 
-✅ Skill is valid (with warnings)
-```
+```bash
+# 1. Create a new skill
+npx claude-skills init database-queries \
+  --description "SQLite queries for contacts and companies. Use when querying the database."
 
-**Exit codes:**
+# 2. Edit the generated SKILL.md
+# - Keep it under 50 lines
+# - Use 1 minimal code example in Quick Start
+# - Link to references/ for detailed docs
 
-- 0 = success
-- 1 = validation failed
-- 1 with --strict = warnings treated as errors
+# 3. Validate before using
+npx claude-skills validate .claude/skills/database-queries
 
-### Command: package
+# 4. Fix any warnings (or use --strict to enforce)
+npx claude-skills validate .claude/skills/database-queries --strict
 
-```bash
-claude-skills package .claude/skills/my-skill
-claude-skills package .claude/skills/my-skill --output dist/
-claude-skills package .claude/skills/my-skill --skip-validation
+# 5. Package for sharing
+npx claude-skills package .claude/skills/database-queries
 ```
 
-**Creates:**
+## Validation Best Practices
 
-- Zip file with skill contents
-- Excludes hidden files, .pyc, **pycache**, etc.
-- Runs validation first (unless --skip-validation)
+### ✅ Good Skill (Passes Validation)
 
-**Output:**
+````markdown
+---
+name: api-client
+description: REST API client for our service. Use when making HTTP requests to api.example.com.
+---
 
-```
-🔍 Validating skill...
-✅ Skill is valid!
+# API Client
 
-📦 Packaging skill: my-skill
-  + my-skill/SKILL.md
-  + my-skill/README.md
-  + my-skill/references/detailed-guide.md
+## Quick Start
 
-✅ Skill packaged successfully!
-   File: dist/my-skill.zip
-   Size: 12.3 KB
+```typescript
+import { apiClient } from '$lib/api';
 
-📤 Upload to Claude.ai: Settings > Features > Skills > Upload
+const response = await apiClient.get('/users');
 ```
+````
 
----
+## Core Principles
 
-## Implementation Roadmap
-
-### Phase 1: Setup (You're here!)
-
-- [x] Create claude-skills-cli repo
-- [x] Copy .claude/ from devhub-crm
-- [ ] Create package.json
-- [ ] Create tsconfig.json
-- [ ] Setup .gitignore, .prettierrc
-- [ ] Install dependencies: `pnpm install`
-
-### Phase 2: Reorganize Files
-
-- [ ] Move `docs/` to root
-- [ ] Move `templates/` to root
-- [ ] Move `skills/skill-creator/` to root
-- [ ] Delete `.claude/settings.local.json`
-- [ ] Delete `.claude/skills/database-patterns/`
-
-### Phase 3: Convert Python → TypeScript
-
-#### init.ts (from init_skill.py)
-
-- [ ] Import types, fs, path, chalk
-- [ ] Create template strings (SKILL.md, README.md, etc.)
-- [ ] Implement createSkill() function
-  - Use fs.mkdirSync(path, { recursive: true })
-  - Use fs.writeFileSync()
-  - Use fs.chmodSync(scriptPath, 0o755) for executable
-- [ ] Use @clack/prompts for interactive mode (optional)
-- [ ] Match Python output format exactly (emoji, messages)
-
-#### validate.ts (from validate_skill.py)
-
-- [ ] Create SkillValidator class
-  - errors: string[]
-  - warnings: string[]
-- [ ] Implement validation methods:
-  - validateDirectory()
-  - validateSkillMd() - parse YAML frontmatter
-  - validateReferences()
-  - validateScripts() - check executable with fs.statSync()
-  - validateAssets()
-- [ ] Use chalk for colored output
-- [ ] Match Python emoji output exactly
-- [ ] Support --strict flag
-
-#### package.ts (from package_skill.py)
-
-- [ ] Import archiver for zip creation
-- [ ] Call validate.ts first (child_process.spawnSync)
-- [ ] Create zip with exclusions:
-  - Hidden files (starts with .)
-  - .pyc, .pyo, .swp, ~
-  - **pycache**, .DS_Store
-- [ ] Report file size in KB
-- [ ] Match Python output format
-
-### Phase 4: CLI Entry Point
-
-#### index.ts
-
-- [ ] Add shebang: `#!/usr/bin/env node`
-- [ ] Import @clack/prompts
-- [ ] Import commands (init, validate, package)
-- [ ] Create interactive menu (like mcpick)
-  - "Create new skill"
-  - "Validate skill"
-  - "Package skill"
-  - "Exit"
-- [ ] Handle command-line arguments (for non-interactive)
-- [ ] Error handling with try/catch
-
-### Phase 5: Testing
-
-- [ ] Build: `pnpm build`
-- [ ] Test init: `node dist/index.js init --name test-skill`
-- [ ] Test validate: `node dist/index.js validate skills/skill-creator`
-- [ ] Test package: `node dist/index.js package skills/skill-creator`
-- [ ] Verify output matches Python version
-
-### Phase 6: Publishing
-
-- [ ] Setup .changeset config
-- [ ] Add initial changeset
-- [ ] Test with `pnpx` locally
-- [ ] Publish to npm: `pnpm release`
-- [ ] Update devhub-crm to use `pnpx claude-skills-cli`
+- Use typed requests and responses
+- Handle errors with try/catch
+- Include authentication headers
 
----
+## Reference Files
 
-## Design Decisions
+- [references/endpoints.md](references/endpoints.md) - Complete API reference
+- [references/examples.md](references/examples.md) - Request/response examples
 
-### Why @clack/prompts instead of commander?
+````
 
-- mcpick uses @clack/prompts for beautiful interactive menus
-- Provides better UX than raw commander arguments
-- Still support non-interactive mode with args
+**Why it's good:**
+- Description: 81 chars with trigger keywords ✅
+- Lines: ~25 lines ✅
+- Code blocks: 1 ✅
+- Has Quick Start section ✅
+- Links to references/ for details ✅
 
-### Why archiver instead of node:zlib?
+### ❌ Bad Skill (Fails Validation)
 
-- archiver is battle-tested for creating zips
-- Handles file permissions, directory structure
-- Direct replacement for Python's zipfile
+```markdown
+---
+name: api-client
+description: Comprehensive REST API client for making HTTP requests to our service endpoints including GET, POST, PUT, DELETE, PATCH operations with authentication, error handling, retries, rate limiting, and response caching for users, posts, comments, tags, categories, and settings endpoints.
+---
 
-### Why chalk for colors?
+# API Client
 
-- Match Python's emoji output (✅ ❌ ⚠️)
-- Better terminal color support
-- Widely used, stable
+[186 lines of detailed documentation with 7 code blocks...]
+````
 
-### Why ES modules (type: "module")?
+**Problems:**
 
-- Modern Node.js best practice
-- Matches mcpick setup
-- Better tree-shaking, cleaner imports
+- Description: 287 chars, no trigger keywords ❌
+- Lines: 186 (max 150) ❌
+- Code blocks: 7 (recommend 1-2) ❌
+- No Quick Start section ❌
+- Should split into references/ ❌
 
----
+## Development
 
-## Testing Checklist
+```bash
+# Install dependencies
+npm install
 
-Before publishing v1.0.0:
+# Build TypeScript
+npm run build
 
-- [ ] All three commands work (init, validate, package)
-- [ ] Output matches Python version exactly
-- [ ] Exit codes match (0 = success, 1 = error)
-- [ ] Emoji indicators work (✅ ❌ ⚠️)
-- [ ] --strict mode works on validate
-- [ ] --skip-validation works on package
-- [ ] Created skills validate successfully
-- [ ] Packaged zips can be uploaded to Claude.ai
-- [ ] Works via `pnpx claude-skills-cli`
-- [ ] Works when installed globally
+# Run locally
+node dist/index.js validate path/to/skill
 
----
+# Format code
+npm run format
+
+# Type check
+npx tsc --noEmit
+```
 
 ## Resources
 
-### Official Anthropic Documentation:
+### Official Documentation
 
 - [Agent Skills Overview](https://www.anthropic.com/news/skills)
 - [Engineering Blog: Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)
 - [Claude Docs: Skills](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview)
-- [Anthropic Skills Repo](https://github.com/anthropics/skills)
+- [Anthropic Skills Repository](https://github.com/anthropics/skills)
 
-### Included Documentation:
+### Included Documentation
 
 - [docs/SKILLS-ARCHITECTURE.md](docs/SKILLS-ARCHITECTURE.md) - Progressive disclosure system
-- [docs/SKILL-DEVELOPMENT.md](docs/SKILL-DEVELOPMENT.md) - 6-step creation workflow
+- [docs/SKILL-DEVELOPMENT.md](docs/SKILL-DEVELOPMENT.md) - Skill creation workflow
 - [docs/SKILL-EXAMPLES.md](docs/SKILL-EXAMPLES.md) - Real-world examples
 
-### Reference Implementation:
+## License
 
-- [mcpick](https://github.com/spences10/mcpick) - Similar CLI structure to follow
+MIT © Scott Spence
 
----
+## Contributing
 
-## Notes for Next Chat Session
+Contributions welcome! This tool is designed to help Claude use skills efficiently. When proposing changes, consider:
 
-1. **Start with setup:** Create package.json and tsconfig.json first
-2. **Install deps:** `pnpm install` to get @clack/prompts, chalk, archiver
-3. **Reorganize files:** Move docs/, templates/, skills/ from .claude/ to root
-4. **Convert Python scripts one by one:** Start with init.ts (simplest), then validate.ts, then package.ts
-5. **Create index.ts:** Wire up commands with @clack/prompts menu
-6. **Test everything:** Build and run against skill-creator to verify
-
-**Key principle:** Match Python output and behavior EXACTLY. Users should not notice any difference except it's faster and more portable.
-
----
+1. **Token efficiency** - Does this help reduce token usage?
+2. **Ergonomics for Claude** - Is it easy for Claude to understand and use?
+3. **Progressive disclosure** - Does it enforce the 3-level system?
 
-**Ready to build!** 🚀
+See the feedback document at [CLI-FEEDBACK.md](CLI-FEEDBACK.md) for detailed validation requirements.