zhongwei/gh-jgardner04-skills-jgardner04-skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:25:55 +08:00
commit 42b20ade49
9 changed files with 2537 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
.claude-plugin/plugin.json Normal file
View File

@@ -0,0 +1,12 @@
{
"name": "jgardner04-skills",
"description": "Collection of custom skills for enhancing Claude's capabilities across various domains",
"version": "0.0.0-2025.11.28",
"author": {
"name": "jgardner04",
"email": "zhongweili@tubi.tv"
},
"skills": [
"./skills/skill-creator"
]
}

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# jgardner04-skills
Collection of custom skills for enhancing Claude's capabilities across various domains

64
plugin.lock.json Normal file
View File

@@ -0,0 +1,64 @@
{
"$schema": "internal://schemas/plugin.lock.v1.json",
"pluginId": "gh:jgardner04/skills:jgardner04-skills",
"normalized": {
"repo": null,
"ref": "refs/tags/v20251128.0",
"commit": "09693446562ee344813c808c848a82ae06f3de3c",
"treeHash": "e65f8bf934517afaa4d2eff8943f6c45c4a612c0d9e9548f84416ec345ac8dc2",
"generatedAt": "2025-11-28T10:19:06.377226Z",
"toolVersion": "publish_plugins.py@0.2.0"
},
"origin": {
"remote": "git@github.com:zhongweili/42plugin-data.git",
"branch": "master",
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
},
"manifest": {
"name": "jgardner04-skills",
"description": "Collection of custom skills for enhancing Claude's capabilities across various domains"
},
"content": {
"files": [
{
"path": "README.md",
"sha256": "6a4974bc151d042edcc73363df8d7b78fc6804decc8f7445e4a5cc3a179b29f0"
},
{
"path": ".claude-plugin/plugin.json",
"sha256": "46cc059ac871bbdd9cc9524757185d54e310a812604c6e1229ef3200167e6983"
},
{
"path": "skills/skill-creator/README.md",
"sha256": "a996c049942397dd6c973f94807d11bdbaf4cf46b74d2ac5fd3f9f8498736d43"
},
{
"path": "skills/skill-creator/SKILL.md",
"sha256": "95bc49d212efdfbe555de894c532c27c62bb527fb906356d88b1cd90893312df"
},
{
"path": "skills/skill-creator/LICENSE.txt",
"sha256": "7a1cfa1916ad1571323321a3167321cd6b87915181d22066a043f659bcf7373d"
},
{
"path": "skills/skill-creator/reference/skill-examples.md",
"sha256": "c126ba3e909b552f6c05743d130344141ce91f3bc8f6952d1fead9061061df56"
},
{
"path": "skills/skill-creator/reference/platform-differences.md",
"sha256": "fda31836e230afa7d7d9facdf859d43657c6d74fc359a05ee46e83ff61c4471f"
},
{
"path": "skills/skill-creator/reference/skill-specification.md",
"sha256": "3cc54541ee2aba959befd18ffe3b7825eb31b2a6cbe0b3a6cee64fa1236c3436"
}
],
"dirSha256": "e65f8bf934517afaa4d2eff8943f6c45c4a612c0d9e9548f84416ec345ac8dc2"
},
"security": {
"scannedAt": null,
"scannerVersion": null,
"flags": []
}
}

176
skills/skill-creator/LICENSE.txt Normal file
View File

@@ -0,0 +1,176 @@
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS

64
skills/skill-creator/README.md Normal file
View File

