my-skills

Documentation

# My Skills

Personal collection of custom [Claude Code](https://claude.com/code) agent skills.

## Overview

This plugin provides a collection of specialized agent skills for Claude Code, enabling automated workflows, utilities, and custom capabilities tailored to personal development needs.

## Installation

### From Local Repository

```bash
# User scope (available across all projects)
claude plugin install /Users/oscar/ghq/github.com/ypwu1/my_skills --scope user

# Project scope (shared with team via git)
claude plugin install /Users/oscar/ghq/github.com/ypwu1/my_skills --scope project

# Local scope (project-specific, gitignored)
claude plugin install /Users/oscar/ghq/github.com/ypwu1/my_skills --scope local
```

### From GitHub (after publishing)

```bash
claude plugin install my-skills@ypwu1
```

## Available Skills

| Skill | Invocation | Description |
|-------|-----------|-------------|
| Example Utility | `/my-skills:example-utility` | Simple utility skill template |
| Example Workflow | `/my-skills:example-workflow` | Complex workflow with bundled resources |

## Adding New Skills

### Quick Start

1. Create a new directory in `skills/` with your skill name (kebab-case)
2. Add a `SKILL.md` file with YAML frontmatter:

```markdown
---
name: your-skill-name
description: What your skill does and when to use it. Be specific about triggers and use cases.
---

# Your Skill Instructions

Write clear, imperative instructions for Claude...
```

3. Test your skill:
```bash
claude --plugin-dir /Users/oscar/ghq/github.com/ypwu1/my_skills
```

### Skill Patterns

#### Simple Utility Pattern

Use `skills/example-utility/` as a template for:
- Single-purpose tasks
- Quick transformations
- Simple validations
- Straightforward operations

Structure:
```
your-skill/
└── SKILL.md
```

#### Complex Workflow Pattern

Use `skills/example-workflow/` as a template for:
- Multi-step processes
- External script execution
- Reference documentation needs
- Template/asset requirements

Structure:
```
your-skill/
├── SKILL.md
├── scripts/          # Executable scripts
├── references/       # Documentation
└── assets/          # Templates, configs
```

### Skill Best Practices

1. **Name**: Use kebab-case (e.g., `code-reviewer`, `pdf-processor`)
2. **Description**: Include BOTH what it does AND when to use it
   - ✅ "Format Python code using Black. Use when working with Python files that need formatting, before commits, or when style consistency is needed."
   - ❌ "Formats Python code"
3. **Keep SKILL.md under 500 lines** - use bundled resources for longer content
4. **Use imperative form**: "Format code", not "Formatting code"
5. **Test thoroughly** before committing

### Bundled Resources

When adding bundled resources:

**Scripts** (`scripts/` directory):
- Make executable: `chmod +x scripts/your-script.sh`
- Include proper shebang: `#!/usr/bin/env bash`
- Use `${CLAUDE_PLUGIN_ROOT}` for plugin paths
- Handle errors gracefully

**References** (`references/` directory):
- Use for detailed documentation (loaded on-demand)
- Keep focused and organized
- Link clearly from SKILL.md

**Assets** (`assets/` directory):
- Templates, configuration files
- Static resources
- Keep generic and reusable

## Development

### Project Structure

```
my-skills/
├── .claude-plugin/
│   └── plugin.json        # Plugin manifest
├── skills/                # Agent skills directory
│   ├── example-utility/   # Simple skill template
│   └── example-workflow/  # Complex skill template
├── docs/
│   └── IMPLEMENTATION_PLAN.md  # Project planning documentation
├── .gitignore
├── LICENSE
├── README.md
├── CHANGELOG.md
└── CONTRIBUTING.md
```

### Testing Skills Locally

```bash
# Test with --plugin-dir flag
claude --plugin-dir /Users/oscar/ghq/github.com/ypwu1/my_skills

# Enable debug output
claude --debug --plugin-dir /Users/oscar/ghq/github.com/ypwu1/my_skills
```

### Version Management

This plugin follows [Semantic Versioning](https://semver.org/):
- **MAJOR**: Breaking changes to existing skills
- **MINOR**: New skills or backward-compatible enhancements
- **PATCH**: Bug fixes and documentation updates

Update version in `.claude-plugin/plugin.json` and document changes in `CHANGELOG.md`.

## Plugin Distribution

### Publishing to Skills.sh

1. Create a marketplace file:
```json
{
  "name": "ypwu1-marketplace",
  "plugins": [
    {
      "name": "my-skills",
      "source": "ypwu1/my_skills",
      "version": "1.0.0",
      "description": "Personal collection of custom Claude Code agent skills"
    }
  ]
}
```

2. Users install with:
```bash
claude plugin install my-skills@ypwu1
```

### Alternative Distribution

Share directly via GitHub:
```bash
claude plugin install https://github.com/ypwu1/my_skills.git
```

## Resources

- [Claude Code Plugins Reference](https://code.claude.com/docs/en/plugins-reference)
- [Agent Skills Documentation](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview)
- [Skill Authoring Best Practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)
- [Skills Repository Examples](https://github.com/anthropics/skills)

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on adding new skills.

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for version history.
Keywords

Documentation
