How the skill system works

MCP gives an agent access to the product. Skills are the rules by which it uses that access. Installing them is covered separately; what each one does is in the reference. This page is about why there are many of them and how they add up to one thing.

A skill is part of the product, not documentation about it

A skill is a Markdown file the agent reads and follows literally: which tool to call, in what order, what to write into the ticket, when to stop. Without skills the access remains and the behaviour disappears: the agent can still create nodes, but it will do so however it likes and lose context between sessions.

Hence a consequence that is not obvious from outside: a rule the server enforces and a rule the agent reads are one rule in two places, and both have to exist. A gate without a skill works, but meets the agent with a refusal where it expected success. A skill without a gate is an exhortation — learned the hard way: before the server-side checks existed, the discipline rested on the skill text and did not hold.

How a skill gets invoked

Two ways, and the second is the one used more often in practice.

By slash command — when you know exactly which skill you need:

/execute-task AF-TASK-42

By an ordinary request — the skill is picked up on its own, from its description. Each one lists its triggers in the frontmatter: both the shape of the task and the words people use to ask for it, in two languages. So all of this works without naming a skill:

take AF-TASK-42

we need CSV export, break it into tasks

connect this repository to Flownix

Two practical consequences. You don't need to name the skill — saying what you want is enough; the skill list is useful for understanding what the product can do, not for picking from it before every request. And a server refusal can be the trigger: flownix-write-spec is invoked on a mention of proposal_not_approved, and spec-first-change on spec_first_not_approved, so an agent that hits a gate finds the right instruction by itself.

Which skill owns what

There are many of them not because the procedure is complicated, but because every piece of it has a single owner.

The single-owner rule

The spec format is described in one skill, flownix-write-spec. The others link to it and do not restate it.

This is not tidiness but a conclusion drawn from a mistake. The format was once duplicated across five skills, and the predictable happened: the copies drifted, and the one people read is always the drifted one. So every rule has one home, and everywhere else there is a link — even where restating it would have been more convenient for the reader.

Handing work over

Skills are not a rigid pipeline, but there are transitions between them, and one of them matters.

plan-feature reads the project policy before it creates the first node. If spec-first is on it does not expand the task tree but hands the work to spec-first-change. The order of that check is deliberate: learning about the mode after the tree exists is too late — which is exactly what would happen if the skill read the policy halfway through.

The same principle in execute-task: when it hits a gate refusal it does not look for a way around but sends the agent back to the change. A refusal that does not name the way out is one an agent will try to bypass — also learned the hard way.

What the project policy changes

The three spec policies (in detail) change not only server behaviour but which skill leads the work:

The policy reaches the agent by two routes: it reads it with get_project_policy, and it sees it in the .flownix file written when the project was connected. The second route exists so the rule is known before the first call, not after the first refusal.

Your own skills beside the product's

A skill is ordinary Markdown, and your own live in the same directory. Synchronisation leaves them alone: in the sync-skills report they appear under LOCAL_ONLY and stay as they are.

The point of the separation is that the product's skills describe how Flownix works and yours describe how your team works. The first are updated with the product, the second live their own life, and mixing them into one file means losing one or the other at the next update.

When the agent does not behave as described

In order, most common first:

1. The skills are stale — /sync-skills. Check separately that retired skills were deleted: otherwise a renamed skill keeps sitting beside its new version and the agent reads the outdated instruction without giving any sign.
2. The agent has not read flownix-basics — the other skills assume it has, and without it the agent knows neither about components nor that the ticket serves as memory.
3. The policy is not what you think — get_project_policy returns it together with a human-readable statement of what it requires. Compare that with .flownix: a mismatch means the file is stale.
4. A skill was read, but the wrong one — with spec-first on the procedure is led by spec-first-change, not plan-feature; if the agent is expanding a task tree, it is reading the latter.

Next

• Installing skills — four ways to install and one to keep them current
• Skill reference — what each one does
• Spec modes — the three policies
• Spec-first mode — the order of work spec-first-change owns