From 42b20ade4991f10d5869bf2e88f44d0d6c8e954b Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sun, 30 Nov 2025 08:25:55 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 12 + README.md | 3 + plugin.lock.json | 64 ++ skills/skill-creator/LICENSE.txt | 176 +++++ skills/skill-creator/README.md | 64 ++ skills/skill-creator/SKILL.md | 488 +++++++++++++ .../reference/platform-differences.md | 618 +++++++++++++++++ .../skill-creator/reference/skill-examples.md | 656 ++++++++++++++++++ .../reference/skill-specification.md | 456 ++++++++++++ 9 files changed, 2537 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 plugin.lock.json create mode 100644 skills/skill-creator/LICENSE.txt create mode 100644 skills/skill-creator/README.md create mode 100644 skills/skill-creator/SKILL.md create mode 100644 skills/skill-creator/reference/platform-differences.md create mode 100644 skills/skill-creator/reference/skill-examples.md create mode 100644 skills/skill-creator/reference/skill-specification.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..468b612 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -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" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..641d3e7 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# jgardner04-skills + +Collection of custom skills for enhancing Claude's capabilities across various domains diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..a6cf386 --- /dev/null +++ b/plugin.lock.json @@ -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": [] + } +} \ No newline at end of file diff --git a/skills/skill-creator/LICENSE.txt b/skills/skill-creator/LICENSE.txt new file mode 100644 index 0000000..7be6cae --- /dev/null +++ b/skills/skill-creator/LICENSE.txt @@ -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 diff --git a/skills/skill-creator/README.md b/skills/skill-creator/README.md new file mode 100644 index 0000000..183eb99 --- /dev/null +++ b/skills/skill-creator/README.md @@ -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. diff --git a/skills/skill-creator/SKILL.md b/skills/skill-creator/SKILL.md new file mode 100644 index 0000000..a040b8b --- /dev/null +++ b/skills/skill-creator/SKILL.md @@ -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: `(): ` +- 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: ` +- 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! diff --git a/skills/skill-creator/reference/platform-differences.md b/skills/skill-creator/reference/platform-differences.md new file mode 100644 index 0000000..0b962df --- /dev/null +++ b/skills/skill-creator/reference/platform-differences.md @@ -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 diff --git a/skills/skill-creator/reference/skill-examples.md b/skills/skill-creator/reference/skill-examples.md new file mode 100644 index 0000000..5c04454 --- /dev/null +++ b/skills/skill-creator/reference/skill-examples.md @@ -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 + +``` +(): + + + +