Open SkillBag standard v0.2.0

SkillBag

Stop re-teaching every AI agent how your project works. SkillBag gives each repo a portable set of versioned skills that agents can read, reuse, and apply consistently across tools.

versioned and trackablereusable and composablecross-agent compatible

Install SkillBag GitHub

Entrypoint: SKILLBAG.md
Sources: git, zip, local
Discovery: cheap catalog
Rules: clear order

workspace entry

$curl -fsSL https://skillbag.md -o SKILLBAG.md

agentDownload https://skillbag.md to SKILLBAG.md

AGENTS.mdRead and execute SKILLBAG.md before any other work.

CONTEXT.mdname + version + source for each skill

userUse the declared skill for this task

2-minute setup

Install the standard

Fetch the canonical SKILLBAG.md with curl, or ask Codex or Claude Code to download https://skillbag.md and save it as SKILLBAG.md. Skill dependencies are declared by name, source, and version in CONTEXT.md.

terminal

curl -fsSL https://skillbag.md -o SKILLBAG.md

Codex or Claude Code

Download https://skillbag.md and save it as SKILLBAG.md in the repository root.

Optional utilities Read spec

Install

Install the standard, then declare the skills this repo needs

SkillBag starts with one file and one agent instruction. From there, CONTEXT.md can declare skills by name, source, and version from your organization, a vendor, a local path, Skillbag-ai, or any compatible third-party source.

Open skillbag.md Read SKILLBAG.md

Step 1

Fetch the standard

Put the root SkillBag entrypoint in the project that should have portable agent behavior. You can do it yourself or ask Codex or Claude Code to download the same source to the exact root filename.

terminal

curl -fsSL https://skillbag.md -o SKILLBAG.md

Codex or Claude Code prompt

Download https://skillbag.md and save it as SKILLBAG.md in the repository root.

Both routes create the same normative workspace contract agents read first.

Step 2

Tell agents to run it

Add one instruction to AGENTS.md or the provider shim file your agent already reads.

AGENTS.md

Read and execute SKILLBAG.md before any other work.

Other shims can simply point back to AGENTS.md.

Step 3

Declare any compatible source

When a repo needs reusable behavior, declare skills by name, version, and source. This can point directly at a team, vendor, local, or third-party SkillBag source.

CONTEXT.md

dependencies:
  - name: api-review
    version: v1.2.0
    source: git@github.com:ExampleOrg/agent-skillbag.git

Optional Skillbag-ai utilities

dependencies:
  - name: skillbag-create-skill
    version: main
    source: git@github.com:Skillbag-ai/skillbag-utils.git
  - name: skillbag-find-skills-sh
    version: main
    source: git@github.com:Skillbag-ai/skillbag-utils.git

SkillBag standardizes the source contract. It is not a package manager, hosted registry, or requirement to use Skillbag-ai sources.

Step 4

Ask for the task

Once dependencies are present, users do not need to remember execution identifiers. Ask for the outcome and let the agent select the matching local skill.

Use a declared skill

Use the API review skill to check this endpoint change.

Optional utility workflows

Create a SkillBag skill for release-note drafting.

Find me a skill that can help with system-design brainstorming.

Create/find prompts only matter if those utilities are declared. A workspace can also start directly with any third-party or team bag.

Source model

Bags are sources, not registry packages

A bag is any compatible SkillBag source. Point directly at team, vendor, local, or third-party sources; skillbag-utils is just the first-party utility source for maintaining SkillBag workspaces.

Source rules

About

Project-level behavior files for AI agents

SkillBag is the workspace-level layer missing from single-skill formats. It defines how a repo discovers local skills, materializes declared dependencies from compatible sources, resolves precedence, and runs lifecycle behavior.

Agent Skills basis

Open standard, not a package manager

SkillBag defines files, precedence, source validation, and lifecycle behavior. It does not define a hosted registry, publishing API, or general-purpose software package manager.

Workspace rules for existing skill formats

SkillBag is loosely based on the per-skill Agent Skills format and extends it with workspace-level rules. For developers, it is similar in spirit to .editorconfig: small project files that tools can read consistently.

Bring your own compatible sources

A bag can be maintained by Skillbag-ai, a company, a project team, or a third party as long as it exposes a valid SkillBag source.

Skills stay version-controlled

The effective behavior is inspectable in the repository through SKILLBAG.md, CONTEXT.md, and .skills/.

Provider shims stay thin

AGENTS.md, CLAUDE.md, Cursor, and Copilot instruction files can all point to one shared SkillBag contract.

Local edits remain authoritative

Materialized skills are useful, but the standard preserves local changes and requires explicit overwrite behavior.

What it gives you

Source-agnostic bags

Reference behavioral specs from Skillbag-ai, your company, a team repo, a vendor, or a local source that follows the SkillBag contract.

Portable across agents

Keep behavior in ordinary repository files instead of locking it inside one provider-specific setup.

Cheap to discover

Agents read SKILLBAG.md and .skills/SKILLS.md first, then load only the specific skills required for the task.

