ai-agent-skills 1.1.1 → 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
+```