Package Skill

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 d...

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

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

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

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

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:

---
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

# <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