Flow installs its docs, skills and lenses in your project. This guide shows how to add your own, or replace one of Flow's, so your agent follows the rules of your app too. You will learn how to:

  • Write your own docs and skills, and their descriptions
  • Use placeholders in your files
  • Share them across apps with an npm package

npx @adonisplus/flow install collects docs, skills and lenses from three sources, in this order:

  1. Flow's own files.
  2. Each npm package listed in sources of flow.lock, in its order.
  3. .flow/custom/ of your app, which you commit.

When two sources have a file with the same name, the later one wins. So a file in .flow/custom/ replaces Flow's, and the installer writes the result for each of your coding agents. Run npx @adonisplus/flow install again after you change a file.

Put a doc in .flow/custom/docs/. Its frontmatter needs a description, which tells your agent when to read it.

.flow/custom/docs/billing.md
---
description: How the app charges customers, its plans, and the Stripe webhooks it handles.
---

# Billing

…

A doc with the same name as one of Flow's replaces it, and keeps Flow's description unless you give one.

Folders and file names narrow where a doc applies:

  • In <package>/<major>.x/, such as @adonisjs/lucid/21.x/, the doc installs only when your app uses that major of the package.
  • A file named after a stack, such as react.md, installs only for that stack: api, hypermedia, react or vue.
  • index: false in the frontmatter keeps the doc out of the docs index, for a doc that other docs link to.
  • Write for your agent, not for a new teammate. Leave out what an agent already knows about AdonisJS and TypeScript. Write down the decisions of your app that an agent would otherwise make up, such as which service charges a card, or how amounts are stored.
  • State each rule directly, with a short example from your code. Explain why only when the reason changes how the rule applies.
  • Keep one subject in a doc. When another doc already gives a rule, link to it instead of repeating it.
  • The description decides when your agent opens the doc. Name what the doc covers and when it matters, like "How the app charges customers, its plans, and the Stripe webhooks it handles." A label such as "Billing docs" does not tell the agent when to read it.

Put a skill in its own folder in .flow/custom/skills/, with a SKILL.md. The folder name is the skill's name. Other files in the folder, such as references/, install with it.

.flow/custom/skills/billing-changes/SKILL.md
---
description: Use before you change a plan, a price or a Stripe webhook.
trigger: implicit
---

# Billing changes

…

trigger decides who starts the skill:

  • implicit, the default: your agent starts it when the description fits, and you can start it too.
  • explicit: only you start it.
  • internal: only other skills use it.

A skill with the same name as one of Flow's replaces it, and installs as flow-<name>. A folder name that starts with flow- stops the install, because that prefix is Flow's.

  • A skill settles one decision your team makes again and again, such as how to change a price. Give the answer your team chose, not a list of options.
  • Keep SKILL.md to the steps. Put long examples in references/, and link to docs for the rules they already give.
  • The description decides when your agent starts the skill. Start with "Use before" or "Use when", and name the tasks and files that should start it, like "Use before you change a plan, a price or a Stripe webhook." A vague description, such as "Helps with billing", starts the skill at the wrong times, or never.

Put a lens in .flow/custom/lenses/, and add it to .flow/review.yml. Lenses shows the sections a lens needs, and how to write a good one.

Your docs, skills and lenses can use the placeholders that Flow's own files use. The installer replaces them for each app and agent.

__FLOW_SKILL_<name>__
The installed name of a skill, such as flow-code-placement, or one of yours.
__CONTEXT_FILE__
The context file of the agent: CLAUDE.md for Claude Code, AGENTS.md for the others.
{{PM_INSTALL}}
The install command of your package manager, such as npm install.
{{PM_RUN}}
The run command of your package manager, such as npm run.

To share docs, skills and lenses across apps, publish them as an npm package with docs/, skills/ or lenses/ at its root. Each folder has the layout of .flow/custom/.

Install the package as a dev dependency, then add it to the sources.

Terminal
npx @adonisplus/flow install --source=@acme/flow-kit

--source can repeat. Its order is the order of sources in flow.lock, and a later package wins over an earlier one. .flow/custom/ still wins over every package. When you remove the package from package.json, the next npx @adonisplus/flow install removes its files.

Lenses

The built-in lenses, and writing your own.

Knowledge base

The docs Flow installs, and the packages they cover.