How-to guide

Instructions, agents and skills¶

Three things shape how Nawa works beyond what you type into a chat: instruction files you write, the agents Nawa delegates to, and the skills those agents can pick up.

Instruction files: `AGENTS.md`¶

An AGENTS.md file holds standing instructions in plain Markdown — conventions, commands, preferences, rules. Nawa reads the files that apply and hands them to the model, complete and current, with every request. The filename is exactly AGENTS.md; AGENT.md, NAWA.md and CLAUDE.md are not read.

Where a file lives decides what it governs:

File	Governs	When two disagree
`%APPDATA%\Nawa\config\AGENTS.md`	Every chat and project on this profile	A project or directory file overrides it
`AGENTS.md` at the root of a project (or of a chat's own workspace)	That project — its lead and the agents it delegates to	Overrides the profile file; a nested file overrides it
`AGENTS.md` in a directory of the project	That directory and everything under it, not its siblings	The deepest applicable file wins
What you say in the chat	The current task	Outranks any file; permissions still apply

The profile file and the project root are read for every request. A nested file is read once Nawa works in its directory — through a file it reads, writes or lists, a command it runs there, or a directory you name — and Nawa is told to check for one before acting in a directory it has not used yet.

Some rules of thumb for what goes where: "Answer in concise English" belongs in the profile file; "run npm test before you finish" in the project root; "reports go in reports/" in reports/AGENTS.md. Keep the rule in the narrowest place it applies.

Changes take effect at the next request; a request already in flight keeps the snapshot it started with. A missing file is normal; a file that cannot be read is reported, never skipped silently. Nothing in an instruction file grants a permission, and a web page or attachment that happens to be named AGENTS.md is not an instruction file.

Create or change one¶

Ask in the chat, with ordinary words:

"Create an AGENTS.md for this project from its build and test commands."
"Remember in this project's AGENTS.md that final reports go in reports/, replacing the old rule."
"Move my preference for short replies to my profile-wide AGENTS.md; leave the project commands in the project."

Nawa edits the file with its ordinary file tools, where you asked, and nowhere else. It does not rewrite instruction files on its own.

Agents¶

For work that deserves a context of its own, the lead delegates to an agent: a role with its own instructions, tools, model and effort. Nawa ships five built-in agents:

coder — writes, edits, runs and verifies code in a workspace, using the coding model of the active setup.
web-researcher — searches and reads the web and returns evidence; the lead writes the answer.
capability-researcher — researches a model's reasoning controls, effort levels and context window from its official documentation, verifies them, and records the model in the capability configuration.
code-reviewer — reviews existing code for correctness, security, reliability and maintainability risks when you ask for a separate review, audit or hardening assessment.
fact-checker — collects sources for specific claims when you ask for fact-checking.

An agent is a Markdown file with a front matter of name, description, tools, model and effort, followed by its instructions. The built-in agents ship with the app, under agents/defaults/ in the source tree. The agents you create or customize are saved in your profile, as %APPDATA%\Nawa\data\agents\<name>.md. The delegation and its result appear in the transcript like any other step, with the agent's own receipts.

Create, select and restore an agent¶

Ask Nawa to list the available agents before choosing a name. Then describe a role conversationally: “Create an agent called copy-editor that checks clarity and tone, with no workspace editing.” Review the instructions and tool access it proposes. The new role is available from your next message.

Select an available agent from the composer's agent menu or ask the lead to delegate to the named role. To change it, name the agent and the instruction to add or remove. To remove a custom role, ask Nawa to delete it and confirm the deletion.

Built-in agents are immutable and cannot be deleted. Customizing one saves your version in your profile, where it shadows the stock role; ask to restore that agent to remove your version. Updates never overwrite the agents you created or customized. Restore is different from deleting a custom-only agent.

Skills¶

A skill is a packaged procedure — a SKILL.md with a name, a description of when it applies, and step-by-step instructions, with any scripts and reference files beside it. Nawa ships skills for producing Word, PowerPoint and PDF documents, briefing on a person or company, systematic debugging, test-driven development, verifying before completion, testing web apps, reviewing for compliance, and writing new skills. Plugins can bring skills of their own.

The model chooses a skill when a task matches its description; you can also name one. Skills live under data/skills/<name>/ in the profile.

Create and maintain a skill¶

Ask: “Create a reusable skill for our monthly report, with its input requirements, steps and checks.” Give a representative example and say when the skill should apply. Review its SKILL.md and any supporting files before relying on it. Select it from the skills menu or explicitly name it in a request to try it.

Ask to edit or delete the named skill when the procedure changes. A plugin-owned skill is maintained with its plugin; avoid assuming a local edit survives plugin replacement. Skills provide instructions, not extra permissions. Keep access credentials in provider or connector settings, never inside a skill.