# Customizing Flow

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

## Overview

`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.

## Your own docs

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

```md [.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.

### Writing a good doc

- 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.

## Your own skills

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.

```md [.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.

### Writing a good skill

- 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.

## Your own lenses

Put a lens in `.flow/custom/lenses/`, and add it to `.flow/review.yml`. [Lenses](/docs/flow/reviews/lenses#writing-your-own-lens) shows the sections a lens needs, and how to write a good one.

## Placeholders

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

::::field-group

:::field{name="__FLOW_SKILL_<name>__"}
The installed name of a skill, such as `flow-code-placement`, or one of yours.
:::

:::field{name="__CONTEXT_FILE__"}
The context file of the agent: `CLAUDE.md` for Claude Code, `AGENTS.md` for the others.
:::

:::field{name="{{PM_INSTALL}}"}
The install command of your package manager, such as `npm install`.
:::

:::field{name="{{PM_RUN}}"}
The run command of your package manager, such as `npm run`.
:::

::::

## Sharing across apps

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.

```sh
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.

## Next steps

::card-group
:::card{title="Lenses" to="/docs/flow/reviews/lenses"}
The built-in lenses, and writing your own.
:::

:::card{title="Knowledge base" to="/docs/flow/knowledge-base"}
The docs Flow installs, and the packages they cover.
:::
::
