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...
---
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
don't have the plugin yet? install it then click "run inline in claude" again.