> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

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

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    Agent["🤖 Agent"] --> Bundle["📦 @backend-dev bundle"]
    Bundle --> S1["🔧 pdf-processing"]
    Bundle --> S2["🔧 sql-runner"]
    Bundle --> S3["🔧 repo-search"]
    S1 & S2 & S3 --> Prompt["📋 Prompt injection"]

    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef bundle fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef skill fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef prompt fill:#10B981,stroke:#7C90A0,color:#fff

    class Agent agent
    class Bundle bundle
    class S1,S2,S3 skill
    class Prompt prompt
```

## Quick Start

<Steps>
  <Step title="Author a bundle manifest">
    Create a YAML file in a `bundles/` subdirectory of your skills directory:

    ```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # ./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.
    ```
  </Step>

  <Step title="Select the bundle">
    Use `@bundle-name` anywhere you'd normally list a skill:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    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.")
    ```
  </Step>

  <Step title="Mix bundles with individual skills">
    Bundles and plain skill paths can be combined freely:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    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.")
    ```
  </Step>
</Steps>

***

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant Agent
    participant SkillManager
    participant Bundle as Bundle Manifest
    participant Prompt

    Agent->>SkillManager: skills=["@backend-dev"]
    SkillManager->>Bundle: resolve @backend-dev
    Bundle-->>SkillManager: [pdf-processing, sql-runner, repo-search]
    SkillManager-->>Agent: expanded skill list
    Agent->>Prompt: inject skill instructions + bundle instruction
```

***

## Bundle Manifest Schema

Bundles are discovered from YAML files in two locations:

1. `./skills/bundles/*.yaml` — any YAML file inside a `bundles/` subdirectory
2. `./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 |

<Note>
  Both `skills` and `members` are accepted as the list key. Members can be a plain string (space/comma-separated) or a YAML list.
</Note>

### Example manifest

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent

agent = Agent(
    name="Custom Dev",
    instructions="Help with development tasks.",
    skills=["@backend-dev", "./skills/my-private-tool"],
)
```

### Multiple bundles

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    Q{"Where is\nyour bundle?"} --> A["skills/bundles/*.yaml\n(recommended)"]
    Q --> B["skills/<name>/BUNDLE.yaml\n(inside a skill dir)"]

    classDef q fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef opt fill:#189AB4,stroke:#7C90A0,color:#fff

    class Q q
    class A,B opt
```

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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Agent Skills" icon="puzzle-piece" href="/docs/features/skills">
    Core skills system — how skills are loaded and injected
  </Card>

  <Card title="Learn a Skill" icon="graduation-cap" href="/docs/features/agent-learn-skill">
    Generate a skill from code, docs, or PDFs
  </Card>

  <Card title="Skill Manage" icon="wand-magic-sparkles" href="/docs/features/skill-manage">
    Let agents create and edit skills with human approval
  </Card>

  <Card title="Skills vs Tools" icon="scale" href="/docs/features/skills-vs-tools">
    When to use skills versus executable tools
  </Card>
</CardGroup>