> ## Documentation Index
> Fetch the complete documentation index at: https://www.rumus.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Rules & skills

> Teach the agent your conventions once with rules; give it reusable named procedures with skills.

The fastest way to make the agent work the way *you* work is to write down what's true about your environment and how you want things done. Rumus exposes two complementary tools for that:

* **Rules** — short, **always-on** guidance the agent reads with every prompt.
* **Skills** — named, **on-demand** procedures the agent invokes when relevant.

Both are managed at **Settings → AI → Rules & Skills**.

## Rules

A rule is a short bit of plain text that the agent treats as part of its system prompt. Use rules for facts and preferences that should apply every time:

* *"Use `pnpm` not `npm` in this repo."*
* *"Never run destructive commands without confirming, even if whitelisted."*
* *"All production hosts are in `us-east`; `us-west` hosts are staging."*
* *"Default to writing tests in Vitest, not Jest."*

### Add a rule

<Steps>
  <Step title="Open the page">
    **Settings → AI → Rules & Skills → Rules** tab.
  </Step>

  <Step title="Click New rule">
    A short text editor opens. Type the rule.
  </Step>

  <Step title="Toggle enabled and save">
    Each rule has an **Enabled** toggle so you can disable a rule without deleting it. Save.
  </Step>
</Steps>

The rule applies to **every** new agent message from that point on. Existing in-flight tool calls aren't affected.

### Tips for writing good rules

* **Be specific.** "Be careful with prod" doesn't help. "Never run `rm -rf` against any host whose name contains `prod`" does.
* **Frame as facts when possible.** Rules that describe *how things are* generalize better than rules that describe *what to do*.
* **Keep them short.** Rules that bloat into paragraphs become noise; the agent ignores them. A few crisp lines beats a wall of text.
* **Audit regularly.** When a rule no longer reflects your environment, disable or delete it.

## Skills

A skill is a named, self-contained procedure. Each skill has:

* A **name** (e.g. `deploy-staging`).
* A **description** of when to use it.
* An **instruction** body — the actual step-by-step procedure, in your words.

Unlike rules, skills aren't always-on. The agent reads the list of available skills with each prompt, but only invokes a skill when its description matches what you've asked for. That keeps the per-message context lean even with dozens of skills.

### When to write a skill

If you're repeatedly explaining the same multi-step procedure to the agent — turn it into a skill. Common candidates:

* **Deployments** — "deploy the staging environment", "promote staging to production".
* **Health checks** — "check whether the queue worker is healthy on `prod-worker-*`".
* **Diagnostic flows** — "investigate a 502 on the API: check logs, then upstream, then load balancer".
* **Code conventions** — "set up a new feature module: scaffold, register in router, add tests".

### Add a skill

<Steps>
  <Step title="Open the page">
    **Settings → AI → Rules & Skills → Skills** tab.
  </Step>

  <Step title="Click New skill">
    Fill in:

    * **Name** — short, identifier-like (`deploy-staging`).
    * **Description** — one sentence describing when the agent should use it.
    * **Instruction** — the actual procedure, written as steps.
  </Step>

  <Step title="Toggle enabled and save">
    Toggleable just like rules. Save.
  </Step>
</Steps>

### Writing the instruction body

Pretend you're writing a runbook for a colleague:

```
1. SSH into the bastion.
2. Run `kubectl --context=staging apply -f manifests/`.
3. Verify pod rollout with `kubectl --context=staging rollout status deploy/api`.
4. Hit the staging health endpoint and confirm 200.
5. Post in #staging-deploys with the result.
```

The agent treats this as the source of truth for that procedure. When a prompt would invoke this skill, the agent walks the steps, using its tools to actually do them.

## How rules and skills sync

Both rules and skills are part of your **AI settings**, which sync to the cloud as part of [config sync](/docs/account/sync). Edit a skill on your laptop and it shows up on your desktop after the next sync.

They're **not** part of the [vault](/docs/account/vault) — they're treated as configuration, not credentials, since they're guidance text rather than secrets. Don't put credentials in a rule or skill; reference saved keychains and accounts instead.

## Soft delete

Deleting a rule or skill is a tombstone — it's marked deleted and synced as such, so deletion propagates across your devices. If you accidentally delete one, restore it from local sync state before the next push.

## Tips

* **One responsibility per skill.** Resist the temptation to write `do-everything-deploy` skills; small composable skills are easier for the agent to chain.
* **Name skills to read like verbs.** `deploy-staging` reads naturally in a prompt; `staging-deployment-procedure` doesn't.
* **Use rules for facts, skills for procedures.** *"`prod-*` hosts run Ubuntu 22.04"* is a rule. *"How to roll a kernel upgrade on `prod-*`"* is a skill.
* **Audit your skills when you change tools.** A skill that references the old build system is technical debt the agent will faithfully use.

## Next steps

<CardGroup cols={2}>
  <Card title="Plan mode" icon="list-check" href="/docs/ai/plan-mode">
    Plans frequently invoke skills as individual steps.
  </Card>

  <Card title="Conversation management" icon="comments" href="/docs/ai/conversations">
    Auto-naming, summarization, and task lists.
  </Card>
</CardGroup>