shared

Original source / Raw SKILL.md

---
name: shared
description: Platform-agnostic skills including skill creation templates and best practices. Use when creating new skills or improving existing ones.
allowed-tools: [Read, Write, Glob, Grep, Bash]
---

# Shared Skills

Platform-agnostic skills that work across iOS, macOS, and other Apple platforms. This category provides foundational tools for extending Claude Code's capabilities.

## When This Skill Activates

Use this skill when the user:
- Wants to create a new Claude Code skill
- Asks about skill structure or organization
- Wants to improve or refactor existing skills
- Needs help with skill modularization
- Asks about skill best practices or templates

## Available Modules

Read relevant module files based on the user's needs:

### skill-creator/
Templates and guidance for creating well-structured Claude Code skills.
- Skill structure and organization patterns
- YAML front matter configuration
- Modularization strategies
- Templates for simple and complex skills
- Best practices and common pitfalls

## How to Use

1. Identify user's need from their question
2. Read relevant module files from subdirectories
3. Apply the guidance to their specific context
4. Provide examples from existing skills when helpful

## Example Workflow

**User wants to create a new skill:**
1. Read `skill-creator/SKILL.md` for the full creation process
2. Determine skill complexity (simple vs modularized)
3. Guide through front matter, structure, and content
4. Reference existing skills as examples


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### skill-creator/SKILL.md

```markdown
---
name: skill-creator
description: Guides you through creating well-structured Claude Code skills with proper modularization, templates, and best practices. Use when creating new skills or improving existing ones.
allowed-tools: [Read, Write, Glob, Grep, Bash]
---

# Skill Creator

Helps you create well-structured, modularized Claude Code skills with best practices.

## When This Skill Activates

Use this skill when the user:
- Wants to create a new skill
- Asks about skill structure or organization
- Wants to improve or refactor existing skills
- Needs help with skill modularization
- Asks about skill best practices

## Skill Creation Process

### 1. Understand Requirements

Ask the user:
- **Purpose**: What should this skill do?
- **Activation**: When should it activate?
- **Tools**: What tools will it need? (Read, Write, Edit, Glob, Grep, Bash, WebFetch, etc.)
- **Scope**: Is it project-specific or general-purpose?
- **Complexity**: Will it need reference files or can it be self-contained?

### 2. Plan the Skill Structure

Based on complexity:

**Simple Skills** (Self-contained):
```
.claude/skills/skill-name/
└── SKILL.md
```

**Complex Skills** (Modularized):
```
.claude/skills/skill-name/
├── SKILL.md                  # Main skill definition
├── reference-1.md           # Supporting reference
├── reference-2.md           # Additional reference
└── examples.md              # Code examples/templates
```

### 3. Create the Main SKILL.md

The main SKILL.md should include:

#### Front Matter (Required)
```yaml
---
name: skill-name
description: Brief description of what the skill does and when to use it
allowed-tools: [Read, Write, Edit]
---
```

**Front Matter Fields:**
- `name`: kebab-case skill name (e.g., `code-reviewer`, `ui-audit`)
- `description`: 1-2 sentences describing the skill and when to use it
- `allowed-tools`: Array of tools the skill can use

**Common Tool Combinations:**
- **Read-only analysis**: `[Read, Glob, Grep]`
- **Code modification**: `[Read, Write, Edit]`
- **Full access**: `[Read, Write, Edit, Glob, Grep, Bash]`
- **Web research**: `[Read, Glob, Grep, WebFetch]`

#### Main Content Structure

```markdown
# Skill Name

Brief description of what this skill does.

## When This Skill Activates

Use this skill when the user:
- [Specific trigger 1]
- [Specific trigger 2]
- [Specific trigger 3]

## Process/Workflow

### 1. Step One
- Instructions for first step
- What to check or do
- Expected outputs

### 2. Step Two
- Instructions for second step
- References to supporting files if needed

### 3. Output Format

How to present results to the user.

## References

Links to relevant documentation, files, or resources.
```

### 4. Create Supporting Reference Files

For complex skills, create modular reference files:

**When to Modularize:**
- Main SKILL.md exceeds 300-400 lines
- Contains extensive checklists or examples
- Has multiple distinct topics/categories
- Would benefit from focused reference materials

**Common Reference File Types:**
- **Checklists**: `checklist.md`, `review-checklist.md`
- **Patterns**: `patterns.md`, `anti-patterns.md`
- **Examples**: `examples.md`, `templates.md`
- **Quick References**: `quick-ref.md`, `commands.md`
- **Guidelines**: `guidelines.md`, `standards.md`

**Reference File Structure:**
```markdown
# Reference Topic

Brief description of this reference.

## Section 1

### Subsection
- Checklist items
- Code examples
- Explanations

## Section 2

[Content organized logically]

## References
[External links if needed]
```

### 5. Link References in Main SKILL.md

In the main SKILL.md, reference supporting files:

```markdown
### 2. Load Reference Materials

Before starting, familiarize yourself with these references:

