# @barajas123/pi-skills

A bundle of [Pi](https://pi.dev) agent skills following the [Agent Skills specification](https://agentskills.io/specification).

## Skills

| Skill | Trigger | Description |
|-------|---------|-------------|
| `skill-create` | manual — "create a skill", "design a skill", "write a skill" | Creates new agent skills with spec-compliant YAML frontmatter, proper directory structure, and best practices for scope, calibration, and progressive disclosure. |

## Install

```bash
pi install npm:@barajas123/pi-skills
```

Or try it without installing:

```bash
pi -e npm:@barajas123/pi-skills
```

## Usage

Once installed, Pi loads skill names and descriptions into the system prompt at startup. The agent activates skills on-demand when a task matches.

### Using skill-create

Ask Pi to create a skill:

```
> create a skill for reviewing pull requests
```

Or use the slash command:

```
/skill:skill-create
```

The skill will:
1. Gather domain context from you (real tasks, artifacts, gotchas)
2. Define scope — one coherent unit of work
3. Write a spec-compliant `SKILL.md` with YAML frontmatter
4. Create supporting files (`scripts/`, `references/`, `assets/`) if needed
5. Validate against the agentskills.io spec
6. Suggest running it against a real task to refine

## Package structure

```
pi-skills/
├── package.json          # npm metadata + pi manifest
├── README.md             # this file
└── skills/
    └── skill-create/
        └── SKILL.md      # spec-compliant skill with frontmatter
```

## Adding more skills

To add a new skill to this bundle:

1. Create a directory under `skills/`:
   ```bash
   mkdir -p skills/my-new-skill
   ```

2. Write `skills/my-new-skill/SKILL.md` with YAML frontmatter:
   ```markdown
   ---
   name: my-new-skill
   description: What it does and when to use it.
   ---

   # My New Skill

   ## Instructions
   ...
   ```

3. Bump the version in `package.json`:
   ```bash
   npm version patch
   ```

4. Publish:
   ```bash
   npm publish --access public
   ```

## Spec compliance

All skills in this package follow the [Agent Skills specification](https://agentskills.io/specification):

- ✅ YAML frontmatter with required `name` and `description` fields
- ✅ `name` is lowercase with hyphens, no leading/trailing/consecutive hyphens
- ✅ `description` describes what the skill does AND when to use it
- ✅ `SKILL.md` body under 500 lines
- ✅ Progressive disclosure — detailed content in `references/` loaded on demand
- ✅ Optional directories: `scripts/`, `references/`, `assets/`

## License

MIT