Why We Open-Sourced Koinoflow

Koinoflow is on GitHub under MIT. No manifesto, no mission statement about democratizing anything, no press cycle. It is a tool a few engineers at Visionect built to fix three very specific problems we were hitting internally, and keeping it closed stopped making sense.

The three problems, in order of how much they hurt:

• Getting skills to people who are not going to write a SKILL.md themselves.
• Versioning those skills without giving every team a git repo.
• Keeping the whole company on the same version of a skill the day a process changes.

Hallucination reduction and lower token bills fell out of the solution. Those are the bonuses, not the pitch.

Problem 1: skills are written by engineers, used by everyone else

A skill is a folder with a specific frontmatter, a carefully-worded description the model uses to decide when to invoke it, optional scripts, and a set of allowed-tools that control what the agent is permitted to run. A well-formed skill is a small engineering artifact. It has to follow security rules (no secrets in scripts, no overly broad tool permissions, no executable payloads from untrusted sources) and style rules (the description has to match how real users phrase the request, or the model will not pick it up).

The people who need those skills are rarely the people who can write them. Legal wants an "NDA redline" skill. Finance wants an expense-threshold skill. Support wants a refund-runbook skill. None of those teams want to learn YAML frontmatter, and none of them should be the ones deciding what goes in allowed-tools. Hand them a markdown file and ask them to edit it in place on their laptop and you have already lost the security review.

What we needed was a way for an engineer or ops lead to author a skill once, with the security and format review baked into the authoring step, and then hand it to a non-technical colleague as a button. That is what Koinoflow is. Skills are written, reviewed, and signed off in one place. Every person in the org consumes them through the same MCP server, with the same version, the same permissions, and the same owner on record.

Problem 2: git is source control, not a distribution system

Anthropic's own guidance for Claude Code is to commit .claude/skills/ to version control. For a team of ten engineers in one repo, that works fine. For a 200-person company where skills touch Ops, Support, Finance, Legal, People, and Sales, it falls apart the moment you try to write it down as a policy.

Pick any of the obvious questions and watch it break:

• Who owns the repo? Engineering? Then every policy change in Legal needs an engineering PR review.
• Who has it cloned? The CFO is not running git pull on Monday mornings. Nor should they.
• One repo per team? Now you have eight copies of the same onboarding skill, drifting, with eight different names for the same input.
• One repo for everyone? Now a Legal policy edit and a support runbook edit and a finance threshold change are all stacked in the same PR queue.

Git is excellent at what it does. What it does is let engineers collaborate on code that ships together. A company's operational skills are not code that ships together. They are many small policies, each with a different owner, a different cadence, and a different audience. Asking non-engineers to route policy changes through pull requests is a tax they will not pay. They will keep a Google Doc, and the skill in the repo will rot.

Koinoflow keeps the good parts of git (history, diffs, signed versions, rollback) and drops the part that does not survive contact with non-technical teams (the local clone, the terminal, the PR review). Every skill has a version log. Every version has a named owner and a change summary. The UI is the editor. The MCP server is the delivery.

Problem 3: sync is the actual hard part

Say Legal updates the NDA policy on Tuesday afternoon. By Wednesday morning, every agent in every function that touches NDAs needs the new version. Not a cached copy, not yesterday's branch, not "whatever was on my laptop when I last pulled". The new version.

In a git-distributed world, there is no mechanism that guarantees this. You can send a company email. You can ask everyone to pull. You can set up a cron that pulls on some machines. You cannot prove to an auditor that the skill every agent consumed on Wednesday was the correct one.

Because Koinoflow serves skills over MCP from a single source of truth, the question disappears. The agent asks for the skill, the server returns the current version (or a pinned one, if the caller asks), and the audit log records what was served to whom. A policy change is one edit, one review, one publish. Every agent in the company sees the new version on the next call. That is the loop git cannot give you without building a distribution system on top of it. So we built the distribution system.

The bonuses we did not build for

Two things showed up as side effects of solving the three problems above, and now they are how most people describe the product back to us:

• Fewer hallucinations. When the skill is versioned, owned, and re-attested on a cadence, the agent has an authoritative document to cite instead of paraphrasing a five-year-old Confluence page. The drop in made-up answers is the biggest quality change we saw in our own usage.
• Lower token bills. Loading one sharp skill (300 tokens) into the agent's context is cheaper than dumping a 40-page wiki export and hoping the model finds the right paragraph. At our scale the difference is real money. At enterprise scale it is a lot of money.

Both matter. Neither is the reason we started. We started because we could not figure out how to put a skill in front of the finance team without either breaking security or teaching them git.

Why open source

Three practical reasons pushed us over the line:

• Auditability. A governance layer between your AI agents and your company policies is not something you want to trust to a black box. With MIT on the repo, security review is a link instead of a questionnaire.
• Self-host by default. Several of the teams we talked to cannot send their process library to a third-party SaaS. Open source means they run it where their data already lives.
• Feedback from people who are not us. We have one company worth of edge cases. Exposing the code to teams with different shapes of operations (regulated industries, multi-entity groups, very large support orgs) will surface gaps we would not find on our own.

Visionect still maintains Koinoflow and still offers a hosted version for teams who want it. The hosted and self-hosted codebases are the same repo. We do not keep a better version behind a paywall.

What is actually in the repository

The repo at github.com/visionect/Koinoflow has everything we run in production:

• The Django backend, including the process model, version history, audit cadence jobs, and the staleness alerting we describe in the workspace policies post.
• The MCP server that exposes discover_skills, read_skill, list_skills, and the rest of the repo-backed toolset agents use to read the library and route changes through an explicit proposal/apply flow.
• The React front end, including draft-skill authoring flows and the Workspace settings panel for scope and policy toggles.
• Database migrations, seed data, a docker-compose for local dev, and the Terraform we use for our own deployment as a reference.

What open source does not fix

Flipping the license does not solve governance by itself. Koinoflow still requires work from you: naming owners, setting audit cadences, deciding which skills your non-technical colleagues can invoke and which ones stay engineer-only. An open-source tool with no owner is still a tool with no owner.

And we are not pitching this as a movement. It is a tool. If it helps, use it. If it does not, fork it and tell us what was wrong, or ignore it. Both are fine outcomes.

What to do next

Two paths, both free. Clone the repo, run docker compose up, and point an MCP-capable client at the local server. The README walks through registering a test skill, handing it to a non-technical user, and watching the version log update when the owner publishes a change.

If the infrastructure step is in the way, the hosted version at app.koinoflow.com runs the same code and comes with a free 30-day trial. No credit card, same feature set as the self-hosted build. Enough time to wire it up to your real skills and your real agents before deciding whether to self-host, stay hosted, or walk away. Issues and blunt feedback are welcome on GitHub either way.