Skip to content
Nx IDEDocs

Customization5 min read

Skills

Reusable instruction packages the agent loads on demand

Skills are reusable instruction packages the agent loads on demand — deep, task-shaped knowledge that would be wasteful to inject into every prompt the way rules files are. A skill for “how we do database migrations” might be 60 lines of procedure; the agent only pays for those lines in tasks that are actually about migrations. Nexgile Code ships no built-in skills: the catalog is yours to create, and it starts empty.

How skills work

Section titled “How skills work”

At task start, the agent is shown a compact catalog of the skills available in the current mode — each entry is just the skill’s name and description. The agent is required to check that catalog against your request before responding: if exactly one skill clearly applies, it calls the skill tool to load that skill’s full instructions into context, then follows them; if none applies, it proceeds normally and loads nothing. Two properties make this cheap and smooth:

  • Progressive disclosure. Only name + description ride along by default; the body loads when needed, and files a skill links to are read only if the task calls for them.
  • Always auto-approved. Loading a skill never raises an approval prompt — skills are content you explicitly installed, so the skill tool is on the same always-approved footing as todo-list updates.

You can also load one yourself: typing /skill-name in chat works like a slash command (real slash commands win naming ties).

Anatomy of a skill

Section titled “Anatomy of a skill”

A skill is a folder whose name is the skill name, containing a SKILL.md file — YAML frontmatter plus a Markdown body:

.nexgile/skills/
└── database-migrations/
    ├── SKILL.md          # required: frontmatter + instructions
    └── templates/        # optional supporting files the skill can reference
        └── migration.ts

Frontmatter fields:

Field Required Constraints
name Yes Must exactly match the folder name. 1–64 chars; lowercase letters, numbers, hyphens; no leading/trailing/consecutive hyphens.
description Yes 1–1024 chars. This is the trigger — it’s how the agent decides the skill applies, so write it as “Use when…”.
modeSlugs No List of mode slugs the skill is limited to. Omit for “any mode”.

A skill violating these rules (name/folder mismatch, bad name format, missing description) is skipped at discovery time.

Locations and precedence

Section titled “Locations and precedence”

Skills are discovered from Nexgile-specific directories and from the shared cross-agent .agents convention (usable by other tools too):

Priority Location Scope
1 (highest) <project>/.nexgile/skills/<name>/ and <project>/.nexgile/skills-{mode}/<name>/ This project
2 ~/.nexgile/skills/<name>/ and ~/.nexgile/skills-{mode}/<name>/ All projects
3 <project>/.agents/skills/<name>/ (+ skills-{mode}/) This project, shared convention
4 (lowest) ~/.agents/skills/<name>/ (+ skills-{mode}/) All projects, shared convention

When names collide: project beats global, .nexgile beats .agents at the same scope, and a mode-restricted skill beats a generic one of the same name in its modes. Symlinked skill folders are supported, and all locations are watched — add, edit, or delete a SKILL.md and the catalog refreshes automatically.

Creating a skill

Section titled “Creating a skill”

From the UI: open Settings → Skills, create a new skill with a name, a description, Project or Global scope, and optional mode restrictions. Nexgile Code scaffolds the folder and a starter SKILL.md and you fill in the instructions. The same view lets you open, delete, and re-scope existing skills.

By hand: create the folder and SKILL.md yourself — the watcher picks it up on save. Because skills live under .nexgile/ (or .agents/), project skills are committed and shared with your team like any other file, and they’re write-protected against silent agent edits.

Worked example: a “database-migrations” skill

Section titled “Worked example: a “database-migrations” skill”

.nexgile/skills/database-migrations/SKILL.md:

---
name: database-migrations
description: Use when creating, editing, or reviewing database schema
  migrations — covers naming, reversibility, safety checks, and the
  exact commands for this project.
modeSlugs:
  - code
  - db-migrator
---


# Database Migrations


## Creating a migration


1. Generate the file — never hand-create or rename:
   pnpm migrate:create <verb>-<subject>   # e.g. add-invoice-index
2. Implement BOTH directions. down() must fully reverse up().
3. Wrap multi-statement changes in a transaction.


## Safety rules


- No destructive statement (DROP, DELETE, TRUNCATE, column removal)
  without a preceding backfill/step plan in the migration's comment.
- Adding a NOT NULL column requires a DEFAULT or a two-step migration.
- Index creation on tables over ~1M rows must use CONCURRENTLY.


## Verification (required before completing)


pnpm migrate:up && pnpm migrate:down && pnpm migrate:up
pnpm test src/db


## Review checklist


- [ ] Reversible; down() tested
- [ ] No implicit type narrowing on existing columns
- [ ] Follows naming: <timestamp>_<verb>-<subject>.ts
- [ ] docs/db/CHANGELOG.md entry added

Now a request like “add a paid_at column to invoices” makes the agent load this skill first, and the migration arrives generated with the project command, reversible, and verified — without those 40 lines ever taxing unrelated tasks.

Skill or rules file?

Section titled “Skill or rules file?”
Use a rules file when… Use a skill when…
It applies to essentially every task (naming, style, “never touch X”) It applies to one kind of task (migrations, releases, i18n strings)
It’s short — rules ride on every request It’s long — procedures, checklists, command sequences
It must always be in force On-demand loading is fine (and saves tokens)

Rules are always-on and paid for on every request; skills are task-shaped and free until triggered. Most mature setups use both: a tight .nexgilerules under 500 words, plus a handful of meaty skills. See Rules Files & AGENTS.md and, for context economics, Context Management.

Section titled “Related”