SkillBagGitHub
Open SkillBag standard v0.2.0

SkillBag

Give local coding agents the project behavior they need. SkillBag gives Codex, Claude Code, and other workspace-aware tools a portable set of versioned skills they can read, reuse, and apply consistently.

versioned and trackablereusable and composablecross-agent compatible
InstallExampleGitHub
Entrypoint
SKILLBAG.md
Sources
git, zip, local
Discovery
cheap catalog
Rules
clear order

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 utilitiesRead spec

Install

Install the standard in a local workspace

SkillBag starts inside a local repo with one file and one instruction for the agent working in that workspace. 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.mdRead SKILLBAG.md
Step 1

Fetch the standard

Put the root SkillBag entrypoint in the local workspace where the agent will work. 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 local agents

SkillBag is the workspace-level layer for local coding agents. It defines how a repo discovers 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 other local workspace 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 local agents

Use the same repository files with Codex, Claude Code, and other providers that can work against a local workspace.

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

Clone a ready workspace

The example repository is the fastest adoption path: clone it, open it with Codex or Claude Code, and provider shims already point to AGENTS.md so the agent can fetch SKILLBAG.md and follow the setup contract.

Open example repoRead 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
1

Clone the repo

Start from a workspace that already includes AGENTS.md and provider shims.

2

Ask for setup

Open it with Codex or Claude Code and ask the agent to follow setup instructions.

3

Download the standard

AGENTS.md fetches the latest SKILLBAG.md from skillbag.md and routes other shims through the same contract.

4

Materialize dependencies

CONTEXT.md shows the name/source/version shape the agent validates for any compatible source.

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 sourceBrowse skillsMore SkillBags
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.

Official SkillBags

Pick the bag that matches the work

Skillbag-ai publishes compatible bags for common local agent workflows. Add the source your workspace needs in CONTEXT.md; each bag stays independent, versionable, and composable with the standard.

More SkillBagsUtilities source
Documents

Turn office files into agent-readable work

PDF, Word, ODT, image, table, diagram, and templated document workflows for local workspaces that need reliable document handling.

CONTEXT.md source

git@github.com:Skillbag-ai/skillbag-docs.git
Open repoBrowse skills

Why use it

  • Normalize PDFs, Word, ODT, images, and text into markdown transcripts.
  • Run OCR only when a PDF actually needs a text layer.
  • Extract table-heavy documents into markdown, CSV, or spreadsheet outputs.

Top skills

document-to-markdown-transcriptskillbag-pdf-ocrextract-structured-tablescreate-word-document-from-template

Ask naturally

Create a markdown transcript from this PDF.

Extract the tables from this report.

Create a Word document from this markdown using my template.

Knowledge bases

Create local corpora agents can search cheaply

Portable resource roots for documents, notes, datasets, links, and reference libraries that need summaries, chunks, embeddings, and local query.

CONTEXT.md source

git@github.com:Skillbag-ai/skillbag-resources.git
Open repoBrowse skills

Why use it

  • Scaffold local knowledge bases with originals, derivatives, metadata, and state.
  • Ingest clean folders or messy drops without hard-coding project taxonomy.
  • Search summaries first, then deeper chunks and vector candidates when needed.

Top skills

skillbag-resource-scaffoldskillbag-resource-ingestskillbag-resource-sync-indexskillbag-resource-query

Ask naturally

Create a knowledge base for this project.

Ingest this data room for later AI work.

Find what we know about key rotation in the corpus.

Media

Process local recordings without cloud defaults

Audio and video skills for local transcription, timeline generation, transcoding, prerequisite checks, and reusable meeting summaries.

CONTEXT.md source

git@github.com:Skillbag-ai/skillbag-media.git
Open repoBrowse skills

Why use it

  • Transcribe local audio or video with Hugging Face ASR or local Whisper CLI.
  • Create timestamped timelines from meetings, demos, and screen-share walkthroughs.
  • Summarize transcripts into decisions, action items, open questions, and follow-ups.

Top skills

media-transcriptmedia-recording-timelinemedia-call-summarymedia-transcode

Ask naturally

Transcribe this call recording.

Make a timeline from this walkthrough video.

Summarize this transcript into decisions and action items.

Workflows

Keep recurring local work visible over time

Reusable workflow skills for chronological logs and local cron-style agent jobs that need reminders, background execution, and auditable result logs.

CONTEXT.md source

git@github.com:Skillbag-ai/skillbag-workflows.git
Open repoBrowse skills

Why use it

  • Maintain folder-local chronological logs with newest entries first.
  • Track local agent cron jobs in versioned jobs.json files.
  • Use lifecycle reminders, scheduler installation, and cleanup without hiding results.

Top skills

skillbag-chrono-logskillbag-cronjobs

Ask naturally

Add this outcome to the project log.

Create a local cron job reminder for this workspace.

Show me which interactive jobs are due before we continue.

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.

  1. Read SKILLBAG.md

  2. Apply context precedence

  3. Load the skill catalog

  4. Validate missing dependencies

  5. Run lifecycle skills

PhaseReadsResult
EntrySKILLBAG.mdRoot lifecycle, required files, and source rules are known.
ContextUSER_CONTEXT.md + CONTEXT.mdOverrides resolve in a defined precedence order.
Discovery.skills/SKILLS.mdThe agent sees the catalog before loading individual skills.
InstallDeclared dependency sourcesMissing dependencies are validated before files change.
Run#run/always + #run/lastLifecycle-tagged skills run in deterministic order.

Use the standard where coding agents already work.

Install SkillBag in a local workspace, point Codex, Claude Code, or another file-aware agent at the same contract, then declare the skills this repo needs. 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.mdCore repo
Core standardUtilitiesDocsResourcesMediaExample repoSKILLBAG.md