agentleFS
pandemicsynpandemicsyn/neondeck/.agents/skills/flue/SKILL.md

flue

Skill8 starsChanged 2 months agoMITView on GitHub

Use when building, debugging, reviewing, migrating, or documenting Flue projects, including agents, hooks, tools, skills, subagents, sandboxes, routing, channels, persistence, schedules, observability, React clients, deployment targets, and CLI usage. Find and read version-matched Flue documentation before relying on API details.

3 other projects use a version of this.

Adopted by

Most recently taken up by

  • Other versions3 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 3

    1. shadcn-labs/agentcn★ 506same name
    2. SFKislev/Flue★ 102same name
    3. dhruvkelawala/loopwatch★ 2same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository2 other files it gives its agents.

The file

Show its rules and text

We split this skill into the rules it gives an agent

22 rules. 0 are common, 15 are distinctive, and 7 are very specific to this project.

  • 0

    Common

    Most of the 3 edited versions we read keep these.

  • 15

    Distinctive

    This author's own choices. Worth a look.

  • 7

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Treat every Flue API detail as versioned.

    line 8
  2. Very specific:

    Use the project-local flue executable.

    line 14
  3. Distinctive:

    Never combine examples from different Flue versions without explicitly reconciling the changed API.

    line 18
  4. Distinctive:

    Use the local CLI through the project's package manager so the repository's binary wins.

    line 22
  5. Very specific:

    Run flue docs search <query> with the exact concept, symbol, import, CLI flag, or error text.

    line 31
  6. Very specific:

    Run flue docs read <path> for the most relevant results and read each page completely before acting on it.

    line 32
  7. Very specific:

    Run flue docs with no arguments when terminology has changed or search results are ambiguous.

    line 33
  8. Very specific:

    If the local CLI is unavailable, inspect installed package types and source first.

    line 47
  9. Distinctive:

    Read enough material to verify all affected boundaries:

    line 51
  10. Distinctive:

    Search the repository for existing conventions and removed APIs before editing.

    line 55
  11. Distinctive:

    Treat compiler errors as prompts for another exact-symbol or exact-error docs search.

    line 56
  12. Distinctive:

    Keep these Flue 2 boundaries visible while migrating:

    line 63
  13. Very specific:

    Use Vite with @flue/vite; do not use the removed flue dev or flue build commands.

    line 65
  14. Very specific:

    Import SKILL.md directly without import attributes.

    line 70
  15. Distinctive:

    Use conversation-scoped SDK and React clients rather than the removed deployment-wide namespaces.

    line 72
  16. Distinctive:

    Treat that list as orientation, not an API reference.

    line 75
  17. Distinctive:

    Use an agent for continuing, addressable model conversations.

    line 79
  18. Distinctive:

    Use a tool for a typed capability the model or application can invoke.

    line 80
  19. Distinctive:

    Use a durable tool for a short checkpointed side-effect sequence owned by one agent turn.

    line 81
  20. Distinctive:

    Use application code for deterministic domain services, scheduling, and multi-step orchestration with its own state and inspection needs.

    line 82
  21. Distinctive:

    Use a skill for procedural guidance that shapes model behavior.

    line 83
  22. Distinctive:

    Run the repository's focused typecheck and tests, then the production Vite build when build, routing, generated exports, or deployment …

    line 89

“Common” is measured: kept by at least 6 in 10 of the 3 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Flue

Treat every Flue API detail as versioned. Inspect the project, search the relevant documentation, and read the matching pages before designing or editing code. Do not implement Flue APIs from memory.

