From 4c5ff9901e99038ffa4136b6dc6f1940f1d7e934 Mon Sep 17 00:00:00 2001
From: tukuaiai <tukuaiai@gmail.com>
Date: Sun, 14 Dec 2025 08:29:55 +0800
Subject: [PATCH] feat: Enhance claude-skills module with new templates,
 improved script, and detailed documentation

---
 skills/claude-skills/SKILL.md                 | 549 ++++++++++--------
 .../claude-skills/assets/template-complete.md | 135 +++--
 .../claude-skills/assets/template-minimal.md  |  35 +-
 skills/claude-skills/references/index.md      | 141 +++--
 skills/claude-skills/scripts/create-skill.sh  | 182 +++++-
 5 files changed, 641 insertions(+), 401 deletions(-)

diff --git a/skills/claude-skills/SKILL.md b/skills/claude-skills/SKILL.md
index 09f3683..150ffe2 100644
--- a/skills/claude-skills/SKILL.md
+++ b/skills/claude-skills/SKILL.md
@@ -1,22 +1,108 @@
 ---
 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
+
+## Quick Reference
+
+### Skill Directory Structure
+
+```
+skill-name/
+├── 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
+```
+
+### YAML Frontmatter Specification
+
+```yaml
+---
+name: skill-name                    # Required: lowercase, hyphens, unique
+description: Complete description   # Required: What it does + when to trigger
+---
+```
+
+### Production SKILL.md Template
+
+```markdown
+---
+name: my-skill
+description: [Purpose] + [Trigger conditions]. Use when [specific scenarios].
+---
+
+# [Skill Name] Skill
+
+[One-paragraph overview]
+
+## When to Use This Skill
+
+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]
+
+## Working with This Skill
+
+### For Beginners
+[Getting started guidance]
+
+### For Specific Features
+[How to find detailed information]
+
+## Resources
+
+### references/
+[Description]
+
+### scripts/
+[Description]
+
+### assets/
+[Description]
+```
 
 ---
 
@@ -24,250 +110,229 @@ Skills are folders containing instructions, scripts, and resources that Claude l
 
 ### What is a Skill?
 
-**Skill = Folder + SKILL.md + Optional Resources**
+**A Skill is a folder containing instructions, scripts, and resources that Claude loads dynamically to improve performance on specialized tasks.**
 
-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
+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 Directory Structure
+### Skill Activation Triggers
 
-```
-skill-name/
-├── SKILL.md           # Required: Main instructions
-├── assets/            # Optional: Templates, configs, images
-├── scripts/           # Optional: Helper scripts
-└── references/        # Optional: Reference documentation
-```
+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
 
 ---
 
-## SKILL.md Specification
+## Creating Production-Grade Skills
 
-### YAML Frontmatter (Required)
+### Step 1: Define Scope
 
-```yaml
----
-name: skill-name          # Unique identifier (lowercase, hyphens)
-description: What it does and when to use it
----
-```
+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)?
 
-### Recommended Structure
+### Step 2: Gather Source Material
 
+Collect:
+- Official documentation
+- API references
+- Code examples and patterns
+- Common errors and solutions
+
+### Step 3: Structure the SKILL.md
+
+**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: Create Reference Files
+
+**references/index.md:**
 ```markdown
----
-name: my-skill
-description: Clear description of purpose and trigger scenarios
----
+# [Skill Name] Documentation Index
 
-# Skill Name
-
-## Overview
-Brief explanation of the skill's purpose.
-
-## When to Use This Skill
-- Trigger scenario 1
-- Trigger scenario 2
-
-## Instructions
-Detailed execution steps and rules.
-
-## Examples
-### Example 1: Scenario
-Concrete input/output examples.
-
-## Constraints
-- Limitation 1
-- Limitation 2
-
-## Error Handling
-Common errors and solutions.
-
-## Resources
-Reference links and documentation.
+## Quick Links
+- Getting Started → `getting_started.md`
+- API Reference → `api.md`
+- Examples → `examples.md`
 ```
 
