Skip to main content

Bundle Structure

A bundle source is a Git repository. skul caches the source in ~/.skul/library/ and reuses that cache on future runs.

Repository layouts​

Two source layouts are supported.

Multi-bundle repository​

Each top-level subdirectory is a bundle:

github.com/sjquant/ai-bundles
|- react-expert/
|  |- skills/
|  |- commands/
|  `- agents/
`- python-data/
   `- skills/

Users reference the directory name as the bundle name.

Repo-as-bundle​

The repository root itself is one bundle:

github.com/sjquant/react-bundle
|- skills/
`- commands/

In that mode, skul uses the repository slug as the bundle name.

Content layouts​

Inside a bundle, skul supports two ways to describe content.

Canonical layout​

Top-level directories describe the content type:

bundle/
|- skills/
|- commands/
|- agents/
`- AGENTS.md, CLAUDE.md, or .github/copilot-instructions.md

skul copies each directory into every compatible tool target.

Native layout​

Tool-specific dot directories target a single tool explicitly:

bundle/
|- .claude/skills/
|- .cursor/commands/
|- .github/agents/
|- .kiro/skills/
|- .codex/agents/
`- AGENTS.md, CLAUDE.md, or .github/copilot-instructions.md

Use native layout when tool-specific behavior matters and cross-tool copying would be wrong.

Selecting bundle items​

By default, skul add installs every compatible item in the bundle for the selected tool targets. Use --include to install only specific top-level items:

skul add react-expert --agent codex --include skills/diagnose
skul add react-expert --agent codex --include agents/reviewer
skul add react-expert --agent codex --include root-instruction

Supported selectors are:

  • skills/<name>
  • commands/<name>
  • agents/<name>
  • root-instruction

Use --select-items to choose from the available bundle items interactively:

skul add react-expert --agent codex --select-items