my-first-skill

Original source / Raw SKILL.md

---
name: my-first-skill
description: Example skill demonstrating Anthropic SKILL.md format. Load when learning to create skills or testing the OpenSkills loader.
---

# My First Skill

This is an example skill demonstrating the Anthropic SKILL.md format.

## Purpose

This skill shows how to structure procedural guidance for AI coding agents using progressive disclosure.

## When to Use

Load this skill when:
- Learning how skills work
- Testing the OpenSkills loader
- Understanding the SKILL.md format

## Instructions

To create a skill:

1. Create a directory: `mkdir my-skill/`
2. Add SKILL.md with YAML frontmatter:
   ```yaml
   ---
   name: my-skill
   description: When to use this skill
   ---
   ```
3. Write instructions in imperative form (not second person)
4. Reference bundled resources as needed

## Bundled Resources

For detailed information about the SKILL.md specification:

See `references/skill-format.md`

## Best Practices

- Write in imperative/infinitive form: "To do X, execute Y"
- NOT second person: avoid "You should..."
- Keep SKILL.md under 5,000 words
- Move detailed content to references/
- Use scripts/ for executable code
- Use assets/ for templates and output files

## Resource Resolution

When this skill is loaded, the base directory is provided:

```
Base directory: /path/to/my-first-skill
```

Relative paths resolve from base directory:
- `references/skill-format.md` → `/path/to/my-first-skill/references/skill-format.md`
- `scripts/helper.sh` → `/path/to/my-first-skill/scripts/helper.sh`


---

## Referenced Files

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

### references/skill-format.md

```markdown
# SKILL.md Format Reference

## YAML Frontmatter (Required)

Every SKILL.md must start with YAML frontmatter:

```yaml
---
name: skill-name           # Required: hyphen-case identifier
description: When to use   # Required: 1-2 sentences, third-person
---
```

## Markdown Body (Required)

After frontmatter, write instructions in **imperative/infinitive form**:

**Good:**
- "To accomplish X, execute Y"
- "Load this skill when Z"
- "See references/guide.md for details"

**Avoid:**
- "You should do X"
- "If you need Y"
- "When you want Z"

## Progressive Disclosure

Skills load in three levels:

1. **Metadata** (always in context): name + description
2. **SKILL.md** (loaded when relevant): core instructions
3. **Resources** (loaded as needed): detailed documentation

## Bundled Resources (Optional)

### references/

Documentation loaded into context as needed:
- API documentation
- Database schemas
- Detailed guides

### scripts/

Executable code (Python/Bash/etc.):
- Can be run without loading to context
- Use for deterministic, repeatable tasks

### assets/

Files used in output (not loaded to context):
- Templates
- Images
- Boilerplate code

## File Size Guidelines

- **SKILL.md**: Under 5,000 words
- **references/**: Unlimited (loaded selectively)
- **scripts/**: Executable, not counted
- **assets/**: Not loaded to context

## Example Structure

```
pdf-editor/
├── SKILL.md              (~2,000 words)
├── references/
│   └── pdf-api.md        (detailed API docs)
├── scripts/
│   ├── rotate.py         (executable)
│   └── merge.py
└── assets/
    └── template.pdf      (boilerplate)
```

```