----
-
-## Creating a Skill
-
-### Step 1: Create Directory
+### Step 5: Add Scripts and Assets
 
 ```bash
-mkdir -p my-skill/{assets,scripts,references}
-```
-
-### Step 2: Create SKILL.md
-
-```bash
-cat > my-skill/SKILL.md << 'EOF'
----
-name: my-skill
-description: Skill description
----
-
-# Skill Name
-
-## Overview
-[Purpose]
-
-## When to Use This Skill
-- [Trigger scenario]
-
-## Instructions
-[Detailed instructions]
-
-## Examples
-[Usage examples]
-EOF
-```
-
-### Step 3: Add Resources (Optional)
-
-- `assets/` - Templates, config files
-- `scripts/` - Helper scripts
-- `references/` - Reference docs
-
-### Step 4: Test and Iterate
-
-```
-"Use my-skill to [task description]"
+# 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
+# ❌ Vague
+- Working with code
 
-# ✅ 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+$
+# ✅ 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)
+```
+
+### Error Handling
+```python
+try:
+    result = client.operation()
+except APIError as e:
+    print(f"Error {e.code}: {e.message}")
+```
+```
+
+### Framework Skills
 
 ```markdown
----
-name: minimal-skill
-description: Brief description
----
-
-# Skill Name
-
-## Instructions
-[Core instructions]
-
-## Examples
-[Usage examples]
+## Project Structure
+```
+my-project/
+├── src/
+├── tests/
+└── config/
 ```
 
-### Complete Template
+## Common Commands
+```bash
+framework init my-project
+framework dev
+framework build
+```
+```
+
+### Domain Knowledge Skills
 
 ```markdown
----
-name: complete-skill
-description: Full description with purpose and trigger scenarios
----
+## Core Concepts
 
-# Skill Name
+### Concept 1
+[Explanation]
 
-## Overview
-Brief explanation of the skill's purpose and value.
+### Concept 2
+[Explanation]
 
-## When to Use This Skill
-- Scenario 1: [description]
-- Scenario 2: [description]
+## Decision Framework
 
-## Instructions
+When to use Approach A:
+- [Condition 1]
+- [Condition 2]
 
-### Step 1: [Name]
-[Details]
-
-### Step 2: [Name]
-[Details]
-
-## Examples
-
-### Example 1: [Scenario]
-
-**Input:**
-```
-[input]
-```
-
-**Output:**
-```
-[output]
-```
-
-## Constraints
-- Limitation 1
-- Limitation 2
-
-## Error Handling
-
-| Error | Cause | Solution |
-|-------|-------|----------|
-| Error 1 | Cause | Fix |
-
-## Resources
-- [Resource 1](link)
+When to use Approach B:
+- [Condition 1]
+- [Condition 2]
 ```
 
 ---
 
-## Using Skills
+## Generating Skills from Source Material
+
+### Transformation Process
+
+```
+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
+```
+
+### Generation Prompt
+
+When creating a skill from source material:
+
+```
+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/
+```
+
+---
+
+## 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
-```
-
-### Prompt Template
-
-```
-Generate a Claude Skill from the following material:
-
-## Source Material
-[paste your material]
-
-## Requirements
-1. Follow SKILL.md specification
-2. Include YAML frontmatter (name, description)
-3. Clear structure: Overview, Instructions, Examples, Constraints
-4. Concrete, executable examples
-```
+1. Add more specific trigger conditions
+2. Include more code examples
+3. Make instructions unambiguous
+4. Add explicit constraints
 
 ---
 
-## Skill Categories Reference
+## Reference Files
 
-| 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 |
+This skill includes documentation in `references/`:
 
----
+- **README.md** - Official Anthropic Skills repository documentation
+- **index.md** - Documentation index and quick links
+
+## Working with This Skill
+
+### For Creating New Skills
+Follow the 5-step process in "Creating Production-Grade Skills"
+
+### 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)
+### references/
+- Official Anthropic documentation
+- Navigation index
 
-### 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
+### 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
diff --git a/skills/claude-skills/assets/template-complete.md b/skills/claude-skills/assets/template-complete.md
index 5ef34d6..039a321 100644
--- a/skills/claude-skills/assets/template-complete.md
+++ b/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]
-
-### Step 2: [Step Name]
-
-[Detailed explanation]
-
-### Step 3: [Step Name]
-
-[Detailed explanation]
-
-## Examples
-
-### Example 1: [Scenario Name]
-
-**Input:**
-
-```
-[input content]
+**Pattern 1:** [Name]
+```[language]
+[code example]
 ```
 
-**Output:**
-
-```
-[output content]
+**Pattern 2:** [Name]
+```[language]
+[code example]
 ```
 
