Skald
Track work from idea to release, in Markdown, in your repo, with your coding agents.
Skald turns a folder of Markdown files into a backlog that travels with your code. Capture an idea, plan it, hand it to an agent, answer the questions it raises, review the result, and ship it in a release, with every step recorded as a dated note in the story's own file. Agents drive it from a small CLI that fits in a session's context. You drive it from a local board that shows every project and worktree on the machine. There is no database and no service: one dependency-free Python package, and git is the history.
.skald/
├── config.json # project name, story format version, columns
├── AGENTS.md # what an agent needs to know, written by `init`
├── stories/ # one Markdown file per story
│ └── a3f9c2-implement-wireguard-overlay.md
├── archive/ # stories shipped in a release, moved out of the way
└── templates/ # optional story body templates
Stories are committed with the code they describe, so the board travels with the branch and shows up in pull request diffs.
| An agent's session: claim, resume, hand off, move, and see the diff. | The same story on the board: dependencies, acceptance criteria, notes. |
What you get
- A workflow agents can follow.
contextorients a session in one block,nextandclaimpick work without stepping on other agents,resumereads what the last session left behind, notes carry kinds such asdecisionandhandoff, and acceptance checklists gate the move to done. The contract is one Markdown file thatinitwrites for you. - A board for the human. Every registered project in one page, live updates, drag, multi-select, dependency graph, the working tree of every worktree on the machine, read-only views of other branches, dark mode, and a Help panel with the full CLI reference.
- Git as the database. Story changes commit with the code they describe
and carry
Skald-Storytrailers.diff,activity, andchangelogread history back;rendercommits a snapshot GitHub shows in place;releaseturns the done column into a changelog section and a versioned archive. - Never locked in. The backlog is plain Markdown in your repo, and
skald export --format json|jsonl|csvdumps the whole thing as one flat file for analytics in a spreadsheet or a migration to another tracker. - More than one repository. A machine-local index gives you one board
and
project:iddependencies across every repository you use Skald in. - Nothing to run. Python standard library only, Python 3.10 or newer, Linux, macOS, and Windows. Tab completion for bash, zsh, and fish.
Is Skald the right tool?
Several projects keep a tracker inside the repository. They make different trade-offs, so this table is about focus rather than ranking. Checked against each project's README in September 2026; follow the links for current detail.
| Skald | Backlog.md | Beads | git-bug | git-issue | |
|---|---|---|---|---|---|
| Data lives in | Markdown files under .skald/, committed |
Markdown files under backlog/, committed |
Dolt database under .beads/, with a JSONL export |
Git objects, not files in the worktree | Text files under .issues/, committed |
| Unit of work | Story: column, rank, dependencies, tags, dated notes | Task: status, acceptance criteria, dependencies, labels, milestones | Issue: status, priority, assignee, dependencies, labels, hierarchy | Issue with comments, labels, status | Issue with comments, tags, assignee, milestone, due date |
| Built for | Coding agents first, humans reviewing on a board | Humans and agents together | Agents, with memory decay of closed work | Humans, distributed and offline-first | Humans, git-native |
| Agent interface | CLI, MCP server, Claude Code hooks and skill, AGENTS.md |
CLI, MCP server, AGENTS.md |
CLI with JSON output, MCP server, AGENTS.md |
CLI | CLI |
| Human interface | Local web board across all projects on the machine | Terminal board and local web board | CLI | CLI, TUI, web UI | CLI |
| More than one repository | Yes: one board, project:id references |
One project per workspace | Separate repos with routing and sync | Per repository, pushed to remotes | Per repository |
| Work in progress across worktrees | Board shows each checkout's working tree; a claim in a worktree is seen before it is committed | Files per checkout; the MCP server follows the current worktree | Not documented | Shared: issues are git objects, not files | Files per checkout |
| Committed snapshot | skald render writes Markdown or HTML with a dependency graph |
backlog board export writes a Markdown report |
No | No | No |
| Sync with hosted trackers | No; a one-way, re-runnable GitHub issues import example | No | No | Bridges to GitHub and GitLab | Import and export with GitHub and GitLab |
| Runtime | Python, standard library only | TypeScript on Bun or Node | Go | Go | Shell, jq, curl |
Skald is a good fit when agents do most of the work, a human wants to see that work on one board across repositories, and the backlog should read well in a pull request diff. Reach for something else when you want threaded discussion on issues (git-bug, or the hosted tracker you already use), a long history that needs summarising to save context (Beads), or two-way sync with GitHub issues (git-bug, git-issue).
Install
pip install skald-kanban
# or: pipx install skald-kanban
# or: uv tool install skald-kanban
# latest from source: pip install git+https://github.com/Vitund-AI/skald.git
cd your-repo
skald init
The distribution name is skald-kanban; the command is skald, and git skald works too. init creates .skald/, writes the agent contract, registers the
project on your machine, and points your CLAUDE.md or AGENTS.md at the
contract. Shell completion is one line in your rc file:
eval "$(skald completion zsh)" # or bash; fish: skald completion fish > ~/.config/fish/completions/skald.fish
Quick start
skald new "Implement WireGuard overlay" --tags infra --body "Configure wg0 on every node."
skald new "Write the network docs" --status ready --blocked-by a3f9c2
skald ls
skald open # starts the board server if needed and opens this project
An agent's session looks like this:
skald context --as claude # mine, next, blockers, claims elsewhere, uncommitted
skald claim a3f9c2 --as claude # assign it and move it to in_progress
skald resume a3f9c2 # requirements, checklist, deps, latest handoff
skald note a3f9c2 "Why we chose X" --as claude --kind decision
skald note a3f9c2 "Done: ... Remaining: ... Next: ..." --as claude --kind handoff
skald move a3f9c2 review
git add .skald src && git commit --trailer "Skald-Story: a3f9c2"
For Claude Code, skald hooks claude --install --as claude adds a
SessionStart hook that runs skald context so every session begins
oriented without reading the whole backlog, a Stop hook that refuses to end
with a broken backlog, and a skill that loads the contract. Any agent that
speaks MCP — Cursor, Windsurf, Zed, or Claude Code itself — attaches to
skald mcp over stdio; see Working with agents.
Documentation
| Page | Read it when |
|---|---|
| Getting started | You are installing Skald or adding it to a repository. |
| Working with agents | You want to know what the contract asks for and why, and how to hook Claude Code or any MCP client up to it. |
| The board | You want every board feature in one place. |
| Stories | You want the file format, the design-record layout for long stories, columns and roles, facets and epics, templates, archiving, and releases. |
| Conventions | You want the facet tags (epic:, lane:, effort:, area:, release:) and what each one unlocks. |
| Git and CI | You want commit trailers, reviewing what changed, the committed snapshot, hooks, the GitHub workflow, and the release flow. |
| Multiple projects | You have more than one repository, or more than one checkout of one. |
| Importing | You have an existing folder of Markdown records to bring in. |
| CLI reference | You need the exact flags. Generated from the parser. |
| HTTP API | You are scripting against the board server: the data plane (stories, projects, the change stream) is stable; the board's own routes are internal. |
| Troubleshooting | Something printed an error or looks wrong. |
| Examples | Worked setups on top of the core: routing stories to model-pinned agents by tag, with a report on what each model finished; pulling GitHub issues into the backlog. |
The design is in SPEC.md and the reasoning behind non-obvious
choices in DECISIONS.md. What 1.x keeps stable (the story
format, CLI flags and --json fields, MCP tools, and the HTTP data plane) is
in its Compatibility section.
Development
pip install -e .
python -m unittest # standard library only
ruff check src tests examples scripts # the lint CI runs (pip install ruff)
skald serve # run against this repository's own backlog
skald docs # regenerate docs/cli.md after changing a command
scripts/release.sh 1.2.0 --dry-run # maintainers: the release, checked step by step
This repository dogfoods Skald: its own backlog is in .skald/, and the
board rendered from it is at .skald/README.md.
CONTRIBUTING.md has the workflow for changes, the
project follows a code of conduct, and
SECURITY.md says how to report a vulnerability.
License
MIT. See LICENSE.
Metadata
Release files for skald-kanban 1.3.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| skald_kanban-1.3.3.tar.gz | 247.9 kB | With provenance | Details for skald_kanban-1.3.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| skald_kanban-1.3.3-py3-none-any.whl | Python 3 | none | any | Details for skald_kanban-1.3.3-py3-none-any.whl |
Total release size: 426.5 kB
Release files / skald_kanban-1.3.3.tar.gz
| Download URL | skald_kanban-1.3.3.tar.gz |
|---|---|
| Size | 247.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0b2111094825dcd8a93f6868596ec68d6e74a88ab5b292c0b17b7006fbf21ccf
|
|
BLAKE2b-256 checksum How to use checksums |
1a1d1aef0e9297390b65b6b6647f6503121924c3be2db2c33594f845791af06b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logRelease files / skald_kanban-1.3.3-py3-none-any.whl
| Download URL | skald_kanban-1.3.3-py3-none-any.whl |
|---|---|
| Size | 178.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2e5e052fcde0d2b327484a474e79ca992aa5c5ec3148d475c905f5b3ed0a40bc
|
|
BLAKE2b-256 checksum How to use checksums |
aff25930c4ed060e61ca4b34d337559d8203984b8205dc125b13e33c7c11ba6b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logSecurity for skald-kanban 1.3.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for skald_kanban-1.3.3.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.