claude-skills-cli 0.0.5 → 0.0.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-skills-cli",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "description": "CLI toolkit for creating and managing Claude Agent Skills",
   "type": "module",
   "main": "./dist/index.js",
@@ -46,7 +46,7 @@
   },
   "scripts": {
     "build": "tsc",
-    "postbuild": "mkdir -p dist/skills && cp -r .claude/skills/skill-creator dist/skills/skill-creator",
+    "postbuild": "rm -rf dist/skills && cp -r .claude/skills dist/skills",
     "dev": "tsc --watch",
     "start": "node ./dist/index.js",
     "format": "prettier --write .",

package/dist/skills/skill-creator/skill-creator/SKILL.md

@@ -1,143 +0,0 @@
----
-name: skill-creator
-description:
-  Design and create Claude Skills using progressive disclosure
-  principles. Use when building new skills, planning skill
-  architecture, or writing skill content.
----
-
-# Skill Creator
-
-Principles and patterns for designing effective Claude Skills.
-
-## Quick Start
-
-Creating a minimal skill:
-
-1. Create directory: `.claude/skills/my-skill/`
-2. Create `SKILL.md` with frontmatter (name, description) and body
-3. Test in conversation
-4. Add references/ as content grows
-
-## When to Create a Skill
-
-Create a skill when you notice:
-
-- **Repeating context** across conversations (same schema, patterns,
-  rules)
-- **Domain expertise** needed repeatedly (API integration, framework
-  conventions)
-- **Project-specific knowledge** that Claude should know automatically
-
-Example: "I keep explaining this database schema" → Create a
-database-schema skill.
-
-## Skill Architecture
-
-Skills are directories with this structure:
-
-```
-my-skill/
-├── SKILL.md          # Required: Instructions + metadata
-├── references/       # Optional: Detailed documentation
-├── scripts/          # Optional: Executable operations
-└── assets/           # Optional: Templates, images, files
-```
-
-**SKILL.md** - Core instructions with YAML frontmatter (name,
-description) + markdown body
-
-**references/** - Detailed docs loaded only when Claude needs them
-(schemas, API docs, guides)
-
-**scripts/** - Deterministic operations Claude can execute without
-generating code (validation, generation)
-
-**assets/** - Files used directly in output without loading into
-context (templates, images)
-
-## Progressive Disclosure
-
-Skills load in 3 levels:
-
-**Level 1: Metadata** (~100 tokens, always loaded) - YAML frontmatter
-determines skill triggering
-
-**Level 2: Instructions** (<5k tokens, when triggered) - SKILL.md body
-with core patterns and links
-
-**Level 3: Resources** (unlimited, as needed) - references/ scripts/
-assets/ loaded only when used
-
-**Key principle**: Keep Levels 1 & 2 lean. Move details to Level 3.
-
-## Development Process
-
-1. **Recognize** - Notice repeated context or domain needs
-2. **Gather** - Collect 3-5 concrete examples of skill usage
-3. **Plan** - Decide what goes in SKILL.md vs references/ vs scripts/
-4. **Structure** - Create directory with SKILL.md and needed
-   subdirectories
-5. **Write** - Craft description, then SKILL.md body following
-   patterns
-6. **Enhance** - Add references, scripts, assets as needed
-7. **Iterate** - Test in conversations, refine based on actual usage
-
-## Writing Effective Content
-
-**Descriptions**: Include "Use when..." triggers, <200 chars optimal.
-Format: [Domain] + [Operations] + [Trigger keywords]
-
-**SKILL.md Body**: Target ~50 lines, max ~150. Structure: Quick
-Start + Core Patterns (3-5) + Links. Use imperative voice, concrete
-examples.
-
-**References**: Detailed docs with no size limit. Use descriptive
-filenames.
-
-## Common Patterns
-
-**Succeeds**: Domain expertise, concrete examples, keyword-rich
-descriptions, clear triggers, scripts for deterministic tasks
-
-**Fails**: Generic descriptions, bloated SKILL.md, second person
-voice, missing triggers, vague content
-
-See [skill-examples.md](references/skill-examples.md) for detailed
-patterns.
-
-## Implementation
-
-Skills can be created manually (mkdir, touch SKILL.md) or using tools
-like `claude-skills-cli`.
-
-For tool usage, see [cli-reference.md](references/cli-reference.md).
-
-## Reference Documentation
-
-For detailed guidance:
-
-- [anthropic-resources.md](references/anthropic-resources.md) -
-  Official Anthropic best practices
-- [writing-guide.md](references/writing-guide.md) - Voice, structure,
-  and code examples
-- [skill-examples.md](references/skill-examples.md) - Real-world
-  patterns and anti-patterns
-- [cli-reference.md](references/cli-reference.md) - Tool commands
-  (claude-skills-cli)
-- [cli-feedback.md](references/cli-feedback.md) - Real-world CLI usage
-  patterns
-
-## Notes
-
-- Skills are iterative - start minimal, refine through real usage
-- Description drives discovery - invest time in crafting it
-- Test in actual conversations to validate effectiveness
-- Progressive disclosure is key - resist urge to front-load everything
-
-<!--
-PROGRESSIVE DISCLOSURE:
-- This is Level 2 - principles and architecture only
-- Tool-specific details are in references/
-- Target: ~75 lines for optimal scannability
--->

package/dist/skills/skill-creator/skill-creator/references/anthropic-resources.md

@@ -1,504 +0,0 @@
-# Anthropic Resources - Official Guidance
-
-Key insights from Anthropic's official Agent Skills documentation.
-
-**Sources**:
-
-- [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)
-- [Product Announcement](https://www.anthropic.com/news/skills)
-
----
-
-## The Progressive Disclosure System
-
-**Core Design Principle**: Skills load information in stages as
-needed, rather than consuming context upfront.
-
-### The 3-Level Loading System
-
-| Level  | File                                           | Context Window             | Token Budget | When Loaded   |
-| ------ | ---------------------------------------------- | -------------------------- | ------------ | ------------- |
-| **1**  | SKILL.md Metadata (YAML)                       | Always loaded              | ~100 tokens  | At startup    |
-| **2**  | SKILL.md Body (Markdown)                       | Loaded when skill triggers | <5k tokens   | When relevant |
-| **3+** | Bundled files (references/, scripts/, assets/) | Loaded as needed by Claude | Unlimited\*  | On-demand     |
-
-\*No practical limit - files only load when accessed
-
-### Why This Matters
-
-> "Like a well-organized manual that starts with a table of contents,
-> then specific chapters, and finally a detailed appendix, skills let
-> Claude load information only as needed."
->
-> — Anthropic Engineering Blog
-
-**Benefits**:
-
-- You can install many skills without context penalty
-- Claude only knows each skill exists and when to use it (Level 1)
-- Detailed content doesn't consume tokens until needed
-- Effectively unbounded context per skill (via Level 3)
-
----
-
-## How Skills Work
-
-### Skill Discovery and Loading
-
-1. **Startup**: Claude pre-loads `name` and `description` of every
-   installed skill into system prompt
-2. **User request**: User makes a request that might need a skill
-3. **Skill matching**: Claude scans available skills to find relevant
-   matches
-4. **Skill loading**: If relevant, Claude reads SKILL.md from
-   filesystem via bash
-5. **On-demand access**: Claude reads additional files (references/,
-   scripts/) as needed
-
-### The Filesystem Architecture
-
-Skills run in a code execution environment where Claude has:
-
-- **Filesystem access**: Skills exist as directories on a virtual
-  machine
-- **Bash commands**: Claude uses bash to read files and execute
-  scripts
-- **Code execution**: Scripts run without loading code into context
-
-**How Claude accesses content**:
-
-```bash
-# Claude triggers skill by reading SKILL.md
-bash: cat pdf-skill/SKILL.md
-
-# Claude reads additional references if needed
-bash: cat pdf-skill/references/forms.md
-
-# Claude executes scripts (only output enters context)
-bash: node pdf-skill/scripts/validate_form.js
-```
-
-**Key insight**: Script code never enters the context window. Only the
-output does. This makes scripts far more token-efficient than
-generating equivalent code on the fly.
-
----
-
-## Official Best Practices
-
-From Anthropic's engineering team:
-
-### 1. Start with Evaluation
-
-> "Identify specific gaps in your agents' capabilities by running them
-> on representative tasks and observing where they struggle or require
-> additional context. Then build skills incrementally to address these
-> shortcomings."
-
-**Process**:
-
-- Use Claude on real tasks
-- Notice where it struggles
-- Create skills to fill gaps
-- Test and iterate
-
-### 2. Structure for Scale
-
-> "When the SKILL.md file becomes unwieldy, split its content into
-> separate files and reference them."
-
-**Guidelines**:
-
-- Keep SKILL.md under ~5k words
-- Split mutually exclusive contexts into separate files
-- Use code for both execution and documentation
-- Make it clear whether Claude should run or read scripts
-
-### 3. Think from Claude's Perspective
-
-> "Monitor how Claude uses your skill in real scenarios and iterate
-> based on observations: watch for unexpected trajectories or
-> overreliance on certain contexts."
-
-**Key areas**:
-
-- `name` and `description` drive skill triggering
-- Claude decides whether to use the skill based on metadata
-- Observe actual usage patterns, not assumed ones
-
-### 4. Iterate with Claude
-
-> "As you work on a task with Claude, ask Claude to capture its
-> successful approaches and common mistakes into reusable context and
-> code within a skill."
-
-**Workflow**:
-
-1. Work on task with Claude
-2. Notice successful patterns
-3. Ask Claude to capture them in skill
-4. Test and refine
-
----
-
-## Writing for Claude
-
-### Skills as "Onboarding Guides"
-
-> "Building a skill for an agent is like putting together an
-> onboarding guide for a new hire."
->
-> — Anthropic Engineering Blog
-
-**What this means**:
-
-- Focus on procedural knowledge ("how to do X")
-- Include workflows, not just facts
-- Provide examples of actual usage
-- Capture organizational context
-
-### Skills Transform General → Specialized Agents
-
-> "Skills extend Claude's capabilities by packaging your expertise
-> into composable resources for Claude, transforming general-purpose
-> agents into specialized agents that fit your needs."
-
-**Examples**:
-
-- General Claude + Database skill = Database specialist
-- General Claude + Auth skill = Security specialist
-- General Claude + UI skill = Frontend specialist
-
----
-
-## The Skill Anatomy
-
-### Required Structure
-
-Every skill must have:
-
-```
-skill-name/
-└── SKILL.md          # Required
-```
-
-SKILL.md must have:
-
-```markdown
----
-name: skill-name
-description: What it does and when to use it
----
-
-# Skill content...
-```
-
-### Frontmatter Limits
-
-| Field         | Limit           | Required |
-| ------------- | --------------- | -------- |
-| `name`        | 64 characters   | Yes      |
-| `description` | 1024 characters | Yes      |
-
-Only `name` and `description` are supported. No other YAML fields.
-
-### Optional Bundled Content
-
-```
-skill-name/
-├── SKILL.md                    # Level 2: Instructions
-├── references/                 # Level 3: Documentation
-│   ├── detailed-guide.md
-│   └── api-reference.md
-├── scripts/                    # Level 3: Executable code
-│   ├── validate.js
-│   └── generate.sh
-└── assets/                     # Level 3: Resources
-    ├── template.json
-    └── diagram.png
-```
-
----
-
-## Context Window Behavior
-
-### How the Context Window Changes
-
-From Anthropic's documentation:
-
-**Initial state**:
-
-```
-[System Prompt]
-[Skill 1 Metadata]
-[Skill 2 Metadata]
-[Skill N Metadata]
-[User Message]
-```
-
-**After skill triggers**:
-
-```
-[System Prompt]
-[Skill Metadata (all skills)]
-[User Message]
-[SKILL.md Body]              ← Loaded via bash
-[references/forms.md]        ← Loaded as needed
-```
-
-**Key point**: Metadata for ALL skills is always loaded. Only
-triggered skills load their SKILL.md body.
-
----
-
-## Progressive Disclosure in Practice
-
-### Example: PDF Skill
-
-**Level 1 (Always):**
-
-```yaml
-name: pdf
-description:
-  Extract text and tables from PDF files, fill forms, merge documents.
-  Use when working with PDF files.
-```
-
-~100 tokens
-
-**Level 2 (When triggered):**
-
-```markdown
-# PDF Processing
-
-## Quick Start
-
-Use pdfplumber to extract text...
-
-For form filling, see [forms.md](forms.md)
-```
-
-~3k tokens
-
-**Level 3 (As needed):**
-
-- `references/forms.md` - Form-filling guide (only if filling forms)
-- `scripts/extract_fields.js` - Executable script (runs, doesn't load)
-
-**Total token cost if NOT filling forms**: ~3,100 tokens (Level 1 +
-Level 2) **Total token cost if filling forms**: ~6,000 tokens (Level
-1 + Level 2 + forms.md)
-
----
-
-## Code Execution in Skills
-
-### Why Include Scripts
-
-> "Large language models excel at many tasks, but certain operations
-> are better suited for traditional code execution. For example,
-> sorting a list via token generation is far more expensive than
-> simply running a sorting algorithm."
->
-> — Anthropic Engineering Blog
-
-**When to use scripts**:
-
-- **Efficiency**: Operations that are cheaper to execute than generate
-- **Determinism**: Tasks requiring consistent, repeatable results
-- **Complexity**: Algorithms better suited to code than token
-  generation
-
-### Script Execution Model
-
-```bash
-# Claude runs script
-bash: node scripts/validate_form.js form.pdf
-
-# Output (only this enters context)
-✅ All form fields valid
-Found 12 fillable fields
-```
-
-**Context consumed**: ~20 tokens (just the output) **Alternative
-(Claude generates validation code)**: ~500 tokens
-
-**50x more efficient**
-
----
-
-## Security Considerations
-
-From Anthropic's security guidelines:
-
-### Trusted Sources Only
-
-> "We strongly recommend using Skills only from trusted sources: those
-> you created yourself or obtained from Anthropic."
-
-**Risk**: Malicious skills can:
-
-- Direct Claude to invoke tools in harmful ways
-- Execute code with unintended effects
-- Exfiltrate data to external systems
-- Compromise system security
-
-### Auditing Third-Party Skills
-
-If you must use untrusted skills:
-
-1. **Review all files**: SKILL.md, scripts, images, bundled resources
-2. **Check for unusual patterns**:
-   - Unexpected network calls
-   - File access beyond skill scope
-   - Operations not matching stated purpose
-3. **Examine external sources**: Skills fetching from URLs are risky
-4. **Verify dependencies**: Check code dependencies and imports
-
-### Runtime Constraints
-
-Skills run in the code execution container with:
-
-- ❌ **No network access**: Cannot make external API calls
-- ❌ **No runtime package installation**: Only pre-installed packages
-  available
-- ✅ **Sandboxed execution**: Isolated from host system
-
----
-
-## Skills are Composable
-
-> "Skills stack together. Claude automatically identifies which skills
-> are needed and coordinates their use."
->
-> — Anthropic Product Announcement
-
-### Example: Multi-Skill Task
-
-**User request**: "Create a GitHub contact card with database-backed
-favorites"
-
-**Skills activated**:
-
-1. `github-integration` - Fetch profile data
-2. `database-patterns` - Query favorites table
-3. `ui-components` - Build card component
-4. `styling-patterns` - Apply CSS/styles
-
-**Result**: Skills work together naturally, each handling its domain.
-
----
-
-## Where Skills Work
-
-### Claude.ai
-
-- **Pre-built Skills**: PowerPoint, Excel, Word, PDF (automatic)
-- **Custom Skills**: Upload as zip (Settings > Features)
-- **Sharing**: Individual user only (not org-wide)
-
-### Claude API
-
-- **Pre-built Skills**: Reference by `skill_id` (e.g., `pptx`, `xlsx`)
-- **Custom Skills**: Upload via `/v1/skills` endpoints
-- **Sharing**: Workspace-wide
-
-### Claude Code
-
-- **Custom Skills only**: Filesystem-based (`.claude/skills/` or
-  `~/.claude/skills/`)
-- **Sharing**: Via git/version control
-
-**Important**: Skills don't sync across surfaces. Upload separately
-for each platform.
-
----
-
-## Future of Skills
-
-From Anthropic:
-
-> "Looking further ahead, we hope to enable agents to create, edit,
-> and evaluate Skills on their own, letting them codify their own
-> patterns of behavior into reusable capabilities."
-
-**Coming soon**:
-
-- Simplified skill creation workflows
-- Enterprise-wide deployment
-- Skills complement MCP for complex workflows
-- Agents creating their own skills
-
----
-
-## Key Quotes
-
-### On Progressive Disclosure
-
-> "Progressive disclosure is the core design principle that makes
-> Agent Skills flexible and scalable."
-
-### On Simplicity
-
-> "Skills are a simple concept with a correspondingly simple format.
-> This simplicity makes it easier for organizations, developers, and
-> end users to build customized agents and give them new
-> capabilities."
-
-### On Filesystem Architecture
-
-> "Agents with a filesystem and code execution tools don't need to
-> read the entirety of a skill into their context window when working
-> on a particular task. This means that the amount of context that can
-> be bundled into a skill is effectively unbounded."
-
-### On Purpose
-
-> "Think of Skills as custom onboarding materials that let you package
-> expertise, making Claude a specialist on what matters most to you."
-
----
-
-## Official Resources
-
-### Documentation
-
-- [Agent Skills Overview](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview)
-- [Quickstart Tutorial](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/quickstart)
-- [Best Practices](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/best-practices)
-- [API Skills Guide](https://docs.claude.com/en/api/skills-guide)
-
-### Examples
-
-- [Skills Repository](https://github.com/anthropics/skills)
-- [Skills Cookbook](https://github.com/anthropics/claude-cookbooks/tree/main/skills)
-
-### Articles
-
-- [Product Announcement](https://www.anthropic.com/news/skills)
-- [Engineering Blog](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)
-
----
-
-## Summary: The Anthropic Philosophy
-
-**Skills are**:
-
-- Composable (stack together)
-- Portable (same format everywhere)
-- Efficient (only load what's needed)
-- Powerful (include executable code)
-
-**Build like**:
-
-- Onboarding guides (procedural knowledge)
-- Specialized tools (domain expertise)
-- Reference manuals (progressive detail)
-
-**Optimize for**:
-
-- Token efficiency (3-level loading)
-- Claude's perspective (discovery via metadata)
-- Real usage (iterate based on observation)
-- Scalability (split when too large)