Explicit when rules conflict

Conversation context, user context, project context, the standard, and skill defaults resolve in a defined order.

Explicit dependencies

CONTEXT.md declares skill name, source, and version so agents know exactly which compatible source supplied each behavior.

Auditable at runtime

Run tags make always-on and pre-response behavior visible so execution drift can be detected and reported.

Why it exists

Workspace questions single skills do not answer

Which skills are installed here?
Which dependencies are required for setup?
Which source supplied each skill?
Which context file wins when rules conflict?
How can an agent discover skills without loading everything?

File contract

The small surface agents need

SKILLBAG.md: Workspace entrypoint and normative lifecycle rules.
.skills/SKILLS.md: Cheap discovery catalog for installed skills.
.skills/<name>/SKILL.md: Individual skill instructions, metadata, parameters, and dependencies.
CONTEXT.md: Project-level dependencies and behavioral context.
USER_CONTEXT.md: User-local overrides that should remain untracked.

Example project

A minimal repo can bootstrap the standard

The example repository shows the smallest practical adoption path: provider shims point to AGENTS.md, AGENTS.md fetches SKILLBAG.md, and dependency entries use the same name/source/version shape for any compatible source.

Open example repo Read core README

Agent prompt

Ask for setup

In the example repo, the user prompt can stay simple because repository files carry the actual setup contract.

Codex or Claude Code

follow setup instructions

Ask for setup

Open the example project with an agent and ask it to follow setup instructions.

Download the standard

The AGENTS.md file fetches the latest SKILLBAG.md from skillbag.md.

Materialize dependencies

CONTEXT.md declares skills from one or more compatible sources for the agent to validate and materialize locally.

Use thin shims

CLAUDE.md and other provider files can redirect to the same AGENTS.md rules.

CONTEXT.md dependency shape

dependencies:
  - name: my-custom-skill
    version: v1.2.0
    source: git@github.com:your-org/your-skillbag.git

Optional utilities

First-party utilities for maintaining SkillBag workspaces

You can skip skillbag-utils entirely and declare a team, vendor, local, or third-party source directly in CONTEXT.md. This first-party source provides reusable workspace operations: create, adapt, modify, discover, log, split long tasks, refresh context, and audit execution.

Open utility source Browse skills

CONTEXT.md

dependencies:
  - name: skillbag-adapt-skill
    version: main
    source: git@github.com:Skillbag-ai/skillbag-utils.git
  - name: skillbag-modify-skill
    version: main
    source: git@github.com:Skillbag-ai/skillbag-utils.git
  - name: skillbag-supervisor
    version: main
    source: git@github.com:Skillbag-ai/skillbag-utils.git

natural-language prompts

Create a SkillBag skill for release-note drafting.

Adapt this existing checklist into a SkillBag skill.

Audit which skills were used before you answer.

Create

skillbag-create-skill

Create a conforming local skill and synchronize SKILLS.md.

Adapt

skillbag-adapt-skill

Turn an existing file or directory into a SkillBag skill.

Maintain

skillbag-modify-skill

Edit, rename, or version an existing skill while preserving catalog consistency.

Discover

skillbag-find-skills-sh

Search skills.sh and adapt selected results into SkillBag format.

Report

skillbag-log-skills

Add a lightweight final list of skill names used for the response.

Long task

skillbag-long-task

Split long-running or context-heavy work into continuation-sized batches.

Runtime

skillbag-refresh-skill-context

Re-ingest changed SkillBag state without reloading every skill file.

Audit

skillbag-supervisor

Audit used skills at the end of a task and report whether they were followed.

Runtime flow

What the agent resolves before it acts

Installation is a setup workflow. Runtime is a resolution flow: read the contract, merge context, discover available skills, validate missing dependencies, then run selected lifecycle behavior.

Read SKILLBAG.md
Apply context precedence
Load the skill catalog
Validate missing dependencies
Run lifecycle skills

Phase	Reads	Result
Entry	`SKILLBAG.md`	Root lifecycle, required files, and source rules are known.
Context	`USER_CONTEXT.md + CONTEXT.md`	Overrides resolve in a defined precedence order.
Discovery	`.skills/SKILLS.md`	The agent sees the catalog before loading individual skills.
Install	Declared dependency sources	Missing dependencies are validated before files change.
Run	`#run/always + #run/last`	Lifecycle-tagged skills run in deterministic order.

Use the standard, then declare the skills this repo needs.

The core repo defines the contract. Skillbag-ai publishes a first-party utility source for optional maintenance workflows, and other teams can publish compatible bags with the same source layout, dependency rules, and local override behavior. SkillBag standardizes the files and validation lifecycle, not a central package registry.

Declare a source

CONTEXT.md: name + source + version

Ask naturally

Use the API review skill to check this change.

Optional utilities

skillbag-utils: create, adapt, find, audit

Get SKILLBAG.md Core repo

Core standard Utilities Example repo SKILLBAG.md