User Docs

# The frink-flows skill

Frink's agents use the `frink-flows` skill to design, edit, validate and inspect Flows. The skill explains contracts; the `frink_flows_*` MCP tools read and change live flows.

## What the agent reads

The skill's name and description make it discoverable. On a relevant request, the agent reads `SKILL.md`: a short authoring workflow, graph essentials and an intent-to-reference table. It then opens only the relevant guides.

Nine references cover triggers, webhook aliases, action contracts, graph/logic, templates and shared context, examples, batches, run inspection and custom nodes. Each block's configuration and generated output fields are together, so wiring it does not require a separate output-schema lookup. The examples include a complete fan-out patch with two contained branches, a condition and text/HTML reporting.

`SKILL.md` is the reference index. Start there rather than bookmarking individual reference filenames, which can change as guidance is consolidated.

## Installation and local edits

| Location | Purpose |
|---|---|
| `<app>/assets/skills/frink-flows/` | Release bundle |
| `~/.frink/skills/frink-flows/` | Canonical editable copy |
| `~/.agents/skills/frink-flows/`, `~/.claude/skills/frink-flows/`, `~/.cursor/skills/frink-flows/` | Real copies projected for agent discovery |

These are real copies, not symlinks. Edit the canonical copy, restart Frink so it projects changes, then start a new agent session. A local edit in a projected provider copy can prevent Frink from replacing that copy; it does not write back to the canonical skill.

To add a project-specific pattern, add a Markdown reference in the canonical skill and link it from `SKILL.md`. To change block guidance, follow the router to its current reference. Keep an edited router consistent with its references. Do not edit `.baseline.json`; it records shipped hashes used to distinguish your edits from release content.

## Updates

Frink compares the full shipped content manifest, not just the app version. When it changes:

- Unmodified or missing shipped files take the new release content.
- Locally edited files are preserved with their old baseline entry; Frink logs a warning naming them.
- User-added files remain untouched.
- Clean files removed from the release are removed; edited retired files survive.

To adopt the shipped version of a canonical file you edited, delete that file and restart Frink. Deleting the baseline instead removes the information needed to merge safely and causes Frink to leave the directory alone. Older whole-skill `-rejected` update directories are obsolete and cleaned up on boot.

If guidance stays stale, check whether the canonical file or the provider's projected copy was edited. Restarting a chat alone does not synchronize provider copies. Frink preserves user-authored collisions instead of silently overwriting them.

To narrow automatic activation, edit the canonical `SKILL.md` description. Removing a projected copy is temporary: Frink recreates it at boot.

## Developer maintenance

The hand-authored entrypoint is `assets/skills/frink-flows/SKILL.md`. Reference content is maintained in `src/main/lib/mcp/flows-tools/guidelines/`; `scripts/build-skill-content.ts` renders those modules and builds the content-hashed baseline. Edit those sources, then run `bun run build:skills`; do not hand-edit bundled reference Markdown.

Output, trigger and loop tables come from runtime schema constants; provider aliases come from the shared alias registry. The build drift check verifies generated bytes, the reference-integrity test checks links and router coverage, and example tests apply the documented patch through the real patch engine and graph/template validators. The pre-commit skill gate runs `bun run build:skills:check`; packaging regenerates the bundle.

Related: [Flows](../user-docs/flows.md), [MCP servers](../user-docs/mcp-servers.md).