Initial commit

2025-11-30 08:38:32 +08:00
commit 9b73455071
8 changed files with 1387 additions and 0 deletions
--- a/skills/skill-creator/REFERENCE.md
+++ b/skills/skill-creator/REFERENCE.md
@@ -0,0 +1,498 @@
+# Skill Creator Reference
+
+Comprehensive reference for creating Claude Code skills.
+
+## Table of Contents
+
+- [Validation Rules](#validation-rules)
+- [YAML Frontmatter Specification](#yaml-frontmatter-specification)
+- [Description Best Practices](#description-best-practices)
+- [File Organization](#file-organization)
+- [Tool Restrictions](#tool-restrictions)
+- [Testing Skills](#testing-skills)
+
+## Validation Rules
+
+### Name Requirements
+
+**Format**: `^[a-z0-9-]+$`
+
+- Only lowercase letters (a-z)
+- Numbers (0-9)
+- Hyphens (-)
+- No spaces, underscores, or special characters
+- Maximum length: 64 characters
+
+**Valid examples**:
+- `pdf-processor`
+- `commit-helper`
+- `log-analyzer-2`
+- `api-client-gen`
+
+**Invalid examples**:
+- `PDF_Processor` (uppercase and underscore)
+- `commit helper` (space)
+- `log.analyzer` (period)
+- `api-client!` (special character)
+
+### Description Requirements
+
+**Length**: Maximum 1024 characters
+
+**Must include**:
+1. What the skill does (capabilities)
+2. When to use it (triggers)
+3. Key terms for discovery
+
+**Structure**:
+```
+[What it does]. [When to use it]. [Optional: Requirements].
+```
+
+**Good example**:
+```
+Extract text and tables from PDF files, fill forms, merge documents.
+Use when working with PDF files, forms, or document extraction.
+Requires pypdf and pdfplumber packages.
+```
+
+**Poor example**:
+```
+Helps with documents.
+```
+
+### YAML Frontmatter Rules
+
+**Structure**:
+```yaml
+---
+name: skill-name
+description: Skill description
+allowed-tools: Tool1, Tool2, Tool3  # Optional
+---
+```
+
+**Rules**:
+- Must start with `---` on line 1
+- Must end with `---` before content starts
+- Use spaces, not tabs
+- Required fields: `name`, `description`
+- Optional fields: `allowed-tools`
+- Follow YAML syntax strictly
+
+**Common errors**:
+```yaml
+# Error: Missing opening ---
+name: skill-name
+---
+
+# Error: Tab character instead of spaces
+---
+name:	skill-name  # <- Tab here
+---
+
+# Error: Unquoted string with special chars
+---
+description: It's a skill  # <- Apostrophe breaks YAML
+---
+
+# Fix: Quote strings with special chars
+---
+description: "It's a skill"
+---
+```
+
+## YAML Frontmatter Specification
+
+### Required Fields
+
+#### name
+- Type: String
+- Format: `^[a-z0-9-]+$`
+- Max length: 64 characters
+- Must be unique within the skill directory
+
+#### description
+- Type: String
+- Max length: 1024 characters
+- Should be descriptive and include triggers
+
+### Optional Fields
+
+#### allowed-tools
+- Type: String (comma-separated) or Array
+- Valid tools: Read, Write, Edit, Glob, Grep, Bash, etc.
+- Restricts which tools Claude can use with this skill
+
+**String format**:
+```yaml
+allowed-tools: Read, Grep, Glob
+```
+
+**Array format**:
+```yaml
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+```
+
+## Description Best Practices
+
+### Include What and When
+
+**Structure**: `[Capabilities]. [When to use]. [Requirements].`
+
+### Use Specific Triggers
+
+Include terms users would actually say:
+
+**Good**:
+- "working with Excel files"
+- "analyzing log files"
+- "creating API clients"
+- "when the user mentions PDFs"
+
+**Poor**:
+- "for data"
+- "helps with files"
+- "general purpose"
+
+### Examples by Domain
+
+#### File Processing
+```
+Process and analyze [file type] files, [specific operations].
+Use when working with [file extensions], [user terms], or [tasks].
+```
+
+#### Development Tools
+```
+[Action] for [technology/framework], [specific features].
+Use when [development task], [user scenario], or [technical context].
+```
+
+#### Analysis Skills
+```
+Analyze [data type] for [patterns/metrics], [output format].
+Use when [analysis task], [debugging scenario], or [investigation type].
+```
+
+## File Organization
+
+### Basic Structure
+
+```
+skill-name/
+└── SKILL.md (required)
+```
+
+### With Supporting Files
+
+```
+skill-name/
+├── SKILL.md (required)
+├── REFERENCE.md (optional - detailed docs)
+├── EXAMPLES.md (optional - more examples)
+├── scripts/
+│   ├── helper.py
+│   └── validator.js
+└── templates/
+    ├── template1.txt
+    └── template2.md
+```
+
+### File Naming Conventions
+
+- Use lowercase
+- Use hyphens for spaces
+- Use descriptive names
+- Group by type in subdirectories
+
+**Good**:
+- `scripts/validate-input.py`
+- `templates/api-client-template.ts`
+- `docs/advanced-usage.md`
+
+**Poor**:
+- `Scripts/ValidateInput.py`
+- `template.txt`
+- `file1.md`
+
+### Referencing Files
+
+Use relative paths from SKILL.md:
+
+```markdown
+See [detailed documentation](REFERENCE.md).
+For examples, check [EXAMPLES.md](EXAMPLES.md).
+
+Run the helper:
+```bash
+python scripts/helper.py
+```
+```
+
+## Tool Restrictions
+
+Use `allowed-tools` to limit tool access for safety and focus.
+
+### Common Patterns
+
+#### Read-Only Skills
+```yaml
+allowed-tools: Read, Grep, Glob
+```
+
+Use for:
+- Analysis tasks
+- Log investigation
+- Code review
+- Documentation reading
+
+#### Analysis with Execution
+```yaml
+allowed-tools: Read, Grep, Glob, Bash
+```
+
+Use for:
+- Data analysis that needs computation
+- Test execution
+- Build analysis
+
+#### Limited Write Access
+```yaml
+allowed-tools: Read, Write, Grep, Glob
+```
+
+Use for:
+- Report generation
+- Template expansion
+- Safe file creation
+
+### Available Tools
+
+Common tools you can restrict to:
+- **Read**: Read file contents
+- **Write**: Create new files
+- **Edit**: Modify existing files
+- **Glob**: Find files by pattern
+- **Grep**: Search file contents
+- **Bash**: Execute shell commands
+- **WebFetch**: Fetch web content
+- **WebSearch**: Search the web
+
+### When to Use Tool Restrictions
+
+**Use restrictions when**:
+- Skill should be read-only
+- Skill has limited scope
+- Security is important
+- You want to prevent accidental modifications
+
+**Don't restrict when**:
+- Skill needs full flexibility
+- Multiple operations required
+- User might need varied access
+
+## Testing Skills
+
+### Pre-Testing Checklist
+
+Before testing a new skill:
+
+1. **Validate YAML**:
+   ```bash
+   head -n 20 SKILL.md
+   # Check frontmatter format
+   ```
+
+2. **Check file location**:
+   ```bash
+   # Personal
+   ls ~/.claude/skills/skill-name/SKILL.md
+
+   # Project
+   ls .claude/skills/skill-name/SKILL.md
+
+   # Plugin
+   ls plugin-name/skills/skill-name/SKILL.md
+   ```
+
+3. **Verify name format**:
+   - Lowercase, numbers, hyphens only
+   - No spaces or special characters
+
+4. **Check description**:
+   - Includes what and when
+   - Contains trigger terms
+   - Under 1024 characters
+
+### Testing Process
+
+1. **Restart Claude Code**:
+   ```bash
+   # Skills load at startup
+   claude
+   ```
+
+2. **Test with trigger phrases**:
+   - Use terms from your description
+   - Ask questions that match "when to use"
+   - Vary phrasing to test discovery
+
+3. **Verify activation**:
+   - Skill should activate automatically
+   - Claude should follow instructions
+   - Supporting files should load when referenced
+
+4. **Test edge cases**:
+   - Invalid inputs
+   - Missing dependencies
+   - Error conditions
+
+### Debug Mode
+
+Run with debug flag to see skill loading:
+
+```bash
+claude --debug
+```
+
+Look for:
+- Skill discovery messages
+- Loading errors
+- YAML parse errors
+- File not found errors
+
+### Common Test Scenarios
+
+#### Scenario 1: Does it activate?
+```
+User: [Use trigger phrase from description]
+Expected: Skill activates and provides help
+```
+
+#### Scenario 2: Are restrictions working?
+```
+User: [Request that needs restricted tool]
+Expected: Permission denied or alternative approach
+```
+
+#### Scenario 3: Do supporting files load?
+```
+User: [Ask question requiring reference docs]
+Expected: Claude references the supporting file
+```
+
+## Troubleshooting
+
+### Skill Doesn't Activate
+
+**Check**: Description specificity
+- Add more trigger terms
+- Be more explicit about when to use
+- Include user vocabulary
+
+**Check**: YAML validity
+```bash
+# View frontmatter
+cat SKILL.md | head -n 10
+```
+
+**Check**: File location
+```bash
+# Verify SKILL.md exists in correct location
+ls [path]/SKILL.md
+```
+
+### YAML Parse Errors
+
+**Common causes**:
+- Tabs instead of spaces
+- Missing quotes around special characters
+- Invalid structure
+- Missing opening/closing `---`
+
+**Fix**:
+```yaml
+# Before (broken)
+---
+description: It's broken
+---
+
+# After (fixed)
+---
+description: "It's fixed"
+---
+```
+
+### Tool Restrictions Not Working
+
+**Verify syntax**:
+```yaml
+# Correct
+allowed-tools: Read, Grep, Glob
+
+# Also correct
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+```
+
+**Check tool names**:
+- Use exact tool names (case-sensitive)
+- Common names: Read, Write, Edit, Bash, Grep, Glob
+- Separate with commas in string format
+
+### Supporting Files Not Loading
+
+**Check paths**:
+- Use relative paths from SKILL.md
+- Use forward slashes (/)
+- Don't use absolute paths
+
+**Check file exists**:
+```bash
+cd skill-directory
+ls -la
+# Verify all referenced files exist
+```
+
+## Best Practices Summary
+
+### DO
+
+- Keep skills focused on one capability
+- Write specific, detailed descriptions
+- Include trigger terms users would say
+- Use tool restrictions for safety
+- Provide concrete examples
+- Test thoroughly before sharing
+- Document requirements clearly
+- Use progressive disclosure (supporting files)
+
+### DON'T
+
+- Create vague, generic descriptions
+- Use invalid characters in names
+- Make skills too broad
+- Forget to include "when to use"
+- Skip validation before testing
+- Use absolute paths for supporting files
+- Mix tabs and spaces in YAML
+- Omit error handling guidance
+
+## Version History
+
+When documenting skill changes, use semantic versioning:
+
+```markdown
+## Version History
+- v2.0.0 (2025-11-07): Breaking changes to API
+- v1.1.0 (2025-10-15): Added new features
+- v1.0.0 (2025-10-01): Initial release
+```
+
+This helps team members understand what changed between versions.