Open source · Apache-2.0
Balde — Knowledge Pail
A governance cockpit for reusable skills. Files on disk, git as the ledger, promotion behind a gate.
Skills — those reusable instructions a person or an AI loads up to do one specific thing well: analyze a report, run a piece of research, audit a contract — accumulate fast on a team. Without discipline they turn into a pile of loose files, with forgotten authors, murky versions, and no one knowing which one is canonical. Balde is where that pile becomes an archive: each skill is a file, each action is a commit with a real author, and going from draft to canonical means passing a gate with nine minimum controls. Nothing gets waved through.
What it does
-
Explicit lifecycle
Every skill lives draft → canonical → deprecated. Drafts can be many; canonicals are the ones the organization commits to maintaining.
-
Promotion gate
POST /api/publishreturns 409 until the nine minimum controls pass — documentation, cited sources, reproducibility, named owner. Either it's ready or it doesn't ship. -
A real git ledger
Every create, upload, edit, or promotion is a commit signed by the real author (name and email pulled from SSO). Per-skill
git logis an auditable history, not a database column. -
Skill as repository
An Explore tab opens each skill in read-only mode as if it were a repo: file tree, rendered
SKILL.md, output_schema.json next to its attachments, and the commit history for that specific skill. -
Buddies
An avatar library that mirrors the skills corpus — each buddy has ten canonical poses, versioned in git on its own, creatable by a dedicated Authentik group. Marcolito, Balde's built-in chatbot, lives there.
-
An API for machines
/api/v1with Bearer auth returns only canonical skills in Open Knowledge Format (OKF) — ready to become context for any downstream agent or pipeline.
A look inside
How a skill moves down the pipeline
- New draft
A guided modal collects title, description, type, tags, objective, and lets you attach an
output_schema.jsonor example files. It's born as a draft, version 0.1.0, with a commit signed by the creator. - Draft
The owner edits, adds sources, tweaks the prompt, uploads attachments. Every save is a commit. The panel shows in red the minimum controls still pending.
- Gate
When the owner clicks publish, a deterministic validator (with a fallback for when AI isn't available) checks the nine controls. If any fails, the response is 409 plus the list of what's missing.
- Canonical
Shows up on
/api/v1, joins "All skills", and can be pulled by any authorized consumer. Rollback is another commit — history is never rewritten.
Under the hood
A zero-dependency Node server (~3,000 lines in
server.js, using only native
http and fs) plus a vanilla-JS
SPA. The corpus is a folder of files with a git
repository inside, mounted as a bind mount in
the container. No database.
Authentication via Authentik forward-auth (SSO
+ 2FA), with roles pulled from groups
(Contributor, Curator,
Buddy Author, Admin). The embedded
chatbot (Marcolito) talks to the LLM through a plain
text protocol — it works with Claude Code, Codex, or a
traditional API, no vendor-specific SDK.
Natural companion to Vassoura: skills catalogued in Balde consume data collected by Vassoura via API key.
Take it and run
Open source, Apache-2.0. Issues and pull requests
welcome. If you're building your own skills archive —
for a team, a community, a project — Balde tries to be
a serious starting point instead of that folder of
.md files lost on OneDrive.