FoundryVTT/.claude/skills/.SKILL_TEMPLATE.md

---
name: Skill Name Here
description: Brief, specific description of what this skill does and when Claude should use it. Include trigger words and file types. Use when [specific scenarios]. Keywords: [relevant terms users might mention].
allowed-tools: Read, Grep, Glob
# Optional: Restrict which tools Claude can use when this skill is active
# Omit this field if the skill should follow standard permission model
# Common tool combinations:
# - Read-only: Read, Grep, Glob
# - File operations: Read, Write, Edit, Glob, Grep
# - Git operations: Bash(git status), Bash(git diff), Bash(git log)
# - Execution: Bash, Read, Write
---

# Skill Name Here

> **Purpose**: One-sentence explanation of the skill's primary purpose.

## Quick Start

Brief example of the most common use case:

```language
# Quick example code or command
example_command()
```

## Instructions

Detailed step-by-step guidance for Claude on how to use this skill:

1. **First step**: What to do first
   - Use [specific tool] to gather information
   - Check for [specific conditions]

2. **Second step**: Next action
   - Process the information
   - Apply [specific logic or rules]

3. **Third step**: Final actions
   - Generate output in [specific format]
   - Verify [specific criteria]

## When to Use This Skill

Claude should activate this skill when:
- User mentions [specific keywords]
- Working with [specific file types or patterns]
- Task involves [specific operations]
- User asks about [specific topics]

## Requirements

### Prerequisites
- Required tools or dependencies
- Expected file structures
- Necessary permissions

### Environment
- Operating system considerations
- Path requirements
- Configuration needs

## Examples

### Example 1: Common Use Case
```language
# Code example showing typical usage
def example_function():
    """Clear docstring."""
    pass
```

**Context**: When to use this approach
**Expected Output**: What Claude should produce

### Example 2: Advanced Use Case
```language
# More complex example
advanced_example()
```

**Context**: When this is needed
**Expected Output**: Expected result

## Best Practices

### Do's
- ✅ Specific recommendation with rationale
- ✅ Another best practice
- ✅ Tool usage guidelines

### Don'ts
- ❌ What to avoid and why
- ❌ Common mistakes
- ❌ Anti-patterns

## Output Format

Specify the expected output structure:

```markdown
## Section Title
- Item 1
- Item 2

### Subsection
Details here...
```

Or for code:
```language
// Expected code structure
class Example {
    // Implementation
}
```

## Error Handling

Common issues and solutions:

### Issue 1: Specific Problem
**Symptoms**: What the user sees
**Cause**: Why it happens
**Solution**: How to fix it

### Issue 2: Another Problem
**Symptoms**: Description
**Cause**: Root cause
**Solution**: Fix steps

## Related Files

Link to supporting documentation or resources:
- [Additional reference](reference.md) - Detailed API documentation
- [Examples collection](examples.md) - More usage examples
- [Advanced guide](advanced.md) - Deep dive into complex scenarios

## Tool Permissions

This skill uses the following tools:
- **Read**: For reading file contents
- **Grep**: For searching code patterns
- **Glob**: For finding files

> **Note**: If `allowed-tools` is specified in frontmatter, Claude can only use those tools without asking permission when this skill is active.

## Version History

Track changes to this skill:

- **v1.0.0** (YYYY-MM-DD): Initial release
  - Core functionality
  - Basic examples

- **v1.1.0** (YYYY-MM-DD): Enhancement description
  - New feature added
  - Improved handling of edge case

## Testing Checklist

Before considering this skill complete:

- [ ] Skill activates on appropriate prompts
- [ ] Instructions are clear and unambiguous
- [ ] Examples work as documented
- [ ] Error handling covers common issues
- [ ] Output format is consistent
- [ ] Tool permissions are appropriate
- [ ] Description includes trigger keywords
- [ ] Related files are accessible
- [ ] Team members can use successfully

## Notes

Additional context, tips, or warnings:

- Important consideration about usage
- Performance implications
- Security considerations
- Compatibility notes

---

## Template Usage Guidelines

### Writing the Description (Frontmatter)

The `description` field is **critical** for skill discovery. Follow these rules:

1. **Be Specific**: Include exact terms users would say
   - ❌ "Helps with files"
   - ✅ "Process PDF files, extract text, fill forms. Use when working with PDFs or document extraction."

2. **Include Triggers**: Add keywords that should activate the skill
   - File types: PDF, .xlsx, .json
   - Operations: analyze, generate, convert, test
   - Technologies: React, Python, SQL

3. **Combine What + When**:
   ```yaml
   description: [What it does]. Use when [specific scenarios]. Keywords: [terms].
   ```

### Choosing Allowed Tools

Only include `allowed-tools` if you want to **restrict** Claude's capabilities:

- **Read-only skill**: `allowed-tools: Read, Grep, Glob`
- **Code modification**: `allowed-tools: Read, Edit, Grep, Glob`
- **Full file operations**: `allowed-tools: Read, Write, Edit, Glob, Grep, Bash`
- **Omit field**: For standard permission model (recommended default)

### Organizing Supporting Files

For multi-file skills, structure as:

```
skill-name/
├── SKILL.md           (main skill file)
├── reference.md       (detailed API/reference docs)
├── examples.md        (extensive examples)
├── advanced.md        (complex scenarios)
└── scripts/           (helper scripts)
    ├── helper.py
    └── validator.sh
```

Reference them in SKILL.md with relative paths: `[reference](reference.md)`

### Writing Clear Instructions

1. **Use numbered steps** for sequential processes
2. **Use bullet points** for non-sequential information
3. **Bold key actions** for emphasis
4. **Include decision points**: "If X, then do Y; otherwise do Z"
5. **Specify tools to use**: "Use the Read tool to..." not just "Read the file"

### Testing Your Skill

After creating a skill, test with prompts that:
1. Match the description exactly
2. Use trigger keywords
3. Mention related file types
4. Describe the scenario differently
5. Come from a teammate's perspective

### Progressive Disclosure

Claude loads files **on demand**. Structure content so:
- Essential information is in SKILL.md
- Detailed references are in separate files
- Claude only reads what it needs

Example:
```markdown
For basic usage, follow the instructions above.
For advanced scenarios, see [advanced.md](advanced.md).
For complete API reference, see [reference.md](reference.md).
```

---

## Quick Reference Card

| Element | Purpose | Required |
|---------|---------|----------|
| `name` | Skill display name | ✅ Yes |
| `description` | Discovery & when to use | ✅ Yes |
| `allowed-tools` | Restrict tool access | ❌ Optional |
| Instructions | Step-by-step guidance | ✅ Yes |
| Examples | Concrete usage demos | ✅ Recommended |
| Best Practices | Do's and don'ts | ✅ Recommended |
| Error Handling | Troubleshooting | ❌ Optional |
| Related Files | Supporting docs | ❌ As needed |
| Version History | Track changes | ✅ Recommended |

---

**Remember**: Skills are about **packaging expertise** so Claude can apply specialized knowledge at the right time. Keep them focused, clear, and well-tested.