feat: Enhance claude-skills module with new templates, improved script, and detailed documentation

skills/claude-skills/SKILL.md

@@ -1,273 +1,338 @@
 ---
 name: claude-skills
-description: Meta-skill for creating Claude Skills. Use this to generate, structure, and optimize Skills that teach Claude domain-specific expertise from any source material.
+description: Meta-skill for creating, optimizing, and managing Claude Skills. Use when building new skills from documentation, converting domain expertise into AI capabilities, structuring skill files, or learning skill development best practices. This is the foundational skill that generates other skills.
 ---
 
 # Claude Skills Meta-Skill
 
-> **Meta-skill**: A skill that creates other skills. The core tool for building new Claude capabilities.
-
-## Overview
-
-Skills are folders containing instructions, scripts, and resources that Claude loads dynamically to improve performance on specialized tasks. This skill teaches you how to create, use, and optimize Skills.
+The definitive guide to creating production-grade Claude Skills. This meta-skill teaches Claude how to transform any domain knowledge into structured, reusable AI capabilities.
 
 ## When to Use This Skill
 
+This skill should be triggered when:
 - Creating a new Claude Skill from scratch
-- Converting domain knowledge/documentation into a Skill
-- Optimizing existing Skill structure and content
-- Learning Skill best practices and patterns
-
----
+- Converting documentation, APIs, or domain knowledge into a Skill
+- Optimizing or restructuring existing Skills
+- Learning Skill architecture patterns and best practices
+- Debugging or troubleshooting Skill behavior
+- Understanding YAML frontmatter and Skill metadata
+- Building multi-file Skills with references, scripts, and assets
 
-## Core Concepts
-
-### What is a Skill?
-
-**Skill = Folder + SKILL.md + Optional Resources**
-
-Skills teach Claude to complete specific tasks repeatably:
-- Apply company brand guidelines to documents
-- Analyze data using specific workflows
-- Automate personal tasks
-- Work with specific file formats or APIs
-- Apply domain-specific knowledge
+## Quick Reference
 
 ### Skill Directory Structure
 
 ```
 skill-name/
-├── SKILL.md           # Required: Main instructions
-├── assets/            # Optional: Templates, configs, images
-├── scripts/           # Optional: Helper scripts
-└── references/        # Optional: Reference documentation
+├── SKILL.md              # Required: Main instructions with YAML frontmatter
+├── references/           # Optional: Detailed documentation files
+│   ├── index.md          # Navigation index for references
+│   ├── api.md            # API documentation
+│   └── examples.md       # Code examples
+├── scripts/              # Optional: Helper scripts and automation
+│   └── setup.sh          # Setup/installation scripts
+└── assets/               # Optional: Templates, configs, media
+    └── templates/        # Boilerplate files
 ```
 
----
-
-## SKILL.md Specification
-
-### YAML Frontmatter (Required)
+### YAML Frontmatter Specification
 
 ```yaml
 ---
-name: skill-name          # Unique identifier (lowercase, hyphens)
-description: What it does and when to use it
+name: skill-name                    # Required: lowercase, hyphens, unique
+description: Complete description   # Required: What it does + when to trigger
 ---
 ```
 
-### Recommended Structure
+### Production SKILL.md Template
 
 ```markdown
 ---
 name: my-skill
-description: Clear description of purpose and trigger scenarios
+description: [Purpose] + [Trigger conditions]. Use when [specific scenarios].
 ---
 
-# Skill Name
+# [Skill Name] Skill
 
-## Overview
-Brief explanation of the skill's purpose.
+[One-paragraph overview]
 
 ## When to Use This Skill
-- Trigger scenario 1
-- Trigger scenario 2
 
-## Instructions
-Detailed execution steps and rules.
+This skill should be triggered when:
+- [Trigger 1]
+- [Trigger 2]
+- [Trigger 3]
+
+## Quick Reference
+
+### Common Patterns
+
+**Pattern 1:** [Name]
+```[language]
+[code]
+```
+
+### Example Code Patterns
+
+**Example 1** ([language]):
+```[language]
+[complete working example]
+```
+
+## Reference Files
+
+This skill includes documentation in `references/`:
+- **[file.md]** - [Description]
 
-## Examples
-### Example 1: Scenario
-Concrete input/output examples.
+## Working with This Skill
 
-## Constraints
-- Limitation 1
-- Limitation 2
+### For Beginners
+[Getting started guidance]
 
-## Error Handling
-Common errors and solutions.
+### For Specific Features
+[How to find detailed information]
 
 ## Resources
-Reference links and documentation.
+
+### references/
+[Description]
+
+### scripts/
+[Description]
+
+### assets/
+[Description]
 ```
 
 ---
 
