Reference4 min read

Files & Directories

Every special file the product reads: rules, ignore, modes, commands

Nexgile Code reads a family of special files that let you configure rules, modes, agents, commands, skills, tools, and integrations — per project (checked into your repo) or globally (in your home directory). This page is the complete map: every path, its scope, what it does, and where to read more.

Project files (workspace root)

Path	Scope	Purpose	Details
`.nexgilerules`	Project	Project conventions injected into every prompt	Rules Files
`.nexgilerules-<mode-slug>`	Project	Rules applied only in one mode (filename must match the slug exactly, e.g. `.nexgilerules-code`)	Rules Files
`.nexgile/rules/*.md`	Project	Directory form of rules — multiple organized files instead of one	Rules Files
`.nexgile/rules-<mode-slug>/*.md`	Project	Directory form of mode-specific rules; wins over the single-file variant	Rules Files
`.nexgileignore`	Project	Files the agent must not read or touch (gitignore syntax); must sit at the workspace root	.nexgileignore & Protected Files
`.nexgilemodes`	Project	Custom mode definitions (YAML `customModes:` list)	Custom Modes
`.nexgile/agents/*.md`	Project	Custom agents — one markdown file per agent (frontmatter + body as system prompt), live-reloaded	Custom Agents
`.nexgile/commands/*.md`	Project	Slash commands — filename becomes the command name	Slash Commands
`.nexgile/skills/<name>/SKILL.md`	Project	Skills — reusable instruction packages loaded on demand	Skills
`.nexgile/skills-<mode-slug>/<name>/SKILL.md`	Project	Skills available only in one mode	Skills
`.agents/skills/<name>/SKILL.md`	Project	Shared cross-agent skills directory (lower priority than `.nexgile/skills/`)	Skills
`.nexgile/mcp.json`	Project	Project-level MCP server configuration	Configuring MCP Servers
`.nexgile/tools/*.ts`	Project	User-defined tools — experimental, requires the `customTools` experiment	Tool Reference
`AGENTS.md` / `AGENT.md`	Project	Agent-rules files loaded when `nexgile-code.useAgentRules` is on; `/init` generates `AGENTS.md` for you	Rules Files
`AGENTS.local.md`	Project	Personal, typically git-ignored companion to `AGENTS.md`	Rules Files

Directories the agent writes to

Two paths are outputs rather than configuration — they don’t exist until a mode that uses them runs, and those modes are restricted to writing nowhere else:

Path	Written by	Contents
`.nexgile/extraction/`	📚 Docs Extractor	Extraction results as `.yaml`, `.json`, and `.md`
`agent_generated/database/`	🗄 DB Architect	`diagrams/` (Mermaid ERDs) and `plans/` (schema design documents)
`agent_generated/architecture/`	📐 Code Architect	`diagrams/` (Mermaid flowcharts, sequence, class, ERD, state), plus a self-contained HTML viewer for them

Both are safe to delete and regenerate. Add agent_generated/ to .gitignore if you’d rather not track diagrams; keep .nexgile/extraction/ out of commits for the same reason. See Specialist Modes.

Global files (`~/.nexgile/` in your home directory)

Path	Scope	Purpose	Details
`~/.nexgile/rules/*.md`	Global	Rules applied in every workspace	Rules Files
`~/.nexgile/rules-<mode-slug>/*.md`	Global	Global mode-specific rules	Rules Files
`~/.nexgile/commands/*.md`	Global	Slash commands available everywhere	Slash Commands
`~/.nexgile/agents/*.md`	Global	Custom agents available everywhere	Custom Agents
`~/.nexgile/skills/<name>/SKILL.md`	Global	Skills available everywhere (plus `~/.nexgile/skills-<mode>/` mode-scoped)	Skills
`~/.agents/skills/<name>/SKILL.md`	Global	Shared cross-agent skills (lower priority than `~/.nexgile/skills/`)	Skills
`~/.nexgile/tools/*.ts`	Global	User-defined tools — experimental	Tool Reference

Precedence, in one sentence: project definitions beat global ones on a name collision, .nexgile/ locations beat the shared .agents/ locations, the directory forms of rules beat the single-file forms, and for slash commands the order is project → global → built-in.

Extension storage (managed for you)

Two configuration files live in the extension’s own settings area rather than your repo. Both are opened for you from the relevant settings UI — you rarely need to find them by hand:

File	Purpose
`custom_modes.yaml`	Global custom modes (available in every project) — edited via the Modes settings
`mcp_settings.json`	Global MCP server configuration — opened from the MCP settings view

Task data also lives in extension storage, under your editor’s global-storage directory for nexgile.nexgile-code:

tasks/<task-id>/ — one folder per task: api_conversation_history.json (the full model conversation), ui_messages.json (what you saw in chat), task_metadata.json
settings/ — the two files above

To relocate all of it (for example to a larger drive), set nexgile-code.customStoragePath to an absolute path, or run Set Custom Storage Path from the Command Palette. Checkpoint data (the shadow git repository) is likewise kept outside your project — your project’s git log is never touched. See Checkpoints.

Protected files

These patterns are write-protected: the agent can never modify them without your explicit approval, even when write auto-approval is on (unless you also enable alwaysAllowWriteProtected):

.nexgileignore
.nexgilemodes
.nexgilerules*
.nexgile/**
.vscode/**
*.code-workspace
AGENTS.md
AGENT.md

The logic is self-preserving by design: everything that configures the agent’s own behavior — plus your editor workspace settings — requires a human in the loop to change. Protected files are marked with a shield in approval prompts.