Skill Bundles
Group related skills into named bundles and select them with a single @name selector
A bundle is a named set of skills. Select the bundle with @name and all its member skills load together — no need to list each one.
from praisonaiagents import Agent
agent = Agent(
name="Backend Dev",
instructions="Help with backend engineering tasks.",
skills=["@backend-dev"],
)
agent.start("Refactor the users table migration.")The user selects @backend-dev; all skills in the bundle load together for that agent.
Quick Start
- Author a bundle manifest
Create a YAML file in a
bundles/subdirectory of your skills directory:yaml # ./skills/bundles/backend-dev.yaml name: backend-dev description: Everything a backend engineer needs skills: - pdf-processing - sql-runner - repo-search instruction: | When responding as a backend dev, prefer explicit types and quote sources. - Select the bundle
Use
@bundle-nameanywhere you’d normally list a skill:python from praisonaiagents import Agent agent = Agent( name="Backend Dev", instructions="Help with backend engineering tasks.", skills=["@backend-dev"], ) agent.start("Refactor the users table migration.") - Mix bundles with individual skills
Bundles and plain skill paths can be combined freely:
python from praisonaiagents import Agent agent = Agent( name="Full Stack Dev", instructions="Help with both frontend and backend.", skills=["@backend-dev", "./skills/custom-linter"], ) agent.start("Review this pull request.")
How It Works
Bundle Manifest Schema
Bundles are discovered from YAML files in two locations:
./skills/bundles/*.yaml— any YAML file inside abundles/subdirectory./skills/<skill-name>/BUNDLE.yaml— a top-level file inside a skill directory
Fields
| Field | Type | Required | Description |
|---|---|---|---|
name | str | ✅ | Bundle name in kebab-case (used as @name) |
description | str | — | What the bundle is for |
skills | list[str] | — | Member skill names to expand |
instruction | str | — | Extra guidance injected into the prompt for this bundle |
Example manifest
name: backend-dev
description: Everything a backend engineer needs
skills:
- pdf-processing
- sql-runner
- repo-search
instruction: |
When responding as a backend dev, prefer explicit types and quote sources.Common Patterns
Role bundles
from praisonaiagents import Agent
researcher = Agent(
name="Researcher",
instructions="Research and summarize topics.",
skills=["@researcher"],
)
backend_dev = Agent(
name="Backend Dev",
instructions="Write backend code.",
skills=["@backend-dev"],
)Mix bundles and one-off paths
from praisonaiagents import Agent
agent = Agent(
name="Custom Dev",
instructions="Help with development tasks.",
skills=["@backend-dev", "./skills/my-private-tool"],
)Multiple bundles
from praisonaiagents import Agent
agent = Agent(
name="Full Stack Dev",
instructions="Help with all development tasks.",
skills=["@backend-dev", "@frontend-dev"],
)Bundle Discovery
The SDK scans skill directories for bundle manifests automatically. Discovery mirrors skill discovery — same roots, same auto-discover setting.
Name collision: first bundle found wins. Later duplicates are shadowed and logged at INFO level.
Unknown bundle: a warning is logged and the selector is skipped — agent continues with remaining skills.
Unknown member skill: a warning is logged and the member is skipped — bundle continues expanding remaining members.
Cycle protection: circular bundle references are detected, warned, and skipped.
Best Practices
Use kebab-case names
Bundle names should be in kebab-case (backend-dev, not backendDev or backend_dev). The @ selector strips the marker and looks up the exact name.
Keep bundles focused
A bundle should represent one role or capability domain. Small, focused bundles are easier to reason about and combine than large monolithic ones.
Put role guidance in the instruction field
The instruction field injects extra context into the prompt for every selected bundle. Use it for role-level behavioral guidance rather than duplicating it in each member skill.
Avoid cycles
Bundle members should be skill names, not other bundle selectors. Circular references are detected and logged, but they result in the cycle being skipped — causing unexpected skill gaps.