@@ -0,0 +1,64 @@
# Skill Creator
A meta-skill for creating, validating, and packaging Claude agent skills. This skill helps you build high-quality skills that extend Claude's capabilities.
## What This Skill Does
The skill-creator automates the entire skill development lifecycle:
1. **Interactive Skill Generation** - Asks clarifying questions and generates proper structure
2. **Validation** - Validates SKILL.md format, naming conventions, and requirements
3. **Packaging** - Creates distributable skill packages
4. **Guidance** - Provides best practices and platform-specific guidance
## When to Use
Claude will proactively use this skill when you:
- Want to create a new skill
- Need to validate an existing skill
- Are packaging a skill for distribution
- Want to learn skill development best practices
## Quick Start
Simply ask Claude to create a skill:
```
"I want to create a skill for [purpose]"
```
Claude will guide you through the process using the skill-creator.
## Files in This Skill
- **SKILL.md** - Main skill definition with instructions
- **reference/** - Detailed reference documentation
- `platform-differences.md` - Platform-specific guidance (Claude.ai, API, Code)
- `skill-examples.md` - Complete example skills
- `skill-specification.md` - Technical specification
- **LICENSE.txt** - Apache 2.0 license
## Validation and Packaging Scripts
The skill creator references validation and packaging scripts that are available at the repository root level in `scripts/`:
- **validate_skill.py** - Validates skills against specifications
- **package_skill.py** - Creates distributable skill packages
- **skill_utils.py** - Shared utilities
See the main repository README for how to use these scripts.
## Platform Support
This skill works across:
- **Claude.ai** - User-specific skills
- **Claude API** - Workspace-wide skills
- **Claude Code** - Project/user-level skills with full capabilities
## License
Licensed under Apache 2.0. See LICENSE.txt for complete terms.
## Original Source
This skill was originally developed at https://github.com/jgardner04/claude-skills-skill and has been integrated into this marketplace.

488
skills/skill-creator/SKILL.md Normal file
View File

@@ -0,0 +1,488 @@
---
name: skill-creator
description: Create, validate, and package Claude skills automatically. Use PROACTIVELY when users want to create a new skill, validate existing skill files, or package skills for distribution. Works across Claude.ai, API, and Claude Code platforms.
---
# Skill Creator
An interactive guide for creating, validating, and packaging new Claude skills. This skill helps you build high-quality skills that extend Claude's capabilities with specialized knowledge, workflows, or tool integrations.
## What Are Skills?
Skills are modular capabilities that extend Claude's functionality. Each skill packages:
- **Instructions**: Step-by-step guidance for completing specific tasks
- **Metadata**: Name and description for automatic discovery
- **Resources**: Optional scripts, templates, and reference documentation
Skills use progressive disclosure - only loading what's needed when needed - to minimize token usage while maximizing capability.
## When to Use This Skill
Use the skill-creator when you need to:
- **Create a new skill** from scratch
- **Validate an existing skill** against Claude's requirements
- **Package a skill** for distribution
- **Update a skill** to meet current standards
- **Learn** skill best practices and requirements
## Skill Creation Workflow
### Step 1: Understand the Need
Ask clarifying questions to understand:
1. **Purpose**: What task or domain will this skill address?
2. **Scope**: Is it simple (just instructions) or complex (with scripts/references)?
3. **Platform**: Which Claude surfaces should it target? (Claude.ai, API, Claude Code, or all)
4. **Automation**: Should it be automatically invoked or user-triggered?
Example questions:
- "What specific problem does this skill solve?"
- "Will the skill need helper scripts or just provide guidance?"
- "Should Claude use this skill proactively when users mention [topic]?"
- "Does the skill need platform-specific features (like network access)?"
### Step 2: Design the Skill
Based on the requirements, plan:
**Directory Structure Options:**
**Option A: Simple Skill (Instructions only)**
```
skill-name/
└── SKILL.md
```
**Option B: Skill with Scripts**
```
skill-name/
├── SKILL.md
└── scripts/
├── __init__.py
├── helper1.py
└── helper2.py
```
**Option C: Complex Skill (Full featured)**
```
skill-name/
├── SKILL.md
├── scripts/
│ ├── __init__.py
│ └── utilities.py
└── references/
├── specification.md
└── examples.md
```
**Naming Convention:**
- Lowercase letters, numbers, and hyphens only
- Maximum 64 characters
- Cannot contain "anthropic" or "claude"
- Descriptive and concise (e.g., `git-helper`, `api-tester`, `doc-writer`)
### Step 3: Write SKILL.md
Every skill must have a SKILL.md file with this structure:
```markdown
---
name: skill-name
description: Brief description of what this skill does and when to use it (max 1024 chars)
---
# Skill Title
## Overview
What the skill does and why it's useful.
## When to Use This Skill
Specific scenarios where this skill should be invoked.
## Instructions
### Step 1: [First Action]
Detailed guidance for the first step...
### Step 2: [Second Action]
Detailed guidance for the second step...
### Step N: [Final Action]
Detailed guidance for completion...
## Best Practices
Tips for optimal results.
## Common Issues
Troubleshooting guidance.
## Examples
Concrete examples of the skill in action.
```
**Critical Requirements:**
✅ **Required YAML Frontmatter**
```yaml
---
name: skill-name # lowercase, hyphens, max 64 chars
description: What it does and when to use it # max 1024 chars
---
```
✅ **Description Best Practices**
- Explain WHAT the skill does
- Explain WHEN to use it
- Use action-oriented language (e.g., "Use when...", "MUST be used for...")
- Be specific about capabilities
- Maximum 1024 characters
- No XML tags
✅ **Content Organization**
- Clear hierarchy with headings
- Step-by-step instructions
- Concrete examples
- Platform-specific guidance if needed
### Step 4: Add Supporting Resources (Optional)
**Scripts (Python recommended):**
- Use for deterministic operations
- Validate, transform, or package data
- Generate templates or boilerplate
- Follow security best practices (see references/skill-specification.md)
Example script structure:
```python
#!/usr/bin/env python3
"""
Brief description of what this script does.
"""
import argparse
from pathlib import Path
from typing import Tuple
def main() -> int:
"""Main entry point."""
parser = argparse.ArgumentParser(description="...")
# ... argument parsing ...
try:
result = do_work(args)
print(f"Success: {result}")
return 0
except Exception as e:
print(f"Error: {e}", file=sys.stderr)
return 1
if __name__ == "__main__":
sys.exit(main())
```
**Reference Documentation:**
- Technical specifications
- API documentation
- Database schemas
- Best practices guides
- Example templates
References are loaded on-demand, so include comprehensive details without worrying about token cost.
### Step 5: Validate the Skill
Use the validation script to ensure compliance:
```bash
python .claude-plugin/scripts/validate_skill.py path/to/skill/
```
The validator checks:
- ✅ YAML frontmatter format
- ✅ Required fields (name, description)
- ✅ Naming conventions
- ✅ Description length and format
- ✅ No XML tags or restricted terms
- ✅ File structure
Fix any errors before proceeding.
### Step 6: Test the Skill
1. **Place the skill** in the appropriate location:
- Project-level: `.claude/skills/skill-name/`
- User-level: `~/.claude/agents/skill-name.md` (for single-file skills)
- Plugin: `.claude-plugin/` (for distribution)
2. **Invoke the skill** and verify:
- Instructions are clear and actionable
- Scripts execute correctly
- References load when needed
- Platform-specific features work as expected
3. **Iterate** based on results:
- Clarify ambiguous instructions
- Fix script bugs
- Add missing examples
- Improve error handling
### Step 7: Package for Distribution (Optional)
To share the skill:
```bash
python .claude-plugin/scripts/package_skill.py path/to/skill/ --output skill-name.zip
```
This creates a distributable package including:
- SKILL.md
- All scripts and references
- Metadata/manifest
- Installation instructions
## Platform-Specific Considerations
### Claude.ai
- **Scope**: User-specific (not shared across workspace)
- **Network**: Varies by user/admin settings
- **Distribution**: Upload through Skills UI
- **Best for**: Personal productivity, individual workflows
### Claude API
- **Scope**: Workspace-wide accessible
- **Network**: No access by default
- **Dependencies**: Pre-configured only, no dynamic installation
- **Best for**: Programmatic workflows, enterprise deployments
### Claude Code
- **Scope**: Project-level (.claude/skills/) or user-level (~/.claude/agents/)
- **Network**: Full access available
- **Dependencies**: Can install packages as needed
- **Best for**: Development workflows, technical tasks
**Include platform notes when relevant:**
```markdown
## Platform Notes
### Claude Code
This skill requires network access to fetch API data. It works best in Claude Code where network access is available by default.
### Claude API
Note: This skill requires pre-configured API keys via environment variables.
```
## Best Practices
### Token Efficiency
- Keep SKILL.md focused on essential instructions
- Move detailed specs to reference files
- Use progressive disclosure (load references only when needed)
- Aim for 30-50 tokens when skill is inactive (just frontmatter)
### Discoverability
- Write descriptions that clearly explain when to use the skill
- Use action-oriented language: "Use PROACTIVELY when..."
- Include relevant keywords in the description
- Be specific about capabilities
### Quality
- Test thoroughly before distributing
- Include concrete examples
- Provide troubleshooting guidance
- Handle errors gracefully
- Validate all user inputs
### Security
- Never execute arbitrary code (no eval/exec)
- Validate file paths (prevent traversal attacks)
- Sanitize user inputs
- Use allowlists over denylists
- Follow principle of least privilege
### Maintainability
- Use clear, descriptive names
- Document all functions and scripts
- Keep skills focused on a single purpose
- Version your skills for tracking changes
- Write clear error messages
## Validation Rules Reference
Load the complete specification when needed:
```
Read .claude-plugin/references/skill-specification.md
```
Key rules:
- **Name**: lowercase, hyphens, max 64 chars, no "anthropic"/"claude"
- **Description**: non-empty, max 1024 chars, no XML tags
- **Frontmatter**: Valid YAML between `---` delimiters
- **Files**: UTF-8 encoding, reasonable sizes
- **Scripts**: Executable, proper permissions, type-safe
## Example: Creating a Simple Skill
**User Request**: "Create a skill to help format commit messages"
**Skill Creator Response**:
1. **Clarify requirements**:
- "Should it validate existing commits or generate new ones?"
- "Do you want specific commit types enforced (feat, fix, docs)?"
- "Should it integrate with git commands or just provide guidance?"
2. **After getting answers, create the skill**:
```markdown
---
name: commit-formatter
description: Format git commit messages according to Conventional Commits specification. Use when writing commit messages or validating commit history.
---
# Commit Formatter
Helps create well-formatted git commit messages following Conventional Commits.
## When to Use This Skill
- Writing new commit messages
- Validating existing commits
- Learning commit message best practices
## Instructions
### Step 1: Determine Commit Type
Choose the appropriate type:
- **feat**: New feature
- **fix**: Bug fix
- **docs**: Documentation only
- **style**: Code style (formatting, missing semicolons)
- **refactor**: Code change that neither fixes a bug nor adds a feature
- **perf**: Performance improvement
- **test**: Adding or updating tests
- **chore**: Maintenance tasks
### Step 2: Write Subject Line
Format: `<type>(<scope>): <subject>`
- Scope is optional but recommended (e.g., api, ui, auth)
- Subject is lowercase, no period at end
- Keep under 50 characters
### Step 3: Add Body (Optional)
- Wrap at 72 characters
- Explain what and why, not how
- Separate from subject with blank line
### Step 4: Add Footer (Optional)
- Breaking changes: `BREAKING CHANGE: <description>`
- Issue references: `Closes #123`
## Examples
**Simple commit**:
```
feat(auth): add OAuth2 login support
```
**With body**:
```
fix(api): handle null response from user service
The user service occasionally returns null when the user
is not found. This commit adds proper null checking and
returns a 404 status code.
```
**Breaking change**:
```
feat(api): redesign authentication endpoints
BREAKING CHANGE: The /auth endpoint now requires POST instead
of GET. Update all clients to use POST with JSON body.
Closes #456
```
```
3. **Validate the skill**:
```bash
python .claude-plugin/scripts/validate_skill.py .claude/skills/commit-formatter/
```
4. **Test it**:
- Ask Claude to help format a commit
- Verify the guidance is clear and actionable
- Check examples are helpful
## Troubleshooting
### Skill Not Being Invoked Automatically
**Problem**: Claude doesn't use the skill even when relevant.
**Solutions**:
- Improve the description with clearer trigger phrases
- Add "Use PROACTIVELY when..." to the description
- Mention the skill explicitly: "Use the [skill-name] skill to..."
### Validation Errors
**Problem**: Validator reports errors.
**Solutions**:
- Check YAML formatting (use `---` delimiters)
- Verify name follows conventions (lowercase, hyphens only)
- Ensure description is under 1024 characters
- Remove any XML tags from text
- Check file encoding is UTF-8
### Scripts Not Executing
**Problem**: Python scripts fail or aren't found.
**Solutions**:
- Verify script has execute permissions: `chmod +x script.py`
- Check shebang line: `#!/usr/bin/env python3`
- Ensure dependencies are installed
- Test script independently before integrating
- Check file paths are correct (use Path from pathlib)
### Cross-Platform Issues
**Problem**: Skill works on one platform but not another.
**Solutions**:
- Check platform constraints (network access, dependencies)
- Use pathlib for file paths (not os.path)
- Avoid platform-specific assumptions
- Test on all target platforms
- Add platform-specific guidance in SKILL.md
## Getting Help
For detailed technical specifications:
```
Read .claude-plugin/references/skill-specification.md
```
For platform-specific guidance:
```
Read .claude-plugin/references/platform-differences.md
```
For more examples:
```
Read .claude-plugin/references/skill-examples.md
```
## Creating the Skill Automatically
When you're ready, I'll:
1. **Create the directory structure** at the specified location
2. **Generate SKILL.md** with proper frontmatter and content
3. **Add scripts** if requested (using the python-dev agent for quality)
4. **Create reference files** if needed
5. **Validate** the entire skill
6. **Package** if for distribution if requested
Just tell me what skill you want to create, and I'll guide you through the process!

618
skills/skill-creator/reference/platform-differences.md Normal file
View File

@@ -0,0 +1,618 @@
# Platform-Specific Guidance for Claude Skills
Understanding the differences between Claude surfaces to create skills that work everywhere.
## Overview
Claude skills can run on three different surfaces:
1. **Claude.ai** - Web interface and mobile apps
2. **Claude API** - Programmatic access for developers
3. **Claude Code** - CLI tool for development workflows
Each platform has different capabilities, constraints, and runtime environments. This guide helps you create skills that work effectively across all platforms or target specific ones.
## Quick Comparison
| Feature | Claude.ai | Claude API | Claude Code |
|---------|-----------|------------|-------------|
| **Skill Scope** | User-specific | Workspace-wide | Project or user |
| **Network Access** | Variable (admin settings) | No (by default) | Yes (full access) |
| **File System** | Limited (uploads only) | Limited | Full access |
| **Package Installation** | No | No | Yes (with permissions) |
| **Bash Commands** | No | Limited (sandboxed) | Yes (full shell) |
| **Best For** | Personal productivity | Programmatic workflows | Development tasks |
## Claude.ai
### Overview
Web-based interface with mobile app support. Skills help individual users with their work.
### Characteristics
**Skill Scope**: User-specific only
- Each user uploads their own skills
- Skills are not shared across workspace
- No way to distribute org-wide skills
- Good for personal productivity
**Network Access**: Variable
- Depends on user settings
- Depends on admin/organization policies
- Can be restricted by IT
- Skills should handle network unavailability gracefully
**File System Access**: Upload-based
- Users upload files through the UI
- Skills can read uploaded files
- Skills can generate downloadable files
- No direct file system access
**Tool Availability**:
- ✅ Read (uploaded files)
- ✅ Write (generate downloads)
- ⚠️ WebFetch (if network allowed)
- ⚠️ WebSearch (if network allowed)
- ❌ Bash (no shell access)
- ❌ Git operations
### Best Practices for Claude.ai
#### Make Network Access Optional
```markdown
## Using the API (Optional)
If you have network access enabled, this skill can fetch live data.
Otherwise, you can upload data files directly.
```
#### Provide Upload Instructions
```markdown
## Setup
1. Download the template from [link]
2. Fill in your data
3. Upload the file to Claude
4. Use this skill to process it
```
#### Handle Missing Dependencies
```markdown
## Note
This skill works best with network access. If network is disabled,
you can still use the basic features by providing data manually.
```
#### Use Read/Write Effectively
- Generate files users can download
- Process uploaded CSV, JSON, Markdown
- Create reports, summaries, visualizations (as text/markdown)
### Example: Claude.ai-Friendly Skill
```yaml
---
name: meeting-notes-formatter
description: Format raw meeting notes into structured summaries with action items. Works with uploaded text files or pasted content.
tools: Read, Write
---
# Meeting Notes Formatter
Formats meeting notes into professional summaries.
## How to Use
**Option 1: Upload a file**
1. Save your meeting notes as a .txt or .md file
2. Upload to Claude
3. Ask me to format it: "Format the meeting notes"
**Option 2: Paste directly**
1. Copy your meeting notes
2. Paste into the chat
3. Ask me to format it
## What You'll Get
- Executive summary
- Key discussion points
- Action items with owners
- Decisions made
- Follow-up topics
No network access required!
```
## Claude API
### Overview
Programmatic access for developers to integrate Claude into applications and workflows.
### Characteristics
**Skill Scope**: Workspace-wide
- Skills are available to all workspace members
- Configured at the organization level
- Shared across all API calls in the workspace
- Centralized management
**Network Access**: None by default
- No outbound network requests
- No API calls to external services
- Skills must work offline
- Security-focused design
**Dependency Management**: Pre-configured only
- No dynamic package installation
- Dependencies must be pre-installed in the runtime
- Limited to standard library + pre-approved packages
- Skills cannot require new dependencies
**Execution Environment**: Sandboxed
- Controlled execution environment
- Limited file system access
- Security restrictions
- Predictable, reproducible behavior
**Tool Availability**:
- ✅ Read (from provided context)
- ✅ Write (to return data)
- ⚠️ Bash (sandboxed, limited commands)
- ❌ WebFetch (no network)
- ❌ WebSearch (no network)
- ❌ Package installation
### Best Practices for Claude API
#### Design for Offline Operation
```python
# ❌ Bad: Requires network
def fetch_user_data(user_id):
response = requests.get(f"https://api.example.com/users/{user_id}")
return response.json()
# ✅ Good: Works with provided data
def process_user_data(user_data: dict) -> dict:
"""Process user data provided by the caller."""
return {
"summary": generate_summary(user_data),
"insights": extract_insights(user_data),
}
```
#### Use Only Standard Library
```python
# ✅ Good: Standard library only
import json
import re
from datetime import datetime
from pathlib import Path
from typing import Dict, List
# ❌ Bad: External dependency
import pandas as pd # Not available unless pre-installed
```
#### Document Data Requirements
```markdown
## API Integration
This skill requires the following data to be provided:
### Input Format
```json
{
"users": [...],
"events": [...],
"config": {...}
}
```
### Output Format
```json
{
"report": "...",
"metrics": {...},
"recommendations": [...]
}
```
```
#### Provide Clear Error Messages
```python
def validate_input(data: dict) -> tuple[bool, str]:
"""Validate input data structure."""
if "users" not in data:
return False, "Missing required field: 'users'"
if not isinstance(data["users"], list):
return False, "Field 'users' must be a list"
return True, ""
```
### Example: API-Optimized Skill
```yaml
---
name: data-transformer
description: Transform and validate JSON data structures. Requires data to be provided via API call. Works entirely offline with no external dependencies.
tools: Read, Write
model: haiku
---
# Data Transformer
Transforms JSON data according to specified rules.
## API Usage
```python
import anthropic
client = anthropic.Anthropic()
# Provide data in the API call
message = client.messages.create(
model="claude-3-sonnet-20240229",
messages=[{
"role": "user",
"content": f"Transform this data: {json.dumps(data)}"
}]
)
```
## Input Requirements
The skill expects JSON data in this format:
```json
{
"data": [...],
"rules": {...}
}
```
## Output
Returns transformed data:
```json
{
"transformed": [...],
"errors": [],
"stats": {...}
}
```
## No Dependencies
Uses only Python standard library - no external packages required.
```
## Claude Code
### Overview
CLI tool for development workflows with full system access.
### Characteristics
**Skill Scope**: Flexible
- Project-level: `.claude/skills/` (shared with team via git)
- User-level: `~/.claude/agents/` (personal)
- Plugin-level: `.claude-plugin/` (distributable)
**Network Access**: Full
- Unrestricted outbound requests
- Can call APIs
- Can fetch web pages
- Can download resources
**File System Access**: Full
- Read any accessible file
- Write to any writable location
- Execute commands
- Full git integration
**Package Installation**: Available
- Can install Python packages (pip)
- Can install npm packages
- Can use system package managers
- Can compile code
**Tool Availability**:
- ✅ All tools available
- ✅ Bash (full shell access)
- ✅ WebFetch
- ✅ WebSearch
- ✅ Git operations
- ✅ Read/Write/Edit
- ✅ Task (subagents)
### Best Practices for Claude Code
#### Leverage Full Capabilities
```yaml
---
name: api-tester
description: Test REST APIs with automatic request generation and validation. Use when developing or debugging API endpoints.
tools: Bash, Read, Write, WebFetch
---
# API Tester
Tests REST APIs with comprehensive validation.
## Features
- Automatic request generation
- Response validation
- Performance metrics
- Error handling tests
- OpenAPI spec generation
## Requirements
```bash
pip install requests pyyaml jsonschema
```
## Usage
Just tell me the API endpoint to test!
```
#### Use Project Configuration
```markdown
## Setup
Add to `.claude/settings.json`:
```json
{
"env": {
"API_KEY": "${YOUR_API_KEY}",
"API_URL": "https://api.example.com"
}
}
```
The skill will read these values automatically.
```
#### Integrate with Development Tools
```bash
# Run linters
black your_script.py
pylint your_script.py
# Run tests
pytest tests/
# Build project
npm run build
```
#### Create Complex Workflows
```markdown
## Workflow
1. Fetch latest data from API
2. Validate against schema
3. Transform and process
4. Update local files
5. Generate report
6. Commit changes to git
```
### Example: Claude Code-Optimized Skill
```yaml
---
name: github-issue-helper
description: Manage GitHub issues - create, update, search, and analyze issues using gh CLI. Use when working with GitHub repositories in development.
tools: Bash, Read, Write, Edit, Grep
---
# GitHub Issue Helper
Comprehensive GitHub issue management using gh CLI.
## Requirements
```bash
# Install GitHub CLI
brew install gh # macOS
# OR
apt install gh # Linux
# Authenticate
gh auth login
```
## Features
- **Create issues**: From templates or scratch
- **Search issues**: By label, state, author
- **Bulk operations**: Close, label, assign multiple issues
- **Analysis**: Generate reports, find patterns
- **Integration**: Link to commits, PRs, projects
## Commands
- "Create an issue for the bug in API endpoint"
- "Find all P0 issues assigned to me"
- "Close all issues labeled 'wontfix'"
- "Generate a weekly issue summary"
## Setup
No additional setup required if gh CLI is authenticated.
```
## Cross-Platform Skills
### Design Principles
To create skills that work across all platforms:
#### 1. Progressive Enhancement
Start with core functionality that works everywhere, add platform-specific features as available.
```markdown
## Core Features (All Platforms)
- Process uploaded/provided data
- Generate formatted output
- Validate inputs
## Enhanced Features (Claude Code Only)
- Fetch live data from APIs
- Update local files automatically
- Integrate with git workflow
```
#### 2. Graceful Degradation
Handle missing capabilities elegantly:
```markdown
## Setup
### Claude.ai / API
Upload your data file (CSV, JSON, or TXT)
### Claude Code
I can fetch data directly from your database or API.
Tell me the connection details.
```
#### 3. Platform Detection
Guide users based on their platform:
```markdown
## Platform Notes
**Claude.ai**: Upload files via the interface
**Claude API**: Provide data in the API request body
**Claude Code**: I can read files directly from your project
```
#### 4. Minimal Dependencies
Use standard library when possible:
```python
# ✅ Works everywhere
import json
from pathlib import Path
# ⚠️ Works in Claude Code only
import requests
import pandas
```
### Example: Universal Skill
```yaml
---
name: json-validator
description: Validate and format JSON data against schemas. Works with uploaded files, pasted data, or local files depending on platform.
tools: Read, Write
---
# JSON Validator
Validates JSON against schemas with detailed error reports.
## How to Use
**Claude.ai**:
1. Upload your JSON file
2. Upload your schema file (optional)
3. Ask: "Validate the JSON"
**Claude API**:
```python
message = client.messages.create(
messages=[{
"role": "user",
"content": f"Validate this JSON:\n{json_data}\n\nSchema:\n{schema}"
}]
)
```
**Claude Code**:
```
Validate JSON files in ./data/
```
## Features
- ✅ Schema validation (all platforms)
- ✅ Format checking (all platforms)
- ✅ Error highlighting (all platforms)
- ⚠️ Auto-fix suggestions (Claude Code only)
- ⚠️ Batch processing (Claude Code only)
No external dependencies required!
```
## Testing Across Platforms
### Test Checklist
- [ ] Test on Claude.ai (web interface)
- [ ] Test via Claude API (programmatic access)
- [ ] Test in Claude Code (CLI)
- [ ] Test with network disabled (API mode)
- [ ] Test with file uploads (Claude.ai mode)
- [ ] Test with local files (Claude Code mode)
- [ ] Verify error messages are clear on all platforms
- [ ] Check that platform-specific features degrade gracefully
### Platform-Specific Test Cases
**Claude.ai**:
- Upload various file formats
- Test with network restrictions
- Verify download generation works
- Test on mobile if applicable
**Claude API**:
- Test with no network access
- Verify offline operation
- Test with standard library only
- Check API response format
**Claude Code**:
- Test with project files
- Test bash commands
- Test package installation instructions
- Verify git integration
## Summary
### Choose Your Target
**Claude.ai**: Best for personal productivity skills that process documents
**Claude API**: Best for deterministic, offline data processing
**Claude Code**: Best for development workflows with full system access
### Design Patterns
**Single Platform**: Optimize for that platform's strengths
**Multi-Platform**: Use progressive enhancement and graceful degradation
**Universal**: Stick to core capabilities, document platform differences
### Key Takeaways
1. **Know your constraints**: Each platform has different capabilities
2. **Design accordingly**: Match skill design to platform capabilities
3. **Document clearly**: Tell users what works where
4. **Test thoroughly**: Verify on all target platforms
5. **Handle gracefully**: Degrade features when capabilities are missing
## Resources
- **Claude.ai**: https://claude.ai/skills
- **Claude API**: https://docs.anthropic.com/claude/docs/
- **Claude Code**: https://docs.claude.com/en/docs/claude-code/overview

656
skills/skill-creator/reference/skill-examples.md Normal file
View File

@@ -0,0 +1,656 @@
# Claude Skills Examples
Real-world examples of well-designed skills across different complexity levels and use cases.
## Table of Contents
1. [Simple Skills](#simple-skills) - Just SKILL.md, no scripts
2. [Skills with Scripts](#skills-with-scripts) - Including helper utilities
3. [Complex Skills](#complex-skills) - Full-featured with references
4. [Platform-Specific Skills](#platform-specific-skills) - Optimized for one platform
5. [Universal Skills](#universal-skills) - Work across all platforms
---
## Simple Skills
### Example 1: Commit Message Formatter
**Use Case**: Help developers write conventional commit messages
**Structure**:
```
commit-formatter/
└── SKILL.md
```
**SKILL.md**:
```markdown
---
name: commit-formatter
description: Format git commit messages following Conventional Commits. Use when writing commits or reviewing commit history for proper formatting.
---
# Commit Message Formatter
Helps create well-formatted git commit messages following the Conventional Commits specification.
## When to Use
- Writing new commit messages
- Reviewing existing commits for proper format
- Teaching team members commit conventions
- Generating changelogs
## Commit Format
```
<type>(<scope>): <subject>
<body>
<footer>
```
## Types
- **feat**: New feature for users
- **fix**: Bug fix
- **docs**: Documentation only changes
- **style**: Code style changes (formatting, semicolons)
- **refactor**: Code change that neither fixes a bug nor adds a feature
- **perf**: Performance improvement
- **test**: Adding or updating tests
- **chore**: Maintenance tasks (deps, configs)
- **ci**: CI/CD changes
## Subject Line Rules
- Use imperative mood ("add" not "added")
- No period at the end
- Keep under 50 characters
- Lowercase (except proper nouns)
## Body (Optional)
- Wrap at 72 characters
- Explain WHAT and WHY (not HOW)
- Separate from subject with blank line
## Footer (Optional)
- **Breaking changes**: `BREAKING CHANGE: <description>`
- **Issue references**: `Closes #123`, `Fixes #456`
- **Co-authors**: `Co-authored-by: Name <email>`
## Examples
### Simple Feature
```
feat(auth): add OAuth2 Google login
```
### Bug Fix with Body
```
fix(api): handle null user service response
The user service occasionally returns null when the user is not
found. This adds proper null checking and returns a 404 status.
```
### Breaking Change
```
feat(api)!: redesign authentication endpoints
BREAKING CHANGE: The /auth endpoint now requires POST instead of GET.
All clients must be updated to send POST requests with JSON body
containing username and password fields.
Migration guide: https://docs.example.com/v2-migration
Closes #456
```
### Multiple Issues
```
fix(ui): resolve button alignment in mobile view
Fixes several CSS issues affecting mobile users:
- Button text now wraps properly
- Icons align correctly with text
- Touch targets meet minimum 44px requirement
Fixes #789, #790, #791
```
## Interactive Mode
Just tell me what you changed, and I'll help format it:
**Example conversation**:
- You: "I added a new login page"
- Me: "Was this a new feature or a fix?"
- You: "New feature"
- Me: "What component/area does this affect?"
- You: "Authentication"
- Me: "Here's your commit message: `feat(auth): add login page`"
```
**Why This Works**:
- Clear, actionable instructions
- Concrete examples for different scenarios
- Covers edge cases (breaking changes, multiple issues)
- Action-oriented description triggers automatic use
- No dependencies or scripts needed
---
### Example 2: JSON Formatter
**Use Case**: Format and validate JSON data
**Structure**:
```
json-formatter/
└── SKILL.md
```
**SKILL.md**:
```markdown
---
name: json-formatter
description: Format, validate, and pretty-print JSON data. Use when working with JSON files, API responses, or config files that need formatting or validation.
---
# JSON Formatter
Format and validate JSON data with helpful error messages.
## When to Use
- Format messy JSON
- Validate JSON syntax
- Compare JSON structures
- Convert between compact and pretty formats
- Debug JSON parsing errors
## Features
### 1. Pretty Printing
Transform compact JSON into readable format:
**Input**:
```json
{"name":"John","age":30,"city":"NYC"}
```
**Output**:
```json
{
"name": "John",
"age": 30,
"city": "NYC"
}
```
### 2. Validation
Check for common JSON errors:
- Missing commas
- Trailing commas
- Unquoted keys
- Single quotes instead of double quotes
- Unescaped characters
### 3. Minification
Reduce JSON size for transmission:
**Input**:
```json
{
"users": [
{
"name": "John",
"age": 30
}
]
}
```
**Output**:
```json
{"users":[{"name":"John","age":30}]}
```
### 4. Structure Analysis
- Count objects, arrays, and primitives
- Find deeply nested paths
- Identify large values
- Detect duplicate keys
## Usage
Just paste or upload your JSON and tell me what you need:
- "Format this JSON"
- "Validate this JSON"
- "Minify this JSON"
- "What's wrong with this JSON?"
- "Compare these two JSON files"
## Common Fixes
### Trailing Comma
❌ `{"name": "John", "age": 30,}`
✅ `{"name": "John", "age": 30}`
### Single Quotes
❌ `{'name': 'John'}`
✅ `{"name": "John"}`
### Unquoted Keys
❌ `{name: "John"}`
✅ `{"name": "John"}`
### Missing Comma
❌ `{"name": "John" "age": 30}`
✅ `{"name": "John", "age": 30}`
## Tips
- Use JSON for configs (not YAML) when strict validation needed
- Keep nesting under 5 levels for readability
- Consider splitting large JSON files
- Use consistent key naming (camelCase or snake_case)
```
---
## Skills with Scripts
### Example 3: API Response Validator
**Use Case**: Validate API responses against schemas
**Structure**:
```
api-validator/
├── SKILL.md
├── scripts/
│ ├── __init__.py
│ ├── validator.py
│ └── schema_builder.py
└── README.md
```
**SKILL.md**:
```markdown
---
name: api-validator
description: Validate API responses against JSON schemas with detailed error reports. Use PROACTIVELY when testing or debugging REST APIs.
tools: Bash, Read, Write
model: sonnet
---
# API Response Validator
Comprehensive validation for API responses.
## Features
- Validate against JSON Schema
- Auto-generate schemas from examples
- Test status codes, headers, body
- Performance metrics
- Security checks
## Usage
### Validate a Response
```
Validate this API response:
{
"status": 200,
"body": {"user_id": 123, "name": "John"}
}
Against schema:
{
"type": "object",
"required": ["user_id", "name"],
"properties": {
"user_id": {"type": "integer"},
"name": {"type": "string"}
}
}
```
### Generate Schema
```
Generate a schema for this response:
{"user_id": 123, "name": "John", "email": "john@example.com"}
```
### Batch Validation
```
Validate all responses in ./tests/responses/
```
## Scripts
This skill includes Python scripts for deterministic validation:
- `validator.py`: Core validation logic
- `schema_builder.py`: Generate schemas from examples
Run manually:
```bash
python scripts/validator.py response.json schema.json
```
See README.md for detailed script documentation.
```
**scripts/validator.py**:
```python
#!/usr/bin/env python3
"""Validate JSON against JSON Schema."""
import argparse
import json
import sys
from pathlib import Path
from typing import Any, Dict, List, Tuple
def validate_json(data: Dict[str, Any], schema: Dict[str, Any]) -> Tuple[bool, List[str]]:
"""Validate JSON data against schema.
Returns:
Tuple of (is_valid, error_messages)
"""
errors = []
# Check required fields
if "required" in schema:
for field in schema["required"]:
if field not in data:
errors.append(f"Missing required field: {field}")
# Check field types
if "properties" in schema:
for field, field_schema in schema["properties"].items():
if field in data:
expected_type = field_schema.get("type")
actual_value = data[field]
if not check_type(actual_value, expected_type):
errors.append(
f"Field '{field}' has wrong type. "
f"Expected {expected_type}, got {type(actual_value).__name__}"
)
return len(errors) == 0, errors
def check_type(value: Any, expected_type: str) -> bool:
"""Check if value matches expected JSON type."""
type_map = {
"string": str,
"integer": int,
"number": (int, float),
"boolean": bool,
"array": list,
"object": dict,
"null": type(None),
}
expected_python_type = type_map.get(expected_type)
if expected_python_type is None:
return True # Unknown type, skip check
return isinstance(value, expected_python_type)
def main() -> int:
parser = argparse.ArgumentParser(description="Validate JSON against schema")
parser.add_argument("data_file", type=Path, help="JSON data file")
parser.add_argument("schema_file", type=Path, help="JSON schema file")
args = parser.parse_args()
# Load files
try:
data = json.loads(args.data_file.read_text())
schema = json.loads(args.schema_file.read_text())
except json.JSONDecodeError as e:
print(f"Error: Invalid JSON - {e}", file=sys.stderr)
return 1
except Exception as e:
print(f"Error: {e}", file=sys.stderr)
return 1
# Validate
is_valid, errors = validate_json(data, schema)
if is_valid:
print("✅ Validation passed")
return 0
else:
print("❌ Validation failed:")
for error in errors:
print(f" - {error}")
return 1
if __name__ == "__main__":
sys.exit(main())
```
**Why This Works**:
- Combines AI guidance with deterministic validation
- Scripts provide precise, repeatable checks
- Clear examples show usage patterns
- Works across platforms (with network in Code, offline in API)
---
## Complex Skills
### Example 4: Database Migration Helper
**Use Case**: Validate and generate database migrations
**Structure**:
```
db-migrator/
├── SKILL.md
├── scripts/
│ ├── __init__.py
│ ├── validate_migration.py
│ ├── generate_rollback.py
│ └── analyze_schema.py
└── references/
├── sql-best-practices.md
├── migration-patterns.md
└── examples.md
```
**SKILL.md**:
```markdown
---
name: db-migrator
description: Create and validate database migrations with automatic rollback generation. Use PROACTIVELY when designing schema changes or creating migration files.
tools: Bash, Read, Write, Edit
model: sonnet
---
# Database Migration Helper
Comprehensive toolkit for database migrations.
## When to Use
- Creating new migrations
- Validating migration safety
- Generating rollback scripts
- Reviewing schema changes
- Planning database refactoring
## Features
### 1. Migration Validation
Checks for:
- Breaking changes (column removal, type changes)
- Performance issues (missing indexes, table locks)
- Data integrity risks (missing constraints)
- Naming conventions
- SQL syntax
### 2. Rollback Generation
Automatically generates rollback scripts for:
- Table creation → DROP TABLE
- Column addition → ALTER TABLE DROP COLUMN
- Index creation → DROP INDEX
- Data migrations → Inverse operations
### 3. Schema Analysis
- Compare schemas across environments
- Identify drift
- Suggest optimizations
- Generate documentation
## Quick Start
### Create a Migration
```
Create a migration to add an email column to the users table
```
I'll generate:
- Forward migration (add column)
- Rollback migration (remove column)
- Validation checks
- Index recommendations
### Validate Existing Migration
```
Validate this migration:
[paste your SQL]
```
I'll check for safety issues and suggest improvements.
### Generate Rollback
```
Generate rollback for:
[paste forward migration]
```
## Best Practices
For detailed migration patterns and SQL best practices:
```
Read .claude-plugin/references/sql-best-practices.md
```
## Scripts
### validate_migration.py
Validates SQL migrations for safety:
```bash
python scripts/validate_migration.py migration.sql
```
Checks:
- Syntax errors
- Breaking changes
- Performance issues
- Security risks
### generate_rollback.py
Creates rollback scripts:
```bash
python scripts/generate_rollback.py migration.sql > rollback.sql
```
### analyze_schema.py
Compares schema files:
```bash
python scripts/analyze_schema.py schema1.sql schema2.sql
```
## References
- **sql-best-practices.md**: SQL coding standards and patterns
- **migration-patterns.md**: Common migration scenarios with examples
- **examples.md**: Real-world migration examples
Load as needed for detailed guidance.
```
**Why This Works**:
- Combines AI reasoning with automated checks
- References provide deep expertise without token cost
- Scripts handle deterministic tasks
- Clear separation of concerns
- Works great in Claude Code with full tool access
---
## Summary
### Choosing Skill Complexity
**Simple** (SKILL.md only):
- Documentation formatting
- Writing assistance
- Simple validation
- Template generation
**With Scripts**:
- Data validation
- File processing
- Format conversion
- Code generation
**Complex** (Full featured):
- Multi-step workflows
- Technical domains (databases, APIs)
- Integration with external tools
- Comprehensive validation
### Key Takeaways
1. **Start simple**: Most skills don't need scripts
2. **Add scripts**: When you need deterministic, repeatable operations
3. **Use references**: For detailed specs that don't need to be in context
4. **Test thoroughly**: Ensure skills work as expected
5. **Document well**: Clear examples help users and Claude
### Templates
Use these examples as templates for your own skills:
- Copy the structure
- Adapt the content
- Validate with the validator
- Test thoroughly
- Share with the community!

456
skills/skill-creator/reference/skill-specification.md Normal file
View File

@@ -0,0 +1,456 @@
# Claude Skills Technical Specification
Complete technical requirements and validation rules for Claude skills.
## File Structure
### Required Files
**SKILL.md** - The main skill definition file
- Must be named exactly `SKILL.md` (case-sensitive)
- Must be UTF-8 encoded
- Must start with YAML frontmatter
- Must contain content after frontmatter
### Optional Components
**scripts/** - Helper scripts and utilities
- Python, JavaScript, or bash scripts
- Should include `__init__.py` for Python packages
- Scripts should have execute permissions (Unix)
- Must not execute arbitrary code (no eval/exec)
**references/** - Reference documentation
- Markdown files with detailed specifications
- API documentation
- Database schemas
- Templates and examples
- Loaded on-demand to minimize token usage
**README.md** - Skill-specific documentation
- Installation instructions
- Usage examples
- Platform-specific notes
## YAML Frontmatter Specification
### Format
```yaml
---
name: skill-name
description: Brief description of what this skill does
---
```
### Required Fields
#### name (string, required)
- **Type**: String
- **Required**: Yes
- **Format**: Lowercase letters, numbers, hyphens only
- **Pattern**: `^[a-z0-9-]+$`
- **Min length**: 1 character
- **Max length**: 64 characters
- **Restrictions**:
- Cannot contain "anthropic" (case-insensitive)
- Cannot contain "claude" (case-insensitive)
- Cannot contain XML tags (`<` or `>`)
- Must not start or end with hyphen
- No consecutive hyphens
**Examples**:
- ✅ Valid: `git-helper`, `api-tester`, `doc-writer-pro`
- ❌ Invalid: `GitHelper` (not lowercase), `api_tester` (underscore), `my-anthropic-skill` (contains "anthropic")
#### description (string, required)
- **Type**: String
- **Required**: Yes
- **Min length**: 1 character (after trimming whitespace)
- **Max length**: 1024 characters
- **Restrictions**:
- Cannot be only whitespace
- Cannot contain XML tags (regex: `<[^>]+>`)
- Should explain WHAT the skill does
- Should explain WHEN to use it
**Best Practices**:
- Use action-oriented language for auto-invocation
- Include trigger keywords
- Be specific about capabilities
- Mention platform requirements if relevant
**Examples**:
- ✅ Good: "Create and validate git commit messages following Conventional Commits. Use when writing commits or reviewing commit history."
- ✅ Good: "Analyze API responses and generate test cases. Use PROACTIVELY when designing or testing REST APIs."
- ❌ Poor: "Helps with git" (too vague, no trigger info)
- ❌ Poor: "A tool" (doesn't explain what or when)
### Optional Fields
#### tools (string or array, optional)
Specifies which tools this skill should have access to.
- **Type**: String (comma-separated) or Array
- **Default**: All tools (if omitted)
- **Valid tools**:
- `Bash` - Execute shell commands
- `Read` - Read files
- `Write` - Write new files
- `Edit` - Edit existing files
- `Glob` - Find files by pattern
- `Grep` - Search file contents
- `WebFetch` - Fetch web pages
- `WebSearch` - Search the web
- `Task` - Launch subagents
**Examples**:
```yaml
# String format
tools: Bash, Read, Write
# Array format
tools:
- Bash
- Read
- Write
```
**Use Cases**:
- Restrict to Read/Write for documentation-only skills
- Include Bash for scripts that need command execution
- Include WebFetch/WebSearch for research skills
#### model (string, optional)
Specifies which model to use for this skill.
- **Type**: String
- **Default**: Inherits from parent context
- **Valid values**:
- `sonnet` - Claude Sonnet (balanced)
- `opus` - Claude Opus (most capable)
- `haiku` - Claude Haiku (fastest, most efficient)
- `inherit` - Use parent context's model
**Examples**:
```yaml
# Use Haiku for fast, simple tasks
model: haiku
# Use Sonnet for complex reasoning
model: sonnet
```
## Content Requirements
### Body Structure
The content after frontmatter should be well-structured markdown:
#### Recommended Sections
1. **Overview/Introduction**
- Brief explanation of the skill
- Use cases
2. **When to Use This Skill**
- Specific scenarios
- Trigger conditions
- Context where skill is most helpful
3. **Instructions/Workflow**
- Step-by-step guidance
- Clear action items
- Decision points
4. **Examples**
- Concrete use cases
- Input/output examples
- Edge cases
5. **Best Practices** (optional)
- Tips for optimal use
- Common patterns
6. **Troubleshooting** (optional)
- Common issues
- Solutions
- Error handling
### Markdown Guidelines
- Use proper heading hierarchy (don't skip levels)
- Use code blocks with language tags
- Use lists for steps and options
- Use emphasis (bold/italic) sparingly for clarity
- Include links to external resources if helpful
### Token Efficiency
**Inactive State** (Just frontmatter loaded):
- Target: 30-50 tokens
- The name and description should be concise
**Active State** (Full SKILL.md loaded):
- Keep main instructions focused
- Move detailed specs to references/
- Use progressive disclosure
**References** (Loaded on-demand):
- No token limit
- Can be very detailed
- Include comprehensive examples
- Add API specs, schemas, etc.
## File Size Limits
- **SKILL.md**: Recommended max 50KB (will warn above this)
- **Scripts**: Reasonable size (< 1MB each)
- **References**: No strict limit, but keep focused
- **Total package**: Recommended < 10MB
## Security Requirements
### Path Safety
All file operations must:
- Validate paths to prevent traversal attacks
- Use pathlib.Path for cross-platform compatibility
- Resolve paths and check they're within expected directories
- Never accept arbitrary user paths without validation
**Example** (Python):
```python
from pathlib import Path
def safe_path(base: Path, user_input: str) -> Path:
resolved = (base / user_input).resolve()
if not resolved.is_relative_to(base):
raise ValueError(f"Path traversal detected: {user_input}")
return resolved
```
### Input Validation
- Validate all user inputs
- Use allowlists instead of denylists
- Sanitize before processing
- Check types, ranges, formats
- Provide clear error messages
### Code Execution
- **Never** use `eval()` or `exec()`
- **Never** execute arbitrary user code
- Be cautious with `pickle` - prefer JSON
- Validate file contents before processing
- Use subprocess carefully with fixed commands
### Credentials and Secrets
- Never include credentials in skill files
- Use environment variables
- Document required env vars in README
- Add secrets to .gitignore
- Use permission rules in .claude/settings.json
## Validation Checklist
Use this checklist to ensure compliance:
### Frontmatter
- [ ] File starts with `---`
- [ ] Valid YAML syntax
- [ ] Contains `name` field
- [ ] Contains `description` field
- [ ] Name is lowercase with hyphens only
- [ ] Name is 1-64 characters
- [ ] Name doesn't contain "anthropic" or "claude"
- [ ] Description is 1-1024 characters
- [ ] Description is non-empty (no whitespace-only)
- [ ] No XML tags in name or description
- [ ] Optional fields (tools, model) are valid if present
### Body Content
- [ ] Content exists after frontmatter
- [ ] Reasonable length (not too short)
- [ ] Includes "When to Use" section
- [ ] Includes instructions/steps
- [ ] Includes examples
- [ ] Uses proper markdown formatting
- [ ] Headings are hierarchical
### Directory Structure
- [ ] SKILL.md exists
- [ ] If scripts/ exists, contains relevant files
- [ ] If scripts/ has Python files, includes __init__.py
- [ ] Scripts have execute permissions (Unix)
- [ ] If references/ exists, contains markdown files
- [ ] No sensitive files (credentials, keys)
### Security
- [ ] No eval/exec in scripts
- [ ] Path operations are safe
- [ ] Inputs are validated
- [ ] No hardcoded credentials
- [ ] No path traversal vulnerabilities
### Quality
- [ ] Clear, actionable instructions
- [ ] Concrete examples provided
- [ ] Error handling documented
- [ ] Platform notes if needed
- [ ] Tested on target platforms
## Platform-Specific Requirements
### Claude.ai
- User-level skills only
- Upload via Skills UI
- Network access varies by settings
- No shell access to system
### Claude API
- Workspace-level skills
- No network access by default
- No dynamic package installation
- Integrated via API configuration
### Claude Code
- Project (.claude/skills/) or user level (~/.claude/agents/)
- Full network access
- Can execute bash commands
- Full file system access
## Versioning
While not required, consider versioning your skills:
**In manifest.json**:
```json
{
"version": "1.2.0",
"changelog": "Added support for X"
}
```
**Semantic Versioning Recommended**:
- Major: Breaking changes
- Minor: New features (backward compatible)
- Patch: Bug fixes
## Distribution Formats
### ZIP Package
```
skill-name.zip
├── SKILL.md
├── manifest.json (optional)
├── README.md (optional)
├── scripts/
│ └── *.py
└── references/
└── *.md
```
### Directory Structure
```
skill-name/
├── SKILL.md
├── manifest.json (optional)
├── README.md (optional)
├── scripts/
│ └── *.py
└── references/
└── *.md
```
### Plugin Format (.claude-plugin/)
```
.claude-plugin/
├── SKILL.md
├── scripts/
└── references/
```
## Manifest File (Optional)
When packaging, you can include a manifest.json:
```json
{
"name": "skill-name",
"description": "Brief description",
"version": "1.0.0",
"packaged_at": "2025-01-15T10:30:00Z",
"format": "claude-skill",
"format_version": "1.0",
"includes_scripts": true,
"includes_references": true,
"tools": "Bash, Read, Write",
"model": "sonnet"
}
```
## Common Validation Errors
### Error: "SKILL.md must start with YAML frontmatter"
**Cause**: File doesn't start with `---`
**Fix**: Add frontmatter at the beginning:
```yaml
---
name: skill-name
description: Description here
---
```
### Error: "Invalid YAML in frontmatter"
**Cause**: YAML syntax error
**Fix**: Check indentation, quotes, special characters
- Strings with `:` need quotes
- Multi-line strings need `|` or `>`
- Indentation must be consistent
### Error: "Skill name must be lowercase with hyphens only"
**Cause**: Name has uppercase, underscores, spaces, or special chars
**Fix**: Use only lowercase letters, numbers, and hyphens
### Error: "Description too long"
**Cause**: Description exceeds 1024 characters
**Fix**: Shorten description, move details to body
### Error: "Required field 'name' missing"
**Cause**: Frontmatter doesn't include name field
**Fix**: Add `name: skill-name` to frontmatter
## Testing Your Skill
1. **Validate**: Run the validator
```bash
python .claude-plugin/scripts/validate_skill.py path/to/skill/
```
2. **Manual Testing**: Place skill and try using it
- Test basic functionality
- Test edge cases
- Test error handling
- Test on target platforms
3. **Script Testing**: If your skill includes scripts
- Test scripts independently
- Verify inputs/outputs
- Check error messages
- Test on different platforms
4. **Integration Testing**: Use skill in real scenarios
- Invoke automatically
- Invoke explicitly
- Test with references
- Test tool permissions
## Further Resources
- **Claude Skills Documentation**: https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview
- **Skills Blog Post**: https://claude.com/blog/skills
- **Skills Cookbook**: https://github.com/anthropics/claude-cookbooks/tree/main/skills
- **This Project**: https://github.com/jgardner04/claude-skills-skill