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 — and the notes Nawa keeps for a chat. 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 Nawa's next model request, including one later in the same reply. 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. Apart from its notes, below, it changes instructions only where you ask.

Nawa's notes for a chat¶

The AGENTS.md at the root of a chat's own folder is also that chat's memory. When you set a requirement, correct something or settle a decision, or Nawa checks a fact worth keeping — a root cause, a workaround, where a file lives — it writes a short line in the file's Notes section, fixes or removes lines that go stale, and tells you. In a project, the project's AGENTS.md is shared by every chat in it. Nawa never copies instructions from files, web pages or tool results into it.

Open the file from the chat's Files panel to read it, and edit or delete any line; every change is kept in the folder's history. Facts about you that should follow you to every chat belong in memory instead.

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 saved for the chat.
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 Word, PowerPoint and PDF skills design the whole document: ask for “a board deck on our Q3 results in our brand”, “a proposal for Gulf Retail as a Word document” or “an invoice for Contoso as a PDF”, and attach your logo, an existing deck or your company template. The PDF skill also works on PDFs you already have: merging, splitting, filling forms, redacting, extracting tables to Excel, protecting with a password and more. For a new document without a supplied design, Nawa can show the opening pages or slides in three styles for you to choose from, and an outline before it builds a long deck. When you attach a PowerPoint template or existing deck, its designs take precedence; Nawa should preserve them and report any rendering limitation. The PowerPoint, PDF, Word and Skill Creator entries have distinct icons at the same size as Computer Use. Ask for changes in plain words (“darker”, “use our blue”, “split slide 4”); it rebuilds the same file.

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. An update upgrades the built-in skills you have not changed, adds new ones once, and removes built-in skills Nawa no longer ships unless you changed them; your own skills and your changes are kept.

Create and maintain a skill¶

Describe the outcome you want: “Create a skill that turns our monthly sales figures into a polished report.” Give an example or preferences if you have them. Nawa chooses the package structure, checks tools and dependencies, supplies useful supporting files, and tests the saved skill. It asks about missing requirements that affect your result; you do not need to specify libraries or how skills are stored. Review the sample results and reported limitations. Select the skill from the skills menu or name it in a request to try it.

The creator can bundle scripts, reference documents, and templates. Saving validates the package before making it available; it does not run its scripts or prove its behavior. Ask: “Create a skill for checking our invoices, then test whether it improves accuracy and token use.” Nawa can offer a repeatable comparison in fresh scratch chats, with the skill available in one arm and omitted in the other. The results include a review page, output checks, activation, elapsed time, tool calls, and available token counts. These trials use your configured models and normal permissions; actions on external services or the desktop can still have real effects. The native evaluator retains a separate Chromium profile for diagnostics, with its path in report.json; it imports no production browser data and removes temporary model settings and keys.

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.