# Skills and rules

Rules are standing guidance Insula injects into the agent automatically. Skills are named procedural guides loaded on demand, either by typing `/skill_name` in chat or when the agent selects a matching skill for the task.

Global versus project layout for `.insula` is covered in [Settings spaces](/wiki/02-settings-spaces).

## Where they live

| Kind | Global | Project |
|------|--------|---------|
| Rules | `~/.insula/rules/` | `<project>/.insula/rules/` |
| Skills | `~/.insula/skills/<dir>/SKILL.md` | `<project>/.insula/skills/<dir>/SKILL.md` |

Rules are markdown files under `rules/`, searched recursively. Insula accepts `.md` and `.mdc` extensions.

If the project has no `rules/` directory, global rules are used. If `<project>/.insula/rules/` exists, it fully replaces `~/.insula/rules/` for that project. An empty project `rules/` directory means no rules. Skills from both locations are merged; when names collide, the project skill wins.

With no project open (home), global skills remain available. Rules are not applied.

Insula seeds managed defaults into the global folders on launch when those files are missing or differ from the shipped copies. Extra files you add are left alone.

## Rules

A rule file is markdown. Optional YAML frontmatter sits between a leading pair of `---` lines; the body after the closing `---` is the guidance the agent receives.

### Frontmatter fields

These fields are honored:

| Field | Form | Effect |
|-------|------|--------|
| `description` | string | Label used when the rule is delivered. If frontmatter is present and `description` is empty, the filename is used. |
| `globs` | string, comma-separated string, or YAML array of strings | Project-relative path patterns. Supports doublestar forms such as `**`, `*`, `{}`, and `[]`. |
| `alwaysApply` | boolean | When `true`, the rule is included from the start of each agent turn while a project is open. |

Any other frontmatter keys are ignored. Do not set a non-empty `kind` field; that causes the file to be skipped entirely.

Without frontmatter, the whole file is treated as body. In that case there is no filename fallback for `description`, and the rule only participates if you later add `alwaysApply` or matching `globs`.

### When rules enter context

**Always-apply** (`alwaysApply: true`): appended at the start of Agent, Discuss, Plan, and related project turns. Keep these short: project identity, layout, and pointers.

**Path-triggered** (globs, `alwaysApply` false or omitted): when the agent first reads or writes a project-relative path that matches a glob, matching rules that have not yet been delivered in that conversation are appended once. After delivery, that rule path is not re-sent for the rest of the session.

A rule with neither `alwaysApply: true` nor a matching glob never enters context.

### Examples

Always-apply:

```markdown
---
description: "Project identity and layout"
alwaysApply: true
---

- Shared agent config lives under `.insula/`.
- Prefer existing packages over new shims.
```

Path-triggered (string or array globs):

```markdown
---
description: "Go conventions"
globs: "**/*.go"
alwaysApply: false
---

- Match surrounding package style.
- Do not edit go.mod by hand.
```

```markdown
---
description: "Docs and wiki"
globs:
  - "docs/**"
  - "**/*.md"
alwaysApply: false
---

- Keep user-facing docs free of implementation detail.
```

Comma-separated globs in one string also work: `globs: "*.go,*.md"`.

### Authoring guidance

1. Creating `<project>/.insula/rules/` replaces global rules for that project. Plan the full set you need before adding the directory.
2. Prefer small always-apply files. Put area-specific conventions behind globs so they appear when those files are touched.
3. Write short, concrete bodies that name real paths in the project.

## Skills

Each skill is a directory containing `SKILL.md`. Optional sibling folders:

- `references/`: supporting files the agent can read relative to the skill directory
- `scripts/`: non-hidden files listed for the agent to prefer via the terminal when present

Only immediate child directories of `skills/` are scanned. Nested skill trees are not discovered.

### Frontmatter

| Field | Effect |
|-------|--------|
| `name` | Slash-command and selection name. If omitted, the folder name is used. |
| `description` | Drives agent selection. If omitted, defaults to a generic placeholder. Write a specific description. |

By convention, names start with `skill_`. Other names load if present.

Example:

```markdown
---
name: skill_bootstrap-insula
description: Bootstrap a .insula directory in the open project
---

Procedural steps for the agent.
```

### Loading a skill

1. **Slash command:** type `/` in the chat composer. Autocomplete lists available skills by name and description. Including `/exact_name` in your message force-loads that skill for the turn.
2. **Agent selection:** the agent can load a skill whose description matches the task.

Skills are available in Agent (including home, with global skills only), Discuss, Plan, and related modes.

## Setup

To create or extend project `.insula` content, load the shipped skill `/skill_bootstrap-insula` and follow it. Confirm before anything is created under `.insula/`. That skill also covers languages and macros; this page covers rules and skills only.

There is no Settings panel for authoring rules or skills. Edit the files on disk.

## Practical limits

- Edits to rule files may not apply until you start a new conversation or switch projects.
- Skills are rescanned each turn. New or renamed skills appear in slash autocomplete after the skill list refreshes.
- Path-triggered rules deliver once per rule file path per conversation session.
- Rules apply only while a project is open.