Package Skill

SKILL.md

---
name: package-skill
description: "Create and manage skill packages — bundles of related skills merged into a single top-level skill with internal dispatch. A package skill's own description declares which sub-skills it contains. Trigger when you want to combine multiple skills into one package, reorganize your skill library, or scan a package's sub-skills. Also use when the user says 'package skills', 'bundle skills', 'merge skills', '打包技能', '合并技能', or '创建技能包'."
---

# Skill Packager

Group related skills into a single package with internal dispatch. Reduces top-level skill count and trigger noise while preserving all capabilities.

## When to Use

- Multiple skills share similar trigger patterns (e.g., docx/pptx/xlsx/pdf all trigger on file extensions)
- Skill count exceeds 25 and trigger accuracy degrades
- User asks to consolidate or merge skills

## When NOT to Use

- Skills have fundamentally different trigger domains (e.g., "weather" and "github" — keep separate)
- Only 1-2 skills are involved — not worth packaging overhead

## Directory Structure

```
skills/
  package-skill/           ← This tool
    SKILL.md
    scripts/
      create.py            ← Create packages, add/remove sub-skills
      update.py            ← Scan sub-skills, update pack.md
  <package-name>/          ← Generated package (independent skill)
    SKILL.md               ← Trigger + sub-skill list + dispatch logic
    pack.md                ← Registry: auto-generated sub-skill inventory
    sub/
      <skill-a>/SKILL.md
      <skill-b>/SKILL.md
```

## Workflow

### 1. Create a Package

```bash
python skills/package-skill/scripts/create.py create <package-name> -d "trigger description" <skill1> [skill2 ...]
```

This will:
- Create `<package-name>/` directory with `sub/` and `pack.md`
- Copy each named skill into `sub/`
- Generate a `SKILL.md` with the provided trigger description and dispatch instructions
- Generate a `pack.md` with all sub-skill descriptions for matching
- Remove the original top-level skill directories

### 2. Update pack.md

```bash
python skills/package-skill/scripts/update.py <package-name>
```

Re-reads all `sub/*/SKILL.md` frontmatter and updates `pack.md`. Use after adding or removing sub-skills manually, or anytime you want to refresh the registry.

### 3. Add a Sub-Skill to Existing Package

```bash
python skills/package-skill/scripts/create.py add <package-name> <skill-name>
```

Copies a new skill into the package's `sub/` and updates `pack.md`.

### 4. Remove a Sub-Skill

```bash
python skills/package-skill/scripts/create.py remove <package-name> <skill-name>
```

Removes a sub-skill from the package. If the sub-skill deserves to be top-level again, this command moves it back to `skills/` root.

## Package SKILL.md Template

The generated SKILL.md follows this structure:

```markdown
---
name: <package-name>
description: "<user-provided trigger description>"
---

# <Package Title> Package

This is a skill package bundling N sub-skills: skill-a, skill-b, ...

## How to Use

1. Read [pack.md](pack.md) to determine which sub-skill matches the current task
2. Read the matching sub-skill: `read_file("skills/<package-name>/sub/<sub-skill>/SKILL.md")`
3. Follow that sub-skill's instructions
```

Description is concise and provided by the user at creation time. No sub-skill descriptions here — they live in `pack.md`.

## pack.md Format

```markdown
# <package-name> Registry

- **pdf** — Use this skill whenever the user wants to do anything with PDF files...
- **docx** — Use this skill whenever the user wants to create, read, edit Word documents...
```

Each entry is the `name` and `description` from the sub-skill's frontmatter. Auto-generated by `create.py scan`.

## Guidelines for Writing Package Descriptions

A good package trigger description should:
1. Cover all trigger keywords (file extensions, actions) from sub-skills
2. Stay under 200 words — the description is loaded in every session
3. Guide the agent to read `pack.md` for sub-skill matching

## Design Principles

- **Sub-skills stay intact** — no content is stripped, only relocated to `sub/`
- **Package is a normal skill** — the agent treats it like any other skill
- **Dispatch is explicit** — the agent reads the sub-skill SKILL.md on demand, not pre-loaded
- **Reversible** — `remove` can promote a sub-skill back to top-level