- **patterns.md** - Common patterns and anti-patterns
- **examples.md** - Code examples and templates
- **checklist.md** - Comprehensive review checklist
```

## Skill Writing Best Practices

### Clear Activation Triggers

```markdown
## When This Skill Activates

Use this skill when the user:
- Asks for code review or quality check
- Mentions "best practices" or "refactoring"
- Wants to improve code quality
- Requests architecture review
```

### Actionable Instructions

```markdown
// ❌ Vague
- Check the code

// ✅ Specific
- Check for force unwrapping (!)
- Verify all optionals use safe unwrapping patterns
- Flag any instances for review with line numbers
```

### Examples and Templates

Always provide:
- ✅ Good examples (what to do)
- ❌ Bad examples (what to avoid)
- Explanations (why it matters)

```markdown
### Pattern Example

#### ❌ Anti-pattern
// Bad code example
let value = optional!

#### ✅ Good pattern
// Good code example
guard let value = optional else { return }

#### Why?
Force unwrapping crashes if nil. Guard provides safe unwrapping.
```

### Structured Output Formats

Provide clear output templates:

```markdown
## Output Format

Present findings in this structure:

### ✅ Strengths
- [List strengths]

### ⚠️ Issues Found
**[Category]**
**[Priority]: [File:Line]** - [Description]
// Current code
// Suggested fix
// Reason

### 📋 Recommendations
1. High priority items
2. Medium priority items
3. Low priority items
```

### Tool Selection

Choose appropriate tools:

| Task | Tools |
|------|-------|
| Reading code | `Read, Glob, Grep` |
| Modifying code | `Read, Write, Edit` |
| Running tests | `Read, Bash` |
| Web research | `WebFetch` |
| File operations | `Read, Write, Glob` |

### Checklists

Use checklists for systematic reviews:

```markdown
### Review Checklist

#### Category 1
- [ ] Check item 1
- [ ] Check item 2
- [ ] Check item 3

#### Category 2
- [ ] Check item 4
- [ ] Check item 5
```

## Example Skills

### Simple Skill Example

```yaml
---
name: greeting-responder
description: Responds to user greetings with helpful information about the project
allowed-tools: [Read]
---

# Greeting Responder

Provides helpful project context when users greet Claude.

## When This Skill Activates

Use this skill when the user:
- Says "hello", "hi", or similar greetings
- Asks "what can you help with?"

## Process

1. Greet the user warmly
2. Provide brief overview of the project
3. List 3-5 common tasks you can help with
4. Invite them to ask questions

## Example Output

"Hello! I can help you with this Swift/iOS project. Here are some things I can do:

- Review code for best practices
- Help implement new features
- Debug issues
- Refactor code
- Write tests

What would you like to work on?"
```

### Complex Skill Example

See the existing `coding-best-practices` or `ui-review` skills as examples of well-modularized complex skills.

## Skill Maintenance

### When to Refactor

Refactor a skill when:
- Main SKILL.md exceeds 400-500 lines
- Adding new content becomes difficult
- Multiple distinct topics exist
- Reference material is repeated
- Finding information takes too long

### How to Refactor

1. **Identify logical sections** in the main SKILL.md
2. **Extract sections** into focused reference files
3. **Update main SKILL.md** to reference new files
4. **Test the skill** to ensure references work
5. **Update descriptions** if scope changed

### File Organization

```
.claude/skills/skill-name/
├── SKILL.md                      # Main entry point
├── process.md                    # Detailed workflow
├── patterns/
│   ├── good-patterns.md
│   └── anti-patterns.md
├── references/
│   ├── checklist.md
│   └── examples.md
└── templates/
    └── output-template.md
```

## Testing Your Skill

After creating a skill:

1. **Verify metadata**: Check front matter is valid YAML
2. **Test activation**: Ensure description triggers appropriately
3. **Check references**: Verify all referenced files exist
4. **Run through workflow**: Follow the process end-to-end
5. **Validate output**: Ensure output format is clear and useful

## Common Pitfalls

### ❌ Avoid

- Vague activation criteria
- Missing tool permissions
- Overly complex single-file skills
- No examples or templates
- Unclear output formats
- Broken reference links

### ✅ Do

- Clear, specific activation triggers
- Appropriate tool selection
- Modularize complex skills
- Provide examples for everything
- Define structured output formats
- Keep references organized

## Skill Naming Conventions

**Name Format**: `kebab-case`

**Good Names:**
- `code-reviewer`
- `ui-audit`
- `test-generator`
- `api-analyzer`

**Bad Names:**
- `CodeReviewer` (PascalCase)
- `code_reviewer` (snake_case)
- `reviewer` (too vague)
- `cr` (too abbreviated)

## Templates

See the following reference files for templates:
- **skill-template.md** - Basic skill template
- **complex-skill-template.md** - Modularized skill template

## References

- [Claude Code Skills Documentation](https://docs.claude.com/claude-code/skills)
- Existing skills in `.claude/skills/` for examples
- This project's `coding-best-practices` and `ui-review` skills

## Notes

- Keep skills focused on a single purpose
- Use modularization for maintainability
- Provide clear examples and templates
- Test skills after creation
- Update skills as needs evolve

```