-## Creating a Skill
+## Core Concepts
 
-### Step 1: Create Directory
+### What is a Skill?
 
-```bash
-mkdir -p my-skill/{assets,scripts,references}
-```
+**A Skill is a folder containing instructions, scripts, and resources that Claude loads dynamically to improve performance on specialized tasks.**
 
-### Step 2: Create SKILL.md
+Skills teach Claude to:
+- Apply domain-specific knowledge consistently
+- Follow organization-specific workflows
+- Work with specific APIs, file formats, or tools
+- Automate complex multi-step processes
+
+### Skill Activation Triggers
+
+Skills activate based on:
+- **Explicit mention**: "Use the [skill-name] skill to..."
+- **Description matching**: Task matches skill's description keywords
+- **Context relevance**: Task domain aligns with skill's purpose
 
-```bash
-cat > my-skill/SKILL.md << 'EOF'
----
-name: my-skill
-description: Skill description
 ---
 
-# Skill Name
+## Creating Production-Grade Skills
 
-## Overview
-[Purpose]
+### Step 1: Define Scope
 
-## When to Use This Skill
-- [Trigger scenario]
+Answer before writing:
+1. What specific problem does this skill solve?
+2. What triggers should activate this skill?
+3. What are the boundaries (what it should NOT do)?
 
-## Instructions
-[Detailed instructions]
+### Step 2: Gather Source Material
 
-## Examples
-[Usage examples]
-EOF
-```
+Collect:
+- Official documentation
+- API references
+- Code examples and patterns
+- Common errors and solutions
 
-### Step 3: Add Resources (Optional)
+### Step 3: Structure the SKILL.md
 
-- `assets/` - Templates, config files
-- `scripts/` - Helper scripts
-- `references/` - Reference docs
+**Critical sections:**
+1. YAML frontmatter with comprehensive description
+2. "When to Use This Skill" with specific triggers
+3. "Quick Reference" with common patterns
+4. Code examples that are complete and working
+5. Reference file pointers
 
-### Step 4: Test and Iterate
+### Step 4: Create Reference Files
+
+**references/index.md:**
+```markdown
+# [Skill Name] Documentation Index
 
+## Quick Links
+- Getting Started → `getting_started.md`
+- API Reference → `api.md`
+- Examples → `examples.md`
 ```
-"Use my-skill to [task description]"
+
+### Step 5: Add Scripts and Assets
+
+```bash
+# scripts/setup.sh
+#!/bin/bash
+echo "Setting up [skill-name]..."
 ```
 
 ---
 
 ## Best Practices
 
-### 1. Clear Description
+### Description Writing
 
 ```yaml
-# ❌ Bad
-description: Process data
+# ❌ Too vague
+description: Helps with databases
 
-# ✅ Good
-description: Clean and transform CSV data using pandas, with support for missing value handling, type conversion, and data validation
+# ✅ Comprehensive
+description: PostgreSQL database development including SQL queries, schema design, performance optimization. Use when working with PostgreSQL, writing SQL, or managing databases.
 ```
 
