Agent skills

Introduction

A coding agent knows Rust. It doesn't know that a Navree route without an access attribute won't compile, that services take the request's &Uow, or that navree make:module registers the module for you. Agent skills teach it, one task at a time.

A skill is a folder with a SKILL.md file: YAML front-matter with a name and a description that says when to use it, then the steps, the commands, a code template, the checks to run and the mistakes to avoid for one task. Agents that support skills, Claude Code and a growing list of others, read every skill's description when a session starts and load a skill's body only when the task matches. A project can carry every Navree skill for the cost of a few lines each.

The skills live in the skills/ directory of the Navree repository. Every API a skill names exists in the framework, and its code templates compile against the current navree crate.

The skills

Start with navree. It explains what a Navree app is, how one is laid out, the rules every change follows, and which skill to load for each task, so an agent that loads it first finds the rest.

The skills/README.md in the repository lists the same set. It grows with the framework, and navree skills:install always installs the skills of your Navree version.

What a skill looks like

Every skill follows the same shape. This is the beginning of navree-validation:

---
name: navree-validation
description: Validates request input in Navree with garde DTOs and the `Valid` and `ValidAsync` extractors. Covers DTO rules, Navree's extra rules (`one_of`, `uuid`, `date_ymd`, `confirmed`), required fields, nested data, database rules (`AsyncRule::unique`, `exists`), custom rules and messages, manual `ValidationErrors`, the 400 response shape and tests. Use when writing a request body or query DTO, adding or customizing validation rules or messages, checking uniqueness against the database, or when a test expects a 400 with `errors`.
---

# Validation

Navree validates input before the handler runs. Describe the rules on a DTO
with garde, take `Valid<Json<T>>` (or `Valid<Query<T>>`, `Valid<Form<T>>`)
in the handler, and invalid input becomes a 400 with one message per broken
rule. The DTO lives in the module's `dto.rs`.

## Steps
...

• The description is what the agent sees before it loads the skill. It says what the skill covers and, after "Use when", the situations and the words that should bring it in: "adding a role", "a 403 I don't expect", "database is locked".
• The body gives the steps in order, then a template that compiles, the response or output to expect, the options, a test, the common mistakes and links to these docs.
• References. Larger skills keep detail in a references/ folder next to SKILL.md (navree-database/references/migrations.md), which the agent reads only when it needs that part.

Installing skills

Install the skills into your project, so every teammate's agent has them, and commit them with your code.

navree skills:install

npx skills add NavreeHQ/navree

The site serves the skills too, for agents that fetch them over HTTP: https://navree.com/skills/index.json lists every skill with its name and description, and each one is at https://navree.com/skills/<name>/SKILL.md.

How agents use skills

You don't call a skill; the agent does, when your request matches its description. Ask in your own words:

Add an endpoint that lets a manager reassign a deal to another rep, and test it.

An agent with the Navree skills reads navree (a Navree app, so the umbrella applies), then navree-controllers-and-routing for the route and navree-access-control for "a manager", and follows their steps: generate, write the route with #[can(Manage, Deal)], take the input through Valid<Json<T>>, write the test with TestApp, then run cargo fmt, cargo clippy --all-targets -- -D warnings and cargo test.

To bring a skill in yourself, name it: "Use the navree-database skill to add a lost_reason column". In Claude Code, you can check which skills are installed by asking "Which skills do you have?".

Skills work best with the other two pieces of Navree's agent support:

• AGENTS.md, written by navree new, holds the conventions of your app and is read at the start of every session. Skills hold the how-to of each task and are read on demand. See AGENTS.md and CLAUDE.md.
• Navigator lets the agent check its work against the running app: that the new route is in the route table, that the provider resolves, that the migration ran.

Writing your own skills

The Navree skills know the framework; they don't know your app. Write skills for the tasks your team repeats, in the same folders, next to the Navree ones. A CRM team adds a pipeline stage now and then, and it touches four places:

---
name: crm-pipeline-stages
description: Adds, renames or reorders a deal stage in the CRM pipeline. Covers the Stage enum, win probabilities, board labels, closing rules for won and lost, the abilities that depend on stages, and the tests. Use when the user asks for a new pipeline stage, a stage rename, a different stage order, or a change to a stage's probability.
---

# Pipeline stages

Stages are the `Stage` enum in `crates/crm-core/src/enums.rs`, stored as a
string (at most 16 characters) in `deals.stage`. Board order is the enum's
order. Paths are relative to `apps/crm-api/`.

## Steps

1. Add the variant to `Stage` inside `string_enum!`, in board order, with its
   wire name (`Demo => "demo"`). Keep names to 16 characters: the column is
   `String(StringLen::N(16))`, so no migration is needed.
2. Give it a probability in `Stage::probability` and a column title in
   `Stage::label`.
3. If it closes a deal, add it to `Stage::is_closed` and to the closing
   rules in `crates/crm-deals/src/stages.rs`.
4. Check `crates/crm-core/src/abilities.rs`: the rules that forbid reps
   from moving or deleting closed deals match on `won` and `lost`.
5. Add the stage to the web app's board columns in `../crm-web`.
6. Test: a deal created in the new stage, a move into it and out of it, and
   the board response listing it in order (`crates/crm-deals/tests`).

## Checks

cargo test -p crm-deals -p crm-core
cargo clippy --all-targets -- -D warnings

## Common mistakes

- Reordering variants changes the board order for everyone; say so in the
  change description.
- Renaming a wire name breaks existing rows: add a migration that updates
  `deals.stage`, never rename in place.

What makes a skill work:

• One task per skill. "Pipeline stages", not "Everything about deals". Small skills load only when needed and stay accurate.
• A description with the user's words. The agent matches requests against it. List the situations ("a new pipeline stage", "a stage rename") and the symptoms ("deals disappear from the board").
• Steps in order, with paths. Name the files, types and commands as they are in your code, and grep for each before you write it down. A skill that names an API that doesn't exist teaches the agent to invent.
• A way to check. End with the commands that prove the change works.
• Mistakes you have seen. The section agents learn most from is the one that lists what went wrong last time.

Keep project skills in version control and review them like code. When a convention changes, change the skill in the same pull request.