Skills · v2.2.0

Teach GIDE how your
project actually works.

A skill is a short Markdown file you write under .gide/skills/<name>.md (project-local), or ~/.gide/skills/ for every project. It captures a convention or procedure, the "how we do X here", so you don't re-explain it every prompt.

Selection is deterministic, never fuzzy

GIDE loads a skill only when it's certain it applies

This is the core design decision. There are exactly two ways a skill turns on, and both are things you can point at:

You @mention it

Type @api-error-handling in chat and that skill is injected for that turn. You picked it.

A glob matches a file in play

If a skill's appliesTo globs match the file you're editing or one you referenced, it auto-triggers.

Why there's no keyword matching

A wrong fuzzy match would inject authoritative-sounding but irrelevant guidance, and a small local model tends to trust it as fact. That's how you get hallucination. So similarity can only ever suggest a skill in the menu. It never silently injects one.

What keeps them safe and useful

Frontmatter fields
name (what you @mention), description (one line, written in the words you'd type, shown in the @ menu), appliesTo (globs for auto-trigger), and an optional symbols.
Drift protection
List symbols a skill depends on, and if one gets renamed or deleted, GIDE suppresses that skill automatically rather than give stale advice. A skill that only describes patterns never goes out of date, which is the recommended style.
Subordinate to ground truth
Skills are a budgeted context layer. A skill can never crowd out the actual file you're editing, and @mention outranks a glob-trigger, which outranks auto-learned lessons. They add guidance without overriding reality.
Kept short
A skill shares the model's context window with your real code. A bloated skill competes with the thing you actually want it to reason about.

Four skills, start to finish

The first three carry appliesTo globs, so they turn on by themselves the moment you touch a matching file. The last has an empty appliesTo, so it only activates when you @commit-messages it. There's no "commit file" for it to match.

.gide/skills/api-error-handling.md
---
name: api-error-handling
description: how errors are returned from API routes / handlers
appliesTo: ["server/**/*.js", "**/routes/**", "**/api/**"]
symbols: []
---

# API error handling

Every route returns errors in one shape, never a raw throw to the client.

- Wrap handler bodies so nothing leaks a stack trace to the response.
- Error responses are { error: <machine-code>, detail: <human message> }
  with the right HTTP status (400 bad input, 401 unauthenticated,
  403 not entitled, 404 missing, 500 unexpected).
- Log the real error server-side; send the user a safe message.

## Checklist
- [ ] No throw reaches the client, every path returns the {error, detail} shape
- [ ] Status code matches the failure kind
- [ ] Server logs the real cause; response hides internals

Using them

Create one

Three ways scaffold the file from a teaching template and open it:

  • ›The + (Add Context) menu in the chat input, then "Create new skill…"
  • ›The @ menu while typing, then "✚ Create new skill…"
  • ›Command palette, then "GIDE: Create Skill"

Or just make the file yourself at .gide/skills/<name>.md.

Invoke one

  • Explicit. Type @ in chat, pick the skill, then your request. Best when you want it regardless of the file you're on, like @commit-messages write the message for these changes.
  • Automatic. Just work on a matching file. Open src/components/Card.tsx and ask for a change; react-components loads on its own because the glob matches. You don't have to remember to mention it.

Before you write your first one

Write patterns, not line numbers or one-off names. Pattern skills never go stale and they carry across the whole codebase. Keep each one short, since a skill shares the model's context with the code you actually want it reasoning about. And leave symbols empty unless a skill genuinely hinges on a specific function or class you want drift-protection for. That's really all there is to it.