-### Example 2: [Scenario Name]
-
-**Input:**
-
-```
-[input content]
+**Pattern 3:** [Name]
+```[language]
+[code example]
 ```
 
-**Output:**
+### Example Code Patterns
 
-```
-[output content]
+**Example 1** ([language]):
+```[language]
+// [Description of what this example demonstrates]
+[complete working code]
 ```
 
-## Constraints
+**Example 2** ([language]):
+```[language]
+// [Description]
+[complete working code]
+```
 
-- Limitation 1: [description]
-- Limitation 2: [description]
-- Limitation 3: [description]
+## [Domain-Specific Section 1]
 
-## Error Handling
+### [Subsection]
 
-| Error | Cause | Solution |
-|-------|-------|----------|
-| Error 1 | [cause] | [solution] |
-| Error 2 | [cause] | [solution] |
+[Content]
+
+### [Subsection]
+
+[Content]
+
+## [Domain-Specific Section 2]
+
+### [Subsection]
+
+[Content]
+
+## Reference Files
+
+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
+
+Use `view` to read specific reference files when detailed information is needed.
+
+## Working with This Skill
+
+### For Beginners
+Start with the getting_started reference file for foundational concepts.
+
+### 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
diff --git a/skills/claude-skills/assets/template-minimal.md b/skills/claude-skills/assets/template-minimal.md
index 7161ef3..5259fde 100644
--- a/skills/claude-skills/assets/template-minimal.md
+++ b/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]
diff --git a/skills/claude-skills/references/index.md b/skills/claude-skills/references/index.md
index a7a799a..2237814 100644
--- a/skills/claude-skills/references/index.md
+++ b/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,18 +15,46 @@ 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 |
+
+## Skill Structure Reference
+
+### Required Files
+
+```
+skill-name/
+└── SKILL.md           # Main instructions with YAML frontmatter
+```
+
+### Optional Directories
+
+```
+skill-name/
+├── SKILL.md
+├── references/        # Documentation files
+├── scripts/           # Helper scripts
+└── assets/            # Templates, configs
+```
+
+### YAML Frontmatter
+
+```yaml
+---
+name: skill-name          # lowercase, hyphens
+description: What + When  # Purpose and trigger conditions
+---
+```
 
 ## Topics Covered
 
@@ -33,79 +64,37 @@ Complete overview of Claude Skills including:
 - Platform availability
 - Installation methods
 
-### Example Skills by Category
+### Skill Categories
 
-**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
+| 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 |
 
 ### Platform Integration
-- Claude Code plugin marketplace
-- Claude.ai skills interface
-- Claude API integration
-- Cross-platform portability
 
-## Skill Structure
-
-```
-skill-name/
-├── SKILL.md           # Required: Main instructions
-├── references/        # Optional: Documentation
-├── scripts/           # Optional: Helper scripts
-└── assets/            # Optional: Resources
-```
-
-## YAML Frontmatter
-
-```yaml
----
-name: skill-name
-description: Clear description of what the skill does
----
-```
+| Platform | Method |
+|----------|--------|
+| Claude Code | `/plugin marketplace add anthropics/skills` |
+| Claude.ai | Upload via skills interface |
+| Claude API | Skills API endpoint |
 
 ## External Resources
 
-- **Support Articles:**
-  - What are skills?
-  - Using skills in Claude
-  - Creating custom 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)
 
-- **Blog Posts:**
-  - Equipping agents with Agent 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)
diff --git a/skills/claude-skills/scripts/create-skill.sh b/skills/claude-skills/scripts/create-skill.sh
index 96d74df..211a624 100644
--- a/skills/claude-skills/scripts/create-skill.sh
+++ b/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
+# ${SKILL_NAME^} Skill
 
-## Overview
-
-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.
+---
 
-sed -i "s/SKILL_NAME_PLACEHOLDER/$SKILL_NAME/g" "$SKILL_NAME/SKILL.md"
+# ${SKILL_NAME^} Skill
 
-echo "✅ Created Skill: $SKILL_NAME/"
+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
+
+### Common Patterns
+
+**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/"