Establish the Documentation Target

  1. Inspect package.json and the lockfile for the installed @flue/* versions.
  2. Decide whether the task targets the installed version or upgrades to a newer version.
  3. Use the project-local flue executable. Do not install or download another CLI merely to search its docs.

For maintenance work, prefer the documentation bundled with the installed @flue/cli; it matches the code being maintained. For upgrade work, read the target release's migration guide and current official docs until the dependency pins have been upgraded, then use the newly installed CLI docs.

Never combine examples from different Flue versions without explicitly reconciling the changed API.

Search, Then Read

Use the local CLI through the project's package manager so the repository's binary wins. For npm projects, use this loop:

npm exec -- flue docs search durable execution
npm exec -- flue docs read guide/durability

Apply these commands deliberately:

  • Run flue docs search <query> with the exact concept, symbol, import, CLI flag, or error text. The command returns up to eight ranked JSON results.
  • Run flue docs read <path> for the most relevant results and read each page completely before acting on it.
  • Run flue docs with no arguments when terminology has changed or search results are ambiguous; it lists every bundled page.
  • Pass a catalog path, docs URL, absolute docs path, or source Markdown filename to flue docs read.
  • Refine broad searches. For a cross-cutting change, search and read each affected surface rather than relying on one overview page.

Useful query shapes include:

npm exec -- flue docs search usePersistentState
npm exec -- flue docs search "tool result envelope"
npm exec -- flue docs search "conversation scoped client"
npm exec -- flue docs search "submission_settled"
npm exec -- flue docs search "<exact error message>"

If the local CLI is unavailable, inspect installed package types and source first. Then use only official Flue documentation at https://flueframework.com/docs/ as the network fallback. State when live docs target a different version than the installed packages.

Verify the Contract

Read enough material to verify all affected boundaries:

  • Confirm imports, signatures, return envelopes, statics, hook rules, route shapes, event fields, and CLI flags.
  • Inspect installed .d.ts files or runtime source when the docs do not answer a code-level question.
  • Search the repository for existing conventions and removed APIs before editing.
  • Treat compiler errors as prompts for another exact-symbol or exact-error docs search.
  • Record the Flue docs paths that materially informed the implementation in the handoff.

Migrate to Flue 2

For a 1.0.0-beta.9 to Flue 2 migration, read the live migration guide before editing. Use its ordered checklist as the migration sequence: pins, build, routing, agents, tools, skills, workflows, channels and database, providers, observability, clients, deployment, then verification.

Keep these Flue 2 boundaries visible while migrating:

  • Use Vite with @flue/vite; do not use the removed flue dev or flue build commands.
  • Mount each agent and channel explicitly in app.ts; do not use the removed auto-router.
  • Define agents as exported capitalized synchronous functions in a 'use agent' module and compose behavior with hooks; do not use defineAgent.
  • Replace Actions with tools. Use run({ data }) and return the documented tool result envelope.
  • Replace each Workflow with the smallest correct fit: an awaited init() handle, a durable tool, or an application-owned orchestrator.
  • Import SKILL.md directly without import attributes. Wrap other Markdown with defineSkill only when it must behave as a skill.
  • Attach a sandbox explicitly when filesystem or shell capabilities are required; Flue 2 provides no implicit sandbox.
  • Use conversation-scoped SDK and React clients rather than the removed deployment-wide namespaces.
  • Correlate observability with agent/submission events and instanceId/submissionId, not workflow runs.

Treat that list as orientation, not an API reference. Search and read the current target-version page for every item before implementing it.

Choose the Smallest Flue 2 Primitive

  • Use an agent for continuing, addressable model conversations.
  • Use a tool for a typed capability the model or application can invoke.
  • Use a durable tool for a short checkpointed side-effect sequence owned by one agent turn.
  • Use application code for deterministic domain services, scheduling, and multi-step orchestration with its own state and inspection needs.
  • Use a skill for procedural guidance that shapes model behavior.

For Neondeck, keep application SQLite state separate from Flue conversation/runtime persistence. Preserve one typed backend command and event surface for dashboard and future clients. Prefer deterministic Neondeck services for facts and mutations, and use Flue where model reasoning, conversation continuity, or model-facing tools add value.

Validate Changes

Run the repository's focused typecheck and tests, then the production Vite build when build, routing, generated exports, or deployment configuration changes. During a migration, re-run searches after upgrading the packages so final code is checked against the documentation bundled with the installed Flue 2 CLI.

Primary references:

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.