-### 2. Specific Instructions
+### Trigger Conditions
 
 ```markdown
-# ❌ Bad
-Handle user input
-
-# ✅ Good
-## Input Handling Rules
-1. Validate input format is JSON
-2. Check required fields: name, email, age
-3. Age must be positive integer
-4. Email validation regex: ^[\w.-]+@[\w.-]+\.\w+$
+# ❌ Vague
+- Working with code
+
+# ✅ Specific
+- Writing PostgreSQL queries or stored procedures
+- Designing database schemas or indexes
+- Optimizing slow queries
 ```
 
-### 3. Complete Examples
+### Code Examples
 
 ```markdown
-## Example
-
-### Input
-```json
-{"name": "John", "age": 25}
+# ❌ Incomplete
+```sql
+SELECT * FROM users
 ```
 
-### Output
-```json
-{"status": "success", "data": {"name": "John", "age": 25, "validated": true}}
+# ✅ Complete with context
+**Example: Paginated query with filtering**
+```sql
+SELECT id, username, email, created_at
+FROM users
+WHERE status = 'active'
+ORDER BY created_at DESC
+LIMIT 20 OFFSET 0;
 ```
 ```
 
-### 4. Explicit Constraints
+---
+
+## Skill Patterns by Category
+
+### API/Library Skills
 
 ```markdown
-## Constraints
-- Max data size: 10MB per request
-- UTF-8 encoding only
-- No sensitive data processing
+## Quick Reference
+
+### Authentication
+```python
+client = APIClient(api_key="your-key")
 ```
 
----
+### Common Operations
+```python
+# Create
+resource = client.create(name="example")
 
-## Templates
+# List
+resources = client.list(limit=10)
 
-### Minimal Template
+# Delete
+client.delete(resource_id)
+```
 
-```markdown
----
-name: minimal-skill
-description: Brief description
----
+### Error Handling
+```python
+try:
+    result = client.operation()
+except APIError as e:
+    print(f"Error {e.code}: {e.message}")
+```
+```
 
-# Skill Name
+### Framework Skills
 
-## Instructions
-[Core instructions]
+```markdown
+## Project Structure
+```
+my-project/
+├── src/
+├── tests/
+└── config/
+```
 
-## Examples
-[Usage examples]
+## Common Commands
+```bash
+framework init my-project
+framework dev
+framework build
+```
 ```
 
-### Complete Template
+### Domain Knowledge Skills
 
 ```markdown
----
-name: complete-skill
-description: Full description with purpose and trigger scenarios
----
-
-# Skill Name
+## Core Concepts
 
-## Overview
-Brief explanation of the skill's purpose and value.
+### Concept 1
+[Explanation]
 
-## When to Use This Skill
-- Scenario 1: [description]
-- Scenario 2: [description]
+### Concept 2
+[Explanation]
 
-## Instructions
+## Decision Framework
 
-### Step 1: [Name]
-[Details]
+When to use Approach A:
+- [Condition 1]
+- [Condition 2]
 
-### Step 2: [Name]
-[Details]
+When to use Approach B:
+- [Condition 1]
+- [Condition 2]
+```
 
-## Examples
+---
 
-### Example 1: [Scenario]
+## Generating Skills from Source Material
 
-**Input:**
-```
-[input]
-```
+### Transformation Process
 
-**Output:**
 ```
-[output]
+Source Material
+      ↓
+Extract: concepts, patterns, examples, edge cases, errors
+      ↓
+Structure: YAML → When to Use → Quick Reference → Details
+      ↓
+Create: references/index.md + categorized docs
+      ↓
+Production-Grade Skill
 ```
 
-## Constraints
-- Limitation 1
-- Limitation 2
+### Generation Prompt
 
-## Error Handling
+When creating a skill from source material:
 
-| Error | Cause | Solution |
-|-------|-------|----------|
-| Error 1 | Cause | Fix |
-
-## Resources
-- [Resource 1](link)
+```
+Create a production-grade Claude Skill:
+
+1. Analyze source material
+2. Extract core concepts and patterns
+3. Create SKILL.md with:
+   - Comprehensive description (purpose + triggers)
+   - Specific "When to Use" conditions
+   - Quick Reference with code patterns
+   - Complete working examples
+4. Create references/index.md
+5. Organize detailed docs in references/
 ```
 
 ---
 
-## Using Skills
+## Platform Integration
 
 ### Claude Code
 
@@ -279,77 +344,73 @@ Brief explanation of the skill's purpose and value.
 /plugin install example-skills@anthropic-agent-skills
 
 # Use
-"Use the PDF skill to extract form fields from path/to/file.pdf"
+"Use the PDF skill to extract tables from report.pdf"
 ```
 
 ### Claude.ai
 
