ai-agent-skills 1.2.0 → 1.2.1

package/.cursor/skills/claude-expert-skill-creator/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Vlad-Alexandru Nicolescu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/.cursor/skills/claude-expert-skill-creator/README.md

@@ -0,0 +1,188 @@
+# create-expert-skill
+
+> Transform expert conversations into production-grade Claude Skills. Whith this enhanced "skill-creator" skill you can capture domain knowledge and system-specific ontologies through structured roleplay. It also packages deterministic scripts alongside flexible guidance, and loads expertise progressively, turning AI assistants into specialists.
+
+## Why This Exists
+
+Anthropic released a basic "skill-creator", however, it doesn't utilize the entire range of what's possible within a Skill. This enhanced skill creator makes use of resources, examples, templates, scripts, progressive disclosure and system architecture knowledge to deliver elaborate skills, zipped and ready to upload.
+
+## Why the "Expert" Part Matters
+
+AI assistants struggle in production for two reasons:
+
+1. **Missing domain expertise** — Generic models don't know or aren't primed with your industry's edge cases, terminology, or unwritten rules.
+2. **Missing ontology understanding** — They don't grasp your specific data structures, entity relationships, or system constraints
+
+This skill solves both by helping you:
+- **Interview experts** (or yourself) to extract implicit domain knowledge
+- **Map system ontologies** — company-specific structures, codes, and relationships
+- **Separate deterministic work** (validation, parsing, math) from flexible interpretation
+- **Load knowledge progressively** — only what's needed, when it's needed
+
+The result: Claude works like a trained specialist who understands both the domain AND your specific systems.
+
+## Installation
+
+### Claude Desktop (Recommended)
+
+The packaged `.zip` file is included in this repository for easy installation:
+
+1. Download `create-expert-skill-v2.2.zip` from this repository
+2. Open Claude Desktop → **Settings** → **Capabilities**
+3. Under Skills, click **Upload Skill**
+4. Drag and drop the `.zip` file (no need to unzip)
+
+### Claude Code
+
+Skills can be installed at user or project level:
+
+**Personal skills** (available in all projects):
+```bash
+# Unzip and copy to your personal skills directory
+unzip create-expert-skill-v2.2.zip -d ~/.claude/skills/
+```
+
+**Project skills** (shared with team via git):
+```bash
+# Unzip into your project's .claude/skills/ directory
+unzip create-expert-skill-v2.2.zip -d ./.claude/skills/
+git add .claude/skills/create-expert-skill
+git commit -m "Add create-expert-skill"
+```
+
+Claude Code automatically discovers skills in these locations.
+
+### Claude Agent SDK
+
+For programmatic usage with the Agent SDK:
+
+1. Create skills directory in your project: `.claude/skills/`
+2. Unzip the skill into that directory
+3. Enable skills in your configuration by adding `"Skill"` to `allowed_tools`
+
+```python
+from claude_agent_sdk import query, ClaudeAgentOptions
+
+options = ClaudeAgentOptions(
+    allowed_tools=["Skill", "Read", "Write", "Bash"],
+    # Skills are auto-discovered from .claude/skills/
+)
+```
+
+See [Agent Skills in the SDK](https://platform.claude.com/docs/en/agent-sdk/skills) for full documentation.
+
+## Usage
+
+Start a conversation:
+> "I want to create a skill for validating LEDES billing files"
+
+Claude guides you through:
+```
+Assess  → Is this worth creating? (3+ uses, consistent procedure)
+Discover → What's the domain expertise? What are the system ontologies?
+Design  → What needs scripts vs guidance vs reference material?
+Create  → Generate the skill
+Refine  → Iterate until complete
+Ship    → Package for deployment
+```
+
+## How It Works
+
+### Two Knowledge Streams
+
+Production-ready skills require BOTH:
+
+**Domain Expertise** — Industry knowledge that applies universally:
+- Standards and their versions (e.g., LEDES 98B vs XML 2.0)
+- Professional conventions and edge cases
+- Validation rules from specifications
+
+**Ontology Understanding** — System-specific structures:
+- Company policies and constraints
+- Entity relationships (timekeepers → IDs → rates)
+- Data format variations unique to your systems
+
+### Progressive Disclosure Architecture
+
+Skills load knowledge in layers, not all at once:
+
+```
+Layer 0 (~25 tokens)   → Description only, always visible
+Layer 1 (~500 tokens)  → Core procedures in SKILL.md, loaded when triggered
+Layer 2 (~1000+ tokens) → Deep reference in resources/, loaded selectively
+```
+
+**Why this matters:** A 2,000-token skill that loads everything wastes context. A layered skill loads 25 tokens until needed, then 500, then more only if required.
+
+### Deterministic Scripts
+
+Anything that can be computed exactly should be:
+
+| Task | Without Script | With Script |
+|------|---------------|-------------|
+| Validate date format | LLM guesses (sometimes wrong) | `python validate.py` (always right) |
+| Sum line items | LLM approximates | Script calculates exactly |
+| Check against schema | LLM interprets | Script returns pass/fail |
+
+Scripts run at **zero token cost** — Claude executes them and uses the output.
+
+### Skill Structure
+
+```
+my-skill/
+├── SKILL.md              # Layer 1: Core procedures (300-500 tokens)
+├── scripts/              # Layer 0: Deterministic automation
+│   └── validate.py
+└── resources/            # Layer 2: Deep reference (loaded selectively)
+    ├── schemas/
+    └── ADVANCED.md
+```
+
+## Token Optimization
+
+| Technique | Before | After | Savings |
+|-----------|--------|-------|---------|
+| Scripts | 500 tokens explaining logic | `python scripts/validate.py` | ~450 |
+| Reference files | Inline schema (200 tokens) | Link to file | ~185 |
+| Layer 2 split | Everything in SKILL.md | Split to resources/ | ~750 |
+
+## Packaging
+
+**This skill includes an automated zipping procedure** In most cases, it runs on its own once the expert skill is finished, returning the plug-and-play .zip of the skill directly in conversation. If this doesn't run automatically, simply ask Claude to deliver the packaged skill.
+
+## Files
+
+```
+create-expert-skill/
+├── SKILL.md                          # Main skill (Layer 1)
+├── README.md                         # This file
+├── LICENSE                           # MIT
+├── create-expert-skill-v2.2.zip      # Ready-to-install package
+├── scripts/
+│   ├── package_skill.py              # Packaging automation
+│   └── README.md
+└── resources/
+    ├── templates/
+    │   └── TEMPLATES.md              # Skill templates (minimal/enhanced/script)
+    └── examples/
+        └── EXAMPLES.md               # Domain patterns (billing, API, schemas)
+```
+
+## Contributing
+
+Found a bug or want to improve the skill?
+- Open an issue for bugs or feature requests
+- PRs welcome for templates, examples, or documentation
+
+## License
+
+MIT — use freely, modify as needed.
+
+## Author
+
+[Vlad-Alexandru Nicolescu](https://github.com/vnicolescu)
+
+---
+
+**Version:** 2.2
+**Tested with:** Claude Desktop

package/.cursor/skills/claude-expert-skill-creator/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: create-expert-skill
+description: Create production-ready skills from expert knowledge. Extracts domain expertise and system ontologies, uses scripts for deterministic work, loads knowledge progressively. Use when building skills that must work reliably in production.
+version: 2.2
+---
+
+# Expert Skill Creation
+
+Transform expert knowledge into production-ready skills that combine domain expertise with system-specific understanding.
+
+## Why Skills Fail in Production
+
+AI assistants fail not because they lack intelligence, but because they lack:
+
+1. **Domain Expertise** — Industry-specific rules, edge cases, unwritten conventions
+2. **Ontology Understanding** — How YOUR systems, data structures, and workflows actually work
+
+**Both are required.** Domain knowledge without system context produces generic output. System knowledge without domain expertise produces structurally correct but semantically wrong results.
+
+## Workflow
+
+```
+Assess → Discover (Expertise + Ontology) → Design → Create → Refine → Ship
+```
+
+## Quick Assessment
+
+**Create a skill when:**
+- Used 3+ times (or will be)
+- Follows consistent procedure
+- Saves >300 tokens per use
+- Requires specialized knowledge not in Claude's training
+- Must produce trusted output (not "close enough")
+
+**Don't create for:** one-time tasks, basic knowledge Claude already has, rapidly changing content.
+
+## Discovery: Two Streams
+
+### Stream 1: Domain Expertise
+
+Deep knowledge that transcends any specific company:
+- Industry standards and their versions
+- Professional conventions and best practices
+- Edge cases only practitioners know
+- Validation rules from specifications
+
+*Example (LEDES validation):* LEDES 98B vs XML 2.0 formats, UTBMS code taxonomy, date format requirements, required vs optional fields.
+
+### Stream 2: Ontology Understanding
+
+How the skill maps to specific systems and organizations:
+- Company-specific policies and constraints
+- Data structures and identifiers unique to the system
+- Cross-references between entities (timekeepers → IDs → rates)
+- Workflow states and transitions
+
+*Example (LEDES validation):* Firm-specific timekeeper codes, matter numbering conventions, approved billing rates, outside counsel guideline requirements.
+
+### Discovery Questions
+
+When starting, I'll ask about:
+1. **Domain & Purpose** — What problem? What industry standards apply?
+2. **Ontology Requirements** — What system-specific structures must the skill understand?
+3. **Content Source** — Conversation, docs, specifications, or files to distill from?
+4. **Automation Potential** — What can be deterministic (scripts)? What needs interpretation (LLM)?
+5. **Complexity Level** — Simple (SKILL.md only), Enhanced (+scripts), or Full (+resources)?
+
+## Skill Architecture
+
+```
+skill-name/
+├── SKILL.md              # Layer 1: Core (300-500 tokens)
+├── scripts/              # Layer 0: Automation (0 tokens to run)
+│   └── validate.py
+└── resources/            # Layer 2: Details (loaded selectively)
+    └── ADVANCED.md
+```
+
+**Layer 0** (Scripts): Free execution, structured JSON output
+**Layer 1** (SKILL.md): Loaded when triggered - keep lean
+**Layer 2** (Resources): Fetched only when specific section needed
+
+## Token Optimization
+
+| Technique | Instead of | Do this | Savings |
+|-----------|-----------|---------|---------|
+| Scripts | 500 tokens explaining validation | `python scripts/validate.py` | ~450 tokens |
+| Reference | Inline schema (200 tokens) | Link to `resources/schema.json` | ~185 tokens |
+| Layer 2 | Everything in SKILL.md | Link to `resources/ADVANCED.md` | ~750 tokens |
+
+## Description Formula
+
+`<Action> <Object> for <Purpose>. Use when <Trigger>.`
+
+Example: "Validate billing data for system migration. Use before importing invoices."
+
+## Shipping
+
+When content is finalized:
+
+```bash
+python scripts/package_skill.py skill-name 1.0
+```
+
+Creates `skill-name-v1.0.zip` with:
+- DIRECTORY_STRUCTURE.txt (auto-generated)
+- README.md with deployment instructions
+- All skill files properly organized
+
+## Templates & Examples
+
+See `resources/templates/` for:
+- Minimal skill template
+- Enhanced skill template  
+- Script template
+
+See `resources/examples/` for domain-specific patterns.
+
+## Quality Checklist
+
+Before shipping:
+- [ ] Description <30 tokens
+- [ ] SKILL.md <500 tokens (Layer 1)
+- [ ] Scripts for deterministic operations
+- [ ] Advanced content in resources/ (Layer 2)
+- [ ] Version in frontmatter
+- [ ] All referenced files exist
+
+---
+
+**Version:** 2.2 | **Target:** <500 tokens Layer 1

package/.cursor/skills/claude-expert-skill-creator/resources/examples/EXAMPLES.md

@@ -0,0 +1,147 @@
+# Domain Examples
+
+Real-world skill patterns for common use cases.
+
+---
+
+## Example 1: Billing System Migration
+
+**Context:** Company migrating from legacy billing to modern system.
+
+**Discovery questions:**
+1. What format is legacy data? (CSV, JSON, database dump?)
+2. What's the target format for new system?
+3. Are there data transformations needed? (field mapping, calculations?)
+4. Any validation rules to enforce?
+5. How should errors be handled?
+
+**Resulting structure:**
+```
+billing-migration/
+├── SKILL.md                       # Migration workflow
+├── scripts/
+│   ├── validate_legacy.py         # Check data completeness
+│   ├── transform.py               # Map fields to new format
+│   └── verify_totals.py           # Verify financial totals match
+└── resources/
+    ├── schemas/
+    │   ├── legacy.json            # Legacy data schema
+    │   └── modern.json            # Target schema
+    └── mappings/
+        └── field_mapping.json     # Field-to-field mapping
+```
+
+**Token efficiency:**
+- Description: ~25 tokens
+- SKILL.md: ~400 tokens
+- Scripts: 0 tokens (execution is free)
+- resources/: ~1200 tokens (loaded only for complex cases)
+
+---
+
+## Example 2: API Integration
+
+**Context:** Integrating with external API, handling auth, rate limits, retries.
+
+**Discovery questions:**
+1. What API? (OpenAPI spec available?)
+2. What endpoints are used most?
+3. How does authentication work?
+4. Are there rate limits to handle?
+5. What error cases need special handling?
+
+**Resulting structure:**
+```
+api-integration/
+├── SKILL.md                       # Common API patterns
+├── scripts/
+│   ├── authenticate.py            # Handle OAuth flow
+│   ├── request.py                 # Wrapper with retry logic
+│   └── rate_limiter.py            # Respect rate limits
+└── resources/
+    ├── openapi.json               # API specification
+    └── templates/
+        └── request.json           # Request body templates
+```
+
+---
+
+## Example 3: Data Schema Mapping
+
+**Context:** Mapping between two data formats with transformations.
+
+**Discovery questions:**
+1. What are the source and target schemas?
+2. Are transformations simple (rename) or complex (calculations)?
+3. What happens to unmapped fields?
+4. How should validation errors be handled?
+
+**Resulting structure:**
+```
+schema-mapper/
+├── SKILL.md                       # Mapping workflow
+├── scripts/
+│   ├── validate_source.py         # Check source data
+│   ├── map_fields.py              # Apply mapping rules
+│   └── validate_target.py         # Verify output
+└── resources/
+    ├── schemas/
+    │   ├── source.json
+    │   └── target.json
+    └── mappings.json              # Field mapping rules
+```
+
+---
+
+## Common Patterns
+
+### Pattern: Validation Script
+Every skill that processes data should include validation:
+
+```python
+def validate(data, schema_path):
+    """Validate data against JSON schema."""
+    with open(schema_path) as f:
+        schema = json.load(f)
+    
+    errors = []
+    for i, item in enumerate(data):
+        try:
+            jsonschema.validate(item, schema)
+        except jsonschema.ValidationError as e:
+            errors.append({"index": i, "error": e.message, "path": list(e.path)})
+    
+    return {"valid": len(errors) == 0, "errors": errors}
+```
+
+### Pattern: Transformation Script
+For data conversion:
+
+```python
+def transform(source_data, mapping):
+    """Transform data using field mapping."""
+    results = []
+    for item in source_data:
+        transformed = {}
+        for target_field, source_field in mapping.items():
+            if isinstance(source_field, str):
+                transformed[target_field] = item.get(source_field)
+            elif callable(source_field):
+                transformed[target_field] = source_field(item)
+        results.append(transformed)
+    return results
+```
+
+### Pattern: Error Accumulation
+Never fail on first error - collect all issues:
+
+```python
+def process_batch(items):
+    results = {"success": [], "errors": []}
+    for item in items:
+        try:
+            results["success"].append(process_one(item))
+        except Exception as e:
+            results["errors"].append({"item_id": item.get("id"), "error": str(e)})
+    return results
+```

package/.cursor/skills/claude-expert-skill-creator/resources/templates/TEMPLATES.md

@@ -0,0 +1,202 @@
+# Skill Templates
+
+Templates for creating new skills. Copy and customize.
+
+---
+
+## Minimal Skill Template
+
+For simple skills with just procedures (no scripts):
+
+```markdown
+---
+name: skill-name
+description: Action on object for purpose. Use when trigger.
+version: 1.0
+---
+
+# Skill Name: Purpose
+
+Brief explanation of what this skill does.
+
+## Quick Start
+
+Most common usage - copy-paste ready.
+
+## Common Scenarios
+
+### Scenario 1: Typical Case
+Description and steps.
+
+### Scenario 2: Variant
+How to handle variations.
+
+## Error Handling
+
+- **Error X**: Cause → Fix
+- **Error Y**: Cause → Fix
+
+---
+**Version:** 1.0
+```
+
+---
+
+## Enhanced Skill Template
+
+For skills with automation scripts:
+
+```markdown
+---
+name: skill-name  
+description: Action on object for purpose. Use when trigger.
+version: 1.0
+---
+
+# Skill Name: Purpose
+
+## Quick Start
+
+\`\`\`bash
+python scripts/process.py --input data.json
+\`\`\`
+
+Expected output: [describe success]
+
+## Prerequisites
+
+- Input format: [specify]
+- Required files: [list]
+
+## Common Scenarios
+
+### Scenario 1: Standard Usage
+\`\`\`bash
+python scripts/process.py --input data.json --output result.json
+\`\`\`
+
+### Scenario 2: Validation Only
+\`\`\`bash
+python scripts/validate.py data.json
+\`\`\`
+
+## Error Handling
+
+- **Error X**: Cause → Fix
+- **Error Y**: Cause → Fix
+
+## Advanced Usage
+
+See [ADVANCED.md](./resources/ADVANCED.md) for complex scenarios.
+
+---
+**Version:** 1.0
+```
+
+---
+
+## Script Template
+
+Standard pattern for automation scripts:
+
+```python
+#!/usr/bin/env python3
+"""
+Script Name: Short description
+
+Usage:
+    python script_name.py input.json [output.json]
+
+Returns:
+    JSON with structured results:
+    {
+        "status": "success|error",
+        "data": {...},
+        "errors": [...]
+    }
+"""
+
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+
+def process(input_path: str, output_path: str = None) -> dict[str, Any]:
+    """Main processing function."""
+    try:
+        with open(input_path) as f:
+            data = json.load(f)
+        
+        # Process data
+        results = {"processed": [], "errors": []}
+        for item in data:
+            try:
+                results["processed"].append(transform(item))
+            except Exception as e:
+                results["errors"].append({"item": item.get("id"), "error": str(e)})
+        
+        # Write output if specified
+        if output_path:
+            with open(output_path, 'w') as f:
+                json.dump(results["processed"], f, indent=2)
+        
+        return {
+            "status": "success" if not results["errors"] else "partial",
+            "processed": len(results["processed"]),
+            "errors": results["errors"]
+        }
+    
+    except Exception as e:
+        return {"status": "error", "message": str(e)}
+
+
+def transform(item: dict) -> dict:
+    """Transform single item - customize this."""
+    return item
+
+
+def main():
+    if len(sys.argv) < 2:
+        print(__doc__)
+        sys.exit(1)
+    
+    input_path = sys.argv[1]
+    output_path = sys.argv[2] if len(sys.argv) > 2 else None
+    
+    result = process(input_path, output_path)
+    print(json.dumps(result, indent=2))
+    sys.exit(0 if result["status"] == "success" else 1)
+
+
+if __name__ == "__main__":
+    main()
+```
+
+---
+
+## DIRECTORY_STRUCTURE.txt Template
+
+Auto-generated by `package_skill.py`, but here's the format:
+
+```
+skill-name/
+├── SKILL.md                    # Main skill file (Layer 1)
+├── README.md                   # Deployment instructions
+├── DIRECTORY_STRUCTURE.txt     # This file
+├── scripts/                    # Automation scripts (Layer 0)
+│   ├── process.py
+│   └── README.md
+└── resources/                  # Reference materials (Layer 2)
+    ├── ADVANCED.md
+    └── schemas/
+        └── schema.json
+
+Token Budget:
+- Layer 0 (description): ~25 tokens
+- Layer 1 (SKILL.md): ~400 tokens
+- Layer 2 (resources/): ~1000 tokens (loaded selectively)
+
+Version: 1.0
+Created: YYYY-MM-DD
+```

package/.cursor/skills/claude-expert-skill-creator/scripts/README.md

@@ -0,0 +1,38 @@
+# Scripts
+
+Automation utilities for skill packaging.
+
+## package_skill.py
+
+Packages a skill folder into a deployment-ready .zip file.
+
+### Usage
+
+```bash
+python package_skill.py <skill-folder> <version> [output-dir]
+```
+
+### Examples
+
+```bash
+# Package skill in current directory
+python package_skill.py ./my-skill 1.0
+
+# Specify output location
+python package_skill.py /path/to/skill 2.0 ./releases
+
+# Package this skill itself
+python package_skill.py ../ 2.1
+```
+
+### What it does
+
+1. Validates skill folder has SKILL.md
+2. Generates `DIRECTORY_STRUCTURE.txt` with token estimates
+3. Generates `README.md` if missing
+4. Creates `skill-name-v{version}.zip`
+
+### Requirements
+
+- Python 3.8+
+- Standard library only (no dependencies)

package/.cursor/skills/claude-expert-skill-creator/scripts/package_skill.py

@@ -0,0 +1,249 @@
+#!/usr/bin/env python3
+"""
+Skill Packaging Script
+
+Packages a skill folder into a deployment-ready .zip file.
+
+Usage:
+    python package_skill.py <skill-folder> <version> [output-dir]
+
+Examples:
+    python package_skill.py ./billing-migration 1.0
+    python package_skill.py /path/to/my-skill 2.1 ./releases
+
+Creates:
+    skill-name-v{version}.zip
+
+What it does:
+    1. Validates skill folder and SKILL.md exist
+    2. Generates DIRECTORY_STRUCTURE.txt
+    3. Generates README.md (if missing)
+    4. Creates versioned .zip file
+"""
+
+import re
+import shutil
+import sys
+from datetime import datetime
+from pathlib import Path
+
+
+def extract_frontmatter(skill_md_path: Path) -> dict:
+    """Extract YAML frontmatter from SKILL.md."""
+    content = skill_md_path.read_text()
+    
+    if not content.startswith('---'):
+        return {}
+    
+    parts = content.split('---', 2)
+    if len(parts) < 3:
+        return {}
+    
+    frontmatter = {}
+    for line in parts[1].strip().split('\n'):
+        if ':' in line:
+            key, value = line.split(':', 1)
+            frontmatter[key.strip()] = value.strip()
+    
+    return frontmatter
+
+
+def estimate_tokens(text: str) -> int:
+    """Rough token estimate (~4 chars per token for English)."""
+    return len(text) // 4
+
+
+def generate_directory_structure(skill_path: Path, version: str) -> str:
+    """Generate DIRECTORY_STRUCTURE.txt content."""
+    
+    def build_tree(path: Path, prefix: str = "") -> list[str]:
+        """Recursively build directory tree."""
+        lines = []
+        children = sorted(path.iterdir(), key=lambda x: (x.is_file(), x.name))
+        
+        for i, child in enumerate(children):
+            is_last = i == len(children) - 1
+            connector = "└── " if is_last else "├── "
+            suffix = "/" if child.is_dir() else ""
+            lines.append(f"{prefix}{connector}{child.name}{suffix}")
+            
+            if child.is_dir():
+                extension = "    " if is_last else "│   "
+                lines.extend(build_tree(child, prefix + extension))
+        
+        return lines
+    
+    # Build tree
+    tree_lines = [f"{skill_path.name}/"]
+    tree_lines.extend(build_tree(skill_path))
+    
+    # Estimate tokens
+    skill_md = skill_path / "SKILL.md"
+    layer1_tokens = estimate_tokens(skill_md.read_text()) if skill_md.exists() else 0
+    
+    # Extract description token count
+    frontmatter = extract_frontmatter(skill_md) if skill_md.exists() else {}
+    desc = frontmatter.get('description', '')
+    desc_tokens = len(desc.split())
+    
+    # Layer 2 tokens
+    resources_path = skill_path / "resources"
+    layer2_tokens = 0
+    if resources_path.exists():
+        for md_file in resources_path.rglob("*.md"):
+            layer2_tokens += estimate_tokens(md_file.read_text())
+    
+    structure = "\n".join(tree_lines)
+    
+    return f"""{structure}
+
+Token Budget:
+- Layer 0 (description): ~{desc_tokens} tokens (always loaded)
+- Layer 1 (SKILL.md): ~{layer1_tokens} tokens (loaded on trigger)
+- Layer 2 (resources/): ~{layer2_tokens} tokens (loaded selectively)
+
+Version: {version}
+Created: {datetime.now().strftime('%Y-%m-%d')}
+"""
+
+
+def generate_readme(skill_name: str, version: str) -> str:
+    """Generate README.md with deployment instructions."""
+    title = skill_name.replace('-', ' ').replace('_', ' ').title()
+    
+    return f"""# {title}
+
+**Version:** {version}  
+**Created:** {datetime.now().strftime('%Y-%m-%d')}
+
+## Quick Deploy
+
+1. **Unzip**
+   ```bash
+   unzip {skill_name}-v{version}.zip
+   ```
+
+2. **Install in Claude Desktop**
+   - Open Claude Desktop → Settings → Capabilities → Skills
+   - Click "Add Skill" or "Upload Skill"
+   - Select the `{skill_name}` folder
+
+3. **Verify**
+   - Skill appears in your skills list
+   - Available in all conversations
+
+## Alternative: Manual Installation
+
+```bash
+# Mac/Linux
+cp -r {skill_name} ~/Library/Application\\ Support/Claude/skills/
+
+# Windows
+copy {skill_name} %APPDATA%\\Claude\\skills\\
+```
+
+## Structure
+
+See `DIRECTORY_STRUCTURE.txt` for layout and token budget.
+
+## Usage
+
+See `SKILL.md` for:
+- Quick start
+- Common scenarios
+- Error handling
+
+---
+
+**Ready to use!**
+"""
+
+
+def package_skill(skill_path: Path, version: str, output_dir: Path = None) -> Path:
+    """
+    Package skill into deployment-ready .zip file.
+    
+    Args:
+        skill_path: Path to skill folder
+        version: Version number (e.g., "1.0")
+        output_dir: Where to create .zip (default: current directory)
+    
+    Returns:
+        Path to created .zip file
+    """
+    skill_path = skill_path.resolve()
+    output_dir = (output_dir or Path.cwd()).resolve()
+    
+    # Validate
+    if not skill_path.exists():
+        raise FileNotFoundError(f"Skill folder not found: {skill_path}")
+    
+    skill_md = skill_path / "SKILL.md"
+    if not skill_md.exists():
+        raise FileNotFoundError(f"SKILL.md not found in {skill_path}")
+    
+    if not re.match(r'^\d+\.\d+$', version):
+        raise ValueError(f"Invalid version format: {version}. Use X.Y (e.g., 1.0, 2.1)")
+    
+    skill_name = skill_path.name
+    print(f"📦 Packaging: {skill_name} v{version}")
+    print(f"   Source: {skill_path}")
+    
+    # Generate DIRECTORY_STRUCTURE.txt
+    structure_content = generate_directory_structure(skill_path, version)
+    (skill_path / "DIRECTORY_STRUCTURE.txt").write_text(structure_content)
+    print("   ✓ Generated DIRECTORY_STRUCTURE.txt")
+    
+    # Generate README.md if missing
+    readme_path = skill_path / "README.md"
+    if not readme_path.exists():
+        readme_path.write_text(generate_readme(skill_name, version))
+        print("   ✓ Generated README.md")
+    else:
+        print("   ✓ Using existing README.md")
+    
+    # Create zip
+    zip_name = f"{skill_name}-v{version}"
+    zip_path = output_dir / f"{zip_name}.zip"
+    
+    if zip_path.exists():
+        zip_path.unlink()
+    
+    # Create zip with skill folder as root
+    shutil.make_archive(
+        str(output_dir / zip_name),
+        'zip',
+        skill_path.parent,
+        skill_name
+    )
+    
+    size_kb = zip_path.stat().st_size / 1024
+    print(f"   ✓ Created {zip_path.name} ({size_kb:.1f} KB)")
+    
+    print(f"\n✅ Package ready: {zip_path}")
+    print("\nTo deploy:")
+    print("1. Unzip the package")
+    print("2. Claude Desktop → Settings → Skills → Add Skill")
+    print("3. Select the skill folder")
+    
+    return zip_path
+
+
+def main():
+    if len(sys.argv) < 3:
+        print(__doc__)
+        sys.exit(1)
+    
+    skill_path = Path(sys.argv[1])
+    version = sys.argv[2]
+    output_dir = Path(sys.argv[3]) if len(sys.argv) > 3 else None
+    
+    try:
+        package_skill(skill_path, version, output_dir)
+    except Exception as e:
+        print(f"\n❌ Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/README.md

@@ -6,7 +6,7 @@
 
 <p align="center">
   <strong>Homebrew for AI agent skills.</strong><br>
-  One command. Ten agents. Skills that follow you.
+  Universal Skills installer for any agent that follows the open standard spec 
 </p>
 
 <p align="center">
@@ -179,10 +179,8 @@ cp -r Ai-Agent-Skills/skills/pdf ~/.claude/skills/
 
 ## Create Your Own
 
-Two options:
 
-1. **Generate in 30 seconds**: [skillcreator.ai/build](https://skillcreator.ai/build)
-2. **Build manually**: Follow the [Agent Skills spec](https://agentskills.io/specification)
+1. **Build manually**: Follow the [Agent Skills spec](https://agentskills.io/specification)
 
 ## What Are Agent Skills?
 
@@ -209,19 +207,17 @@ We review all contributions for quality and spec compliance.
 
 ## Links
 
-- [Awesome Agent Skills](https://github.com/skillcreatorai/Awesome-Agent-Skills) - Curated list of 50+ skills
+
 - [Agent Skills Spec](https://agentskills.io) - Official format documentation
-- [Browse Skills](https://skillcreator.ai/discover) - Visual skill gallery with one-click install
-- [Create Skills](https://skillcreator.ai/build) - Generate skills from plain English
+- [Browse Skills](https://skillcreator.ai/explore) - Visual skill gallery with one-click install
+- [Create Skills](https://skillcreator.ai/build) - Generate skills (waitlist) 
 - [Anthropic Skills](https://github.com/anthropics/skills) - Official example skills
 
 ## See Also
 
-**[openskills](https://github.com/numman-ali/openskills)** - Universal skills loader that inspired parts of this project. openskills focuses on flexibility: install from any GitHub repo, sync to AGENTS.md, works with any agent via CLI calls. Great if you need maximum customization.
-
-**We took a different approach**: Homebrew-style simplicity. No global install, no sync step, no AGENTS.md. Just `npx ai-agent-skills install pdf` and it lands in the right folder for your agent. Curated catalog, native paths, zero config.
+**[openskills](https://github.com/numman-ali/openskills)** - another universal skills loader that inspired parts of this project (created pre the open agent skills standard) & Requires global install, AGENTS.md sync, and Bash calls. Great for flexibility.
 
-Different tools for different needs.
+**ai-agent-skills** - Just `npx`, installs to native agent folders. Homebrew for skills.
 
 ---
 

package/cli.js

@@ -211,7 +211,13 @@ function copyDir(src, dest, currentSize = { total: 0 }) {
 
     const entries = fs.readdirSync(src, { withFileTypes: true });
 
+    // Files/folders to skip during copy
+    const skipList = ['.git', '.github', 'node_modules', '.DS_Store'];
+
     for (const entry of entries) {
+      // Skip unnecessary files/folders
+      if (skipList.includes(entry.name)) continue;
+
       const srcPath = path.join(src, entry.name);
       const destPath = path.join(dest, entry.name);
 
@@ -768,11 +774,18 @@ async function browseSkills(agent = 'claude') {
 // ============ EXTERNAL INSTALL (GitHub/Local) ============
 
 function isGitHubUrl(source) {
-  return source.includes('/') && !source.startsWith('.') && !source.startsWith('/') && !source.startsWith('~');
+  // Must have owner/repo format, not start with path indicators
+  return source.includes('/') &&
+         !source.startsWith('./') &&
+         !source.startsWith('../') &&
+         !source.startsWith('/') &&
+         !source.startsWith('~');
 }
 
 function isLocalPath(source) {
-  return source.startsWith('.') || source.startsWith('/') || source.startsWith('~');
+  // Only explicit local paths: ./ or / or ~/
+  // NOT ../ (that's path traversal, should be rejected)
+  return source.startsWith('./') || source.startsWith('/') || source.startsWith('~/');
 }
 
 function expandPath(p) {
@@ -816,6 +829,9 @@ async function installFromGitHub(source, agent = 'claude', dryRun = false) {
       ? path.join(tempDir, 'skills')
       : tempDir;
 
+    // Check if repo root IS a skill (has SKILL.md at root)
+    const isRootSkill = fs.existsSync(path.join(tempDir, 'SKILL.md'));
+
     if (skillName) {
       // Install specific skill
       const skillPath = path.join(skillsDir, skillName);
@@ -835,6 +851,19 @@ async function installFromGitHub(source, agent = 'claude', dryRun = false) {
       copyDir(skillPath, destPath);
       success(`\nInstalled: ${skillName} from ${owner}/${repo}`);
       info(`Location: ${destPath}`);
+    } else if (isRootSkill) {
+      // Repo itself is a single skill
+      const skillName = repo;
+      const destDir = AGENT_PATHS[agent] || AGENT_PATHS.claude;
+      const destPath = path.join(destDir, skillName);
+
+      if (!fs.existsSync(destDir)) {
+        fs.mkdirSync(destDir, { recursive: true });
+      }
+
+      copyDir(tempDir, destPath);
+      success(`\nInstalled: ${skillName} from ${owner}/${repo}`);
+      info(`Location: ${destPath}`);
     } else {
       // Install all skills from repo
       const entries = fs.readdirSync(skillsDir, { withFileTypes: true });
@@ -970,6 +999,7 @@ ${colors.bold}Commands:${colors.reset}
   ${colors.green}search <query>${colors.reset}                   Search skills by name, description, or tags
   ${colors.green}info <name>${colors.reset}                      Show skill details
   ${colors.green}config${colors.reset}                           Show/edit configuration
+  ${colors.green}version${colors.reset}                          Show version number
   ${colors.green}help${colors.reset}                             Show this help
 
 ${colors.bold}Options:${colors.reset}
@@ -978,6 +1008,7 @@ ${colors.bold}Options:${colors.reset}
   ${colors.cyan}--dry-run, -n${colors.reset}    Preview changes without applying
   ${colors.cyan}--category <c>${colors.reset}   Filter by category
   ${colors.cyan}--all${colors.reset}            Apply to all (with update)
+  ${colors.cyan}--version, -v${colors.reset}    Show version number
 
 ${colors.bold}Agents:${colors.reset}
   ${colors.cyan}claude${colors.reset}   (default) ~/.claude/skills/
@@ -1202,6 +1233,13 @@ switch (command || 'help') {
     showHelp();
     break;
 
+  case 'version':
+  case '--version':
+  case '-v':
+    const pkg = require('./package.json');
+    log(`ai-agent-skills v${pkg.version}`);
+    break;
+
   default:
     // If command looks like a skill name, try to install it
     if (getAvailableSkills().includes(command)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-agent-skills",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Install curated AI agent skills with one command. Works with Claude Code, Cursor, Amp, VS Code, and all Agent Skills compatible tools.",
   "main": "cli.js",
   "bin": {

package/skills.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.2.0",
-  "updated": "2025-12-20T00:00:00Z",
+  "version": "1.2.1",
+  "updated": "2025-12-25T00:00:00Z",
   "total": 39,
   "skills": [
     {
@@ -516,7 +516,7 @@
       "id": "development",
       "name": "Development",
       "description": "Coding and software development skills",
-      "count": 12
+      "count": 13
     },
     {
       "id": "document",
@@ -528,19 +528,19 @@
       "id": "creative",
       "name": "Creative",
       "description": "Design and creative skills",
-      "count": 2
+      "count": 6
     },
     {
       "id": "business",
       "name": "Business",
       "description": "Business and communication skills",
-      "count": 2
+      "count": 5
     },
     {
       "id": "productivity",
       "name": "Productivity",
       "description": "Productivity and workflow skills",
-      "count": 3
+      "count": 11
     }
   ]
 }