Skip to main content

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.

The Skald board on the lifecycle columns Idea, Plan, Ready, In progress, Review, and Done: an epic with a children bar, a story claimed by an agent with its checklist progress, a blocked story, two stories with open questions, and a Waiting on a human filter
A terminal session: skald status, skald claim, skald resume, a handoff note, skald move, and skald diff A story open on the board in view mode: its id, dates, and title, a status select, tag chips, its parent chip, an acceptance checklist, and a dated handoff note
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. context orients a session in one block, next and claim pick work without stepping on other agents, resume reads what the last session left behind, notes carry kinds such as decision and handoff, and acceptance checklists gate the move to done. The contract is one Markdown file that init writes 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-Story trailers. diff, activity, and changelog read history back; render commits a snapshot GitHub shows in place; release turns 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|csv dumps 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:id dependencies 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.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for skald-kanban 1.3.2
File Size Uploaded Provenance Actions
skald_kanban-1.3.2.tar.gz 244.1 kB With provenance Details for skald_kanban-1.3.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for skald-kanban 1.3.2
File Interpreter ABI Platform Actions
skald_kanban-1.3.2-py3-none-any.whl Python 3 none any Details for skald_kanban-1.3.2-py3-none-any.whl

Total release size: 420.3 kB

Release files / skald_kanban-1.3.2.tar.gz

Download URL skald_kanban-1.3.2.tar.gz
Size 244.1 kB
Tags Source
SHA-256 checksum
How to use checksums
0d28b0ab2d97ed912ce9352b398542c58e22ed0d3fe191df2d1ce6739ac8f8f2
BLAKE2b-256 checksum
How to use checksums
0519341c62f837b5320a4210fa2e946430d6343dd8ea5a85651a915d4226660f
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 14, 2026.

Transparency log

Release files / skald_kanban-1.3.2-py3-none-any.whl

Download URL skald_kanban-1.3.2-py3-none-any.whl
Size 176.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c5e5db70740eeb7d389d58a7cfab379f1c11a949e9dd3f057d34d15af65df4d4
BLAKE2b-256 checksum
How to use checksums
9229e99bc90bc596d9b34485516166baea51609c119c23b0cab39f250ab77a03
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 14, 2026.

Transparency log

Security for skald-kanban 1.3.2

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.

Select from 2 files

Attestation for skald_kanban-1.3.2.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 14, 2026.

Transparency log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page