-1. Go to Claude.ai (paid plan required)
-2. Upload custom skills via skills interface
-3. Reference skill in conversation
+1. Navigate to Claude.ai (paid plan)
+2. Upload custom skill folder
+3. Reference in conversations
 
 ### Claude API
 
-Upload and use skills via API. See [Skills API Quickstart](https://docs.claude.com/en/api/skills-guide)
+See: https://docs.claude.com/en/api/skills-guide
 
 ---
 
-## Generating Skills from Source Material
+## Troubleshooting
 
-### Input Types
+### Skill Not Activating
 
-1. **Official docs** - API documentation, user manuals
-2. **Code examples** - Sample code, best practices
-3. **Specifications** - Design specs, coding standards
-4. **FAQs** - Common questions and solutions
+1. Check `description` includes trigger keywords
+2. Verify `name` is lowercase with hyphens
+3. Ensure valid YAML (no tabs)
+4. Try explicit: "Use the [skill-name] skill to..."
 
-### Generation Flow
+### Inconsistent Behavior
 
-```
-1. Collect material → 2. Extract core knowledge → 3. Structure → 4. Write SKILL.md → 5. Test & iterate
-```
+1. Add more specific trigger conditions
+2. Include more code examples
+3. Make instructions unambiguous
+4. Add explicit constraints
 
-### Prompt Template
+---
 
-```
-Generate a Claude Skill from the following material:
+## Reference Files
 
-## Source Material
-[paste your material]
+This skill includes documentation in `references/`:
 
-## Requirements
-1. Follow SKILL.md specification
-2. Include YAML frontmatter (name, description)
-3. Clear structure: Overview, Instructions, Examples, Constraints
-4. Concrete, executable examples
-```
+- **README.md** - Official Anthropic Skills repository documentation
+- **index.md** - Documentation index and quick links
 
----
+## Working with This Skill
 
-## Skill Categories Reference
+### For Creating New Skills
+Follow the 5-step process in "Creating Production-Grade Skills"
 
-| Category | Examples |
-|----------|----------|
-| Creative | algorithmic-art, canvas-design, slack-gif-creator |
-| Development | artifacts-builder, mcp-server, webapp-testing |
-| Enterprise | brand-guidelines, internal-comms, theme-factory |
-| Documents | docx, pdf, pptx, xlsx |
-| Meta | skill-creator, template-skill |
+### For Optimizing Existing Skills
+Review "Best Practices" and compare against your skill
 
----
+### For Understanding Architecture
+Read "Core Concepts" for foundational understanding
 
 ## Resources
 
-### Official Documentation
-- [What are skills?](https://support.claude.com/en/articles/12512176-what-are-skills)
-- [Using skills in Claude](https://support.claude.com/en/articles/12512180-using-skills-in-claude)
-- [Creating custom skills](https://support.claude.com/en/articles/12512198-creating-custom-skills)
-- [Skills API Quickstart](https://docs.claude.com/en/api/skills-guide)
-- [Anthropic Skills GitHub](https://github.com/anthropics/skills)
-
-### This Skill's Assets
-- `references/README.md` - Official repository README
-- `references/index.md` - Documentation index
-- `assets/template-minimal.md` - Minimal template
-- `assets/template-complete.md` - Complete template
-- `scripts/create-skill.sh` - Quick creation script
+### references/
+- Official Anthropic documentation
+- Navigation index
+
+### scripts/
+- `create-skill.sh` - Quick skill directory generator
+
+### assets/
+- `template-minimal.md` - Minimal template
+- `template-complete.md` - Full production template
+
+## Notes
+
+- Skills are portable across Claude Code, Claude.ai, and API
+- The `description` field is critical for reliable activation
+- Code examples should be complete and immediately usable
+- This skill generates other production-grade skills

skills/claude-skills/assets/template-complete.md

@@ -1,78 +1,109 @@
 ---
 name: my-skill
-description: Full description of what this skill does, when to use it, and its core capabilities
+description: [Domain] development and operations including [capability 1], [capability 2], [capability 3]. Use when working with [domain], implementing [solutions], or troubleshooting [issues].
 ---
 
-# Skill Name
+# [Skill Name] Skill
 
-## Overview
-
-Brief explanation of the skill's purpose and value.
+Comprehensive assistance with [domain] development, generated from official documentation.
 
 ## When to Use This Skill
 
-- Scenario 1: [description]
-- Scenario 2: [description]
-- Scenario 3: [description]
+This skill should be triggered when:
+- Working with [domain/technology]
+- Asking about [domain] features or APIs
+- Implementing [domain] solutions
+- Debugging [domain] code
+- Learning [domain] best practices
 
-## Instructions
+## Quick Reference
 
-### Step 1: [Step Name]
+### Common Patterns
 
-[Detailed explanation]
+**Pattern 1:** [Name]
+```[language]
+[code example]
+```
 
-### Step 2: [Step Name]
+**Pattern 2:** [Name]
+```[language]
+[code example]
+```
 
-[Detailed explanation]
+**Pattern 3:** [Name]
+```[language]
+[code example]
+```
 
-### Step 3: [Step Name]
+### Example Code Patterns
 
-[Detailed explanation]
+**Example 1** ([language]):
+```[language]
+// [Description of what this example demonstrates]
+[complete working code]
+```
 
-## Examples
+**Example 2** ([language]):
+```[language]
+// [Description]
+[complete working code]
+```
 
-### Example 1: [Scenario Name]
+## [Domain-Specific Section 1]
 
-**Input:**
+### [Subsection]
 
-```
-[input content]
-```
+[Content]
 
-**Output:**
+### [Subsection]
 
-```
-[output content]
-```
+[Content]
 
-### Example 2: [Scenario Name]
+## [Domain-Specific Section 2]
 
-**Input:**
+### [Subsection]
 
-```
-[input content]
-```
+[Content]
 
-**Output:**
+## Reference Files
 
-```
-[output content]
-```
+This skill includes comprehensive documentation in `references/`:
+
+- **getting_started.md** - Installation, setup, first steps
+- **api.md** - Complete API reference
+- **examples.md** - Code examples by use case
+- **troubleshooting.md** - Common issues and solutions
 
-## Constraints
+Use `view` to read specific reference files when detailed information is needed.
 
-- Limitation 1: [description]
-- Limitation 2: [description]
-- Limitation 3: [description]
+## Working with This Skill
 
-## Error Handling
+### For Beginners
+Start with the getting_started reference file for foundational concepts.
 
-| Error | Cause | Solution |
-|-------|-------|----------|
-| Error 1 | [cause] | [solution] |
-| Error 2 | [cause] | [solution] |
+### For Specific Features
+Use the api reference file for detailed function/method information.
+
+### For Code Examples
+The examples reference file contains patterns organized by use case.
 
 ## Resources
 
-- [Resource 1](link)
-- [Resource 2](link)
+### references/
+Organized documentation extracted from official sources:
+- Detailed explanations
+- Code examples with language annotations
+- Links to original documentation
+
+### scripts/
+Helper scripts for common automation tasks.
+
+### assets/
+Templates, boilerplate, and example configurations.
+
+## Notes
+
+- This skill was generated from official documentation
+- Reference files preserve structure from source docs
+- Code examples include language detection for syntax highlighting
+- Quick reference patterns are extracted from common usage

skills/claude-skills/assets/template-minimal.md

@@ -1,14 +1,37 @@
 ---
 name: my-skill
-description: Brief description of what this skill does and when to use it
+description: [Domain] assistance including [key capability]. Use when [trigger condition].
 ---
 
-# Skill Name
+# [Skill Name] Skill
 
-## Instructions
+[One-sentence overview of what this skill does]
 
-[Core instructions here]
+## When to Use This Skill
 
-## Examples
+This skill should be triggered when:
+- [Trigger 1]
+- [Trigger 2]
+- [Trigger 3]
 
-[Usage examples here]
+## Quick Reference
+
+### Common Patterns
+
+**Pattern 1:**
+```[language]
+[code]
+```
+
+**Pattern 2:**
+```[language]
+[code]
+```
+
+## Resources
+
+### references/
+[Documentation files if any]
+
+### scripts/
+[Helper scripts if any]

skills/claude-skills/references/index.md

@@ -1,10 +1,13 @@
 # Claude Skills Documentation Index
 
+## Overview
+
+This index provides navigation for the Claude Skills meta-skill documentation.
+
 ## Categories
 
-### README
+### Official Documentation
 **File:** `README.md`
-**Pages:** 1 (122 lines)
 
 Complete overview of Claude Skills including:
 - What are skills and how they work
@@ -12,100 +15,86 @@ Complete overview of Claude Skills including:
 - Document skills (source-available)
 - Usage across platforms (Claude Code, Claude.ai, API)
 - Creating basic skills
-- Partner skills
 
 ## Quick Links
 
-- What are skills → `README.md` (line 1-9)
-- Example skills list → `README.md` (line 24-45)
-- Document skills → `README.md` (line 47-56)
-- Claude Code setup → `README.md` (line 58-78)
-- Claude.ai usage → `README.md` (line 80-84)
-- Claude API → `README.md` (line 86-88)
-- Creating a skill → `README.md` (line 90-117)
-- Partner skills → `README.md` (line 119-122)
+| Topic | File | Section |
+|-------|------|---------|
+| What are skills | `README.md` | Lines 1-9 |
+| Example skills list | `README.md` | Lines 24-45 |
+| Document skills | `README.md` | Lines 47-56 |
+| Claude Code setup | `README.md` | Lines 58-78 |
+| Claude.ai usage | `README.md` | Lines 80-84 |
+| Claude API | `README.md` | Lines 86-88 |
+| Creating a skill | `README.md` | Lines 90-117 |
 
-## Topics Covered
-
-### Getting Started
-- What skills are
-- How skills work
-- Platform availability
-- Installation methods
+## Skill Structure Reference
 
-### Example Skills by Category
+### Required Files
 
-**Creative & Design:**
-- Algorithmic art generation
-- Canvas design
-- Slack GIF creation
-
-**Development & Technical:**
-- HTML artifacts builder
-- MCP server creation
-- Webapp testing
-
-**Enterprise & Communication:**
-- Brand guidelines
-- Internal communications
-- Theme factory
-
-**Meta Skills:**
-- Skill creator guide
-- Template skill
-
-### Document Skills (Advanced)
-- DOCX (Word documents)
-- PDF (PDF manipulation)
-- PPTX (PowerPoint presentations)
-- XLSX (Excel spreadsheets)
-
-### Creating Skills
-- Basic structure (folder + SKILL.md)
-- YAML frontmatter requirements
-- Markdown instructions
-- Template usage
-
-### Platform Integration
-- Claude Code plugin marketplace
-- Claude.ai skills interface
-- Claude API integration
-- Cross-platform portability
+```
+skill-name/
+└── SKILL.md           # Main instructions with YAML frontmatter
+```
 
-## Skill Structure
+### Optional Directories
 
 ```
 skill-name/
-├── SKILL.md           # Required: Main instructions
-├── references/        # Optional: Documentation
-├── scripts/           # Optional: Helper scripts
-└── assets/            # Optional: Resources
+├── SKILL.md
+├── references/        # Documentation files
+├── scripts/           # Helper scripts
+└── assets/            # Templates, configs
 ```
 
-## YAML Frontmatter
+### YAML Frontmatter
 
 ```yaml
 ---
-name: skill-name
-description: Clear description of what the skill does
+name: skill-name          # lowercase, hyphens
+description: What + When  # Purpose and trigger conditions
 ---
 ```
 
-## External Resources
+## Topics Covered
+
+### Getting Started
+- What skills are
+- How skills work
+- Platform availability
+- Installation methods
+
+### Skill Categories
+
+| Category | Examples |
+|----------|----------|
+| Creative | algorithmic-art, canvas-design, slack-gif-creator |
+| Development | artifacts-builder, mcp-server, webapp-testing |
+| Enterprise | brand-guidelines, internal-comms, theme-factory |
+| Documents | docx, pdf, pptx, xlsx |
+| Meta | skill-creator, template-skill |
 
-- **Support Articles:**
-  - What are skills?
-  - Using skills in Claude
-  - Creating custom skills
+### Platform Integration
+
+| Platform | Method |
+|----------|--------|
+| Claude Code | `/plugin marketplace add anthropics/skills` |
+| Claude.ai | Upload via skills interface |
+| Claude API | Skills API endpoint |
+
+## External Resources
 
-- **Blog Posts:**
-  - Equipping agents with Agent Skills
+### Official Links
+- [What are skills?](https://support.claude.com/en/articles/12512176-what-are-skills)
+- [Using skills in Claude](https://support.claude.com/en/articles/12512180-using-skills-in-claude)
+- [Creating custom skills](https://support.claude.com/en/articles/12512198-creating-custom-skills)
+- [Skills API Quickstart](https://docs.claude.com/en/api/skills-guide)
+- [Anthropic Skills GitHub](https://github.com/anthropics/skills)
 
-- **API Documentation:**
-  - Skills API Quickstart
-  - Creating skills via API
+### Blog Posts
+- [Equipping agents with Agent Skills](https://anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)
 
 ## License
 
-Example skills: Apache 2.0 (open source)
-Document skills: Source-available (reference only)
+- Example skills: Apache 2.0 (open source)
+- Document skills: Source-available (reference only)

skills/claude-skills/scripts/create-skill.sh

@@ -1,54 +1,190 @@
 #!/bin/bash
-# Quick Skill directory structure generator
-# Usage: ./create-skill.sh <skill-name>
+#
+# create-skill.sh - Production-grade Skill directory generator
+#
+# Usage: ./create-skill.sh <skill-name> [--minimal]
+#
+# Examples:
+#   ./create-skill.sh postgresql
+#   ./create-skill.sh my-api --minimal
+#
+
+set -e
 
 SKILL_NAME=$1
+MINIMAL=$2
 
 if [ -z "$SKILL_NAME" ]; then
-    echo "Usage: ./create-skill.sh <skill-name>"
-    echo "Example: ./create-skill.sh my-awesome-skill"
+    echo "Usage: ./create-skill.sh <skill-name> [--minimal]"
+    echo ""
+    echo "Examples:"
+    echo "  ./create-skill.sh postgresql"
+    echo "  ./create-skill.sh my-api --minimal"
     exit 1
 fi
 
+# Validate skill name (lowercase, hyphens only)
+if [[ ! "$SKILL_NAME" =~ ^[a-z][a-z0-9-]*$ ]]; then
+    echo "Error: Skill name must be lowercase, start with letter, use hyphens"
+    echo "Example: my-skill-name"
+    exit 1
+fi
+
+echo "Creating skill: $SKILL_NAME"
+
+# Create directory structure
 mkdir -p "$SKILL_NAME"/{assets,scripts,references}
 
-cat > "$SKILL_NAME/SKILL.md" << 'EOF'
+# Create references/index.md
+cat > "$SKILL_NAME/references/index.md" << 'EOF'
+# Documentation Index
+
+## Categories
+
+### Getting Started
+- **getting_started.md** - Installation and setup
+
+### API Reference
+- **api.md** - Complete API documentation
+
+### Examples
+- **examples.md** - Code examples by use case
+
+## Quick Links
+
+- Installation → `getting_started.md`
+- API Reference → `api.md`
+- Examples → `examples.md`
+EOF
+
+if [ "$MINIMAL" == "--minimal" ]; then
+    # Minimal template
+    cat > "$SKILL_NAME/SKILL.md" << EOF
 ---
-name: SKILL_NAME_PLACEHOLDER
-description: Skill description
+name: $SKILL_NAME
+description: [Domain] assistance including [key capability]. Use when [trigger condition].
 ---
 
-# Skill Name
-
-## Overview
+# ${SKILL_NAME^} Skill
 
-Brief explanation of the skill's purpose.
+[One-sentence overview]
 
 ## When to Use This Skill
 
-- Scenario 1
-- Scenario 2
+This skill should be triggered when:
+- [Trigger 1]
+- [Trigger 2]
+- [Trigger 3]
 
-## Instructions
+## Quick Reference
 
-[Detailed instructions]
+### Common Patterns
 
-## Examples
+**Pattern 1:**
+\`\`\`
+[code]
+\`\`\`
 
-[Usage examples]
+## Resources
 
-## Constraints
+### references/
+Documentation files
 
-- Limitation 1
-- Limitation 2
+### scripts/
+Helper scripts
 EOF
+else
+    # Full production template
+    cat > "$SKILL_NAME/SKILL.md" << EOF
+---
+name: $SKILL_NAME
+description: [Domain] development including [capability 1], [capability 2]. Use when working with [domain], implementing solutions, or troubleshooting issues.
+---
+
+# ${SKILL_NAME^} Skill
+
+Comprehensive assistance with [domain] development.
+
+## When to Use This Skill
+
+This skill should be triggered when:
+- Working with [domain/technology]
+- Asking about [domain] features or APIs
+- Implementing [domain] solutions
+- Debugging [domain] code
+- Learning [domain] best practices
+
+## Quick Reference
 
-sed -i "s/SKILL_NAME_PLACEHOLDER/$SKILL_NAME/g" "$SKILL_NAME/SKILL.md"
+### Common Patterns
 
-echo "✅ Created Skill: $SKILL_NAME/"
+**Pattern 1:** [Name]
+\`\`\`
+[code example]
+\`\`\`
+
+**Pattern 2:** [Name]
+\`\`\`
+[code example]
+\`\`\`
+
+### Example Code Patterns
+
+**Example 1:**
+\`\`\`
+[complete working code]
+\`\`\`
+
+## Reference Files
+
+This skill includes documentation in \`references/\`:
+
+- **index.md** - Documentation navigation
+- **getting_started.md** - Setup and basics
+- **api.md** - API reference
+- **examples.md** - Code examples
+
+## Working with This Skill
+
+### For Beginners
+Start with getting_started reference file.
+
+### For Specific Features
+Use api reference for detailed information.
+
+### For Code Examples
+See examples reference file.
+
+## Resources
+
+### references/
+Organized documentation from official sources.
+
+### scripts/
+Helper scripts for automation.
+
+### assets/
+Templates and configurations.
+
+## Notes
+
+- Generated from official documentation
+- Code examples are complete and working
+EOF
+fi
+
+echo ""
+echo "✅ Created skill: $SKILL_NAME/"
+echo ""
+echo "   $SKILL_NAME/"
 echo "   ├── SKILL.md"
 echo "   ├── assets/"
 echo "   ├── scripts/"
 echo "   └── references/"
+echo "       └── index.md"
 echo ""
-echo "Next: Edit $SKILL_NAME/SKILL.md to add your instructions"
+echo "Next steps:"
+echo "  1. Edit $SKILL_NAME/SKILL.md"
+echo "  2. Add documentation to references/"
+echo "  3. Add helper scripts to scripts/"
+echo "  4. Add templates to assets/"