Load skills and project resources

Nerve builds each agent run from global and project resources. Resources apply to subsequent runs; changing a file does not rewrite an already-sent provider request.

Context and system instructions

Nerve loads global agent AGENTS.md, then files from ancestors root-to-project. A project SYSTEM.md overrides the global system resource. Global and project append prompts are concatenated where defined.

Project-specific Nerve resources live under .nerve/. Portable shared agent skills live in .agents/skills/ in the project or its ancestors. Global Nerve agent resources live under <NERVE_HOME>/agent/; global portable skills live under ~/.agents/skills/.

Legacy .pi directories are not loaded.

Skill files and discovery

Nerve recursively discovers SKILL.md files below each configured skills directory. It also accepts Markdown files placed directly at that directory’s root. .gitignore, .ignore, and .fdignore rules are honored while walking.

A skill needs a nonempty description. A directory-based skill’s lowercase, hyphenated name must match its parent directory; invalid files are skipped and surfaced as diagnostics. Nerve gives the model each discoverable skill’s name, description, and location, then reads the full file only when the skill is used. Set disable-model-invocation: true when a skill should remain available for explicit application use without being advertised to the model.

Skill precedence

First definition by skill name wins. Effective discovery favors project Nerve skills and ancestor portable project skills, then global Nerve and global portable skills, enabled Built-in Nerve skills, and finally enabled Agent Browser guidance. Disabled definitions are removed before precedence is resolved. Review the exact resource precedence table when two definitions share a name.

Use Settings → Skills to inspect discovered scope and toggle a skill without deleting its file. The Built-in Nerve skills group contains official guidance shipped with Nerve. Built-in skills are disabled by default and add nothing to the system prompt until enabled. The initial skill-creator skill helps create valid project or user skills.

The User scope supplies defaults for every project. The Project scope writes sparse, shareable overrides to .nerve/config/capabilities.json; settings without an override continue to follow the user default.

Project capability files are locally trusted by exact content digest. A new or externally changed file remains visible for review but inactive until trusted. Conversation overrides are local to the conversation and take precedence over trusted project values. Capability changes apply when the next agent run is prepared.

Values resolve field by field in the order user → project → conversation. Tool settings (models, image output defaults, and the Kroki server) resolve per tool instead: the nearest level that sets a tool’s settings supplies all of them. A level stores only values set on that level; setting a value back to what the level would inherit removes the override. Later changes to user or project settings never rewrite a conversation’s own values: they stay until you reset them, and the tools menu marks them as set in the conversation even when they currently match the project.

Capability file format

A project capability file contains only values the project pins:

{
  "schemaVersion": 2,
  "tools": {
    "web_search": { "enabled": true, "profileId": "team-search" },
    "python_exec": { "enabled": false },
    "jira": { "enabled": true, "profileId": "team-atlassian" },
    "confluence": { "profileId": "team-atlassian" }
  },
  "skills": {
    "file": { "release": false },
    "nerve": { "skill-creator": true },
    "agentBrowser": { "core": true }
  }
}

Missing entries and missing fields inherit. profileId is accepted only for jira, confluence (Atlassian profiles), and web_search (Tavily profiles). Profiles and their credentials stay in user settings; a profile ID that does not exist on a machine is reported as not found and the tool is not offered there. Version 1 files with boolean tool values are still read and are rewritten as version 2 on the next edit. Unknown tool names are rejected; skill names unavailable on one machine remain dormant so a shared project remains portable. Tool and skill selection fields formerly placed in project .nerve/config/harness.json must be moved to capabilities.json; unrelated harness settings remain in harness.json. Likewise, Jira, Confluence, and Web profile selections (tools) in project .nerve/config/integrations.json must move to capabilities.json; that file keeps only profile definitions.

Trust

Skills and context files are instructions supplied to the model. A repository can contain instructions that ask for tools, credentials, network calls, or destructive actions. Review unfamiliar resources before increasing permission beyond supervised.

Built-in Nerve and Agent Browser skills are appended only when explicitly enabled. File skills override both, and Built-in Nerve skills override same-named Agent Browser guidance. Agent Browser skills are prompt guidance from an external CLI, not a native browser automation tool.