Add an rsigma agent skill

CHANGELOG.md

@@ -4,6 +4,10 @@ All notable changes to RSigma are documented in this file. Each entry correspond
 
 ## [Unreleased]
 
+### Agent skill for the CLI and MCP loop (#501)
+
+`skills/rsigma/` teaches agents the current command groups (`engine`, `rule`, `backend`, `pipeline`, `mcp`, `config`) and the write-lint-evaluate-convert loop. Install with `npx skills add timescale/rsigma -g -y`. Sigma YAML authoring stays in the sigma-rules skill.
+
 ### rstix: validate-on-ingest for TAXII collections (#499)
 
 **Public API (breaking vs 0.22.0):**

README.md

@@ -256,6 +256,13 @@ rsigma mcp serve --rules-dir rules/
 
 The agent then calls structured tools (`parse_rule`, `lint_rules`, `validate_rules`, `evaluate_events`, `convert_rules`, `list_fields`, ...) and gets back JSON. Point `--daemon-url` at a running daemon to add the Operate-cycle tools. See the [MCP server guide](https://rsigma.io/guide/mcp-server/).
 
+To teach an agent the current CLI and that loop, install the skill (Sigma YAML authoring is a separate skill):
+
+```bash
+npx skills add timescale/sigma-rules -g -y
+npx skills add timescale/rsigma -g -y
+```
+
 ### Library Usage
 
 Use the crates directly from Rust:

docs/content/getting-started/installation.md

@@ -133,6 +133,17 @@ rsigma --help
 
 You should see `rsigma {{ rsigma.version }}`, the Cargo features compiled into that binary, and a list of the top-level command groups (`engine`, `rule`, `backend`, `pipeline`, `config`, and `mcp` when built with the `mcp` feature).
 
+## Agent skill
+
+Coding agents that run rsigma (eval, lint, draft, tune, convert, daemon) can load a skill that teaches the current command groups and the MCP loop. YAML authoring stays in the separate [sigma-rules](https://github.com/timescale/sigma-rules) skill.
+
+```bash
+npx skills add timescale/sigma-rules -g -y
+npx skills add timescale/rsigma -g -y
+```
+
+The rsigma skill is published from `skills/rsigma/` in this repository. It does not replace `rsigma mcp serve`. Connect the MCP server when you want typed tools instead of shelling out.
+
 ## Next steps
 
 - Run your first rule in [the quick start](quick-start.md).

skills/rsigma/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: rsigma
+description: "Use the rsigma CLI and MCP server: engine eval, engine daemon, rule lint, rule draft, rule tune, rule backtest, backend convert, mcp serve. Prefer MCP tools when rsigma mcp serve is connected. For authoring Sigma YAML (detection, correlation, filters, pipelines, modifiers), use the sigma-rules skill. Use this skill whenever the user mentions rsigma, evaluating or linting Sigma rules, converting rules to a SIEM query, running a detection daemon, drafting or tuning rules from events, or backtesting a ruleset, even if they do not name the binary."
+---
+
+# rsigma
+
+Use rsigma to run Sigma rules. Author the YAML with the [sigma-rules](https://github.com/timescale/sigma-rules) skill (`npx skills add timescale/sigma-rules -g -y`). This skill covers the toolchain: command names, when to call MCP versus the CLI, and which command fits the job.
+
+Flag tables and option lists live at [rsigma.io](https://rsigma.io/). Read them when you need a flag. Do not invent flags, and do not quote lint or auto-fix counts. The [linting guide](https://rsigma.io/guide/linting-rules/) is the catalogue.
+
+## Command names
+
+The CLI is noun-led. These old top-level forms do not exist:
+
+| Do not run | Run instead |
+|------------|-------------|
+| `rsigma eval` | `rsigma engine eval` |
+| `rsigma lint` | `rsigma rule lint` |
+| `rsigma validate` | `rsigma rule validate` |
+| `rsigma daemon` | `rsigma engine daemon` |
+
+Groups:
+
+| Group | Use it for |
+|-------|------------|
+| `engine` | Evaluate events, explain a miss, classify schemas, and run or inspect the daemon (`eval`, `explain`, `classify`, `discover-schemas`, `status`, `tap`, `tail`, `daemon`) |
+| `rule` | Lint, validate, draft, tune, test exemplars, backtest, and reverse-convert |
+| `backend` | Convert rules to a query (`convert`, `targets`, `formats`) |
+| `pipeline` | See how a pipeline rewrites a rule (`diff`) and dry-run dynamic sources (`resolve`) |
+| `mcp` | Serve the toolchain to an agent (`serve`) |
+| `config` | Scaffold and inspect `rsigma.yaml` |
+
+`engine daemon` and `pipeline resolve` need a build with the `daemon` feature. `mcp serve` needs the `mcp` feature. Release binaries and the Docker image include both. `rsigma --features` prints what this binary was built with.
+
+Full tree: [CLI reference](https://rsigma.io/cli/).
+
+## Prefer MCP when it is connected
+
+If `rsigma mcp serve` is already connected, call its tools. They return JSON (`ok`, findings, matches) and you do not scrape CLI text. If it is not connected, use the CLI commands in [workflows.md](references/workflows.md).
+
+Start a local server only when the user wants the agent wired up:
+
+```bash
+rsigma mcp serve --rules-dir rules/
+```
+
+Point `--daemon-url` at a running daemon when the task is live triage (incidents, silences, dispositions). Those tools stay off until that URL is set. Writes stay behind `--allow-operate-writes`. Details: [MCP server guide](https://rsigma.io/guide/mcp-server/).
+
+## Which command
+
+- One-shot check against a file or a few events: `engine eval`. A long-running process with reload, metrics, and sinks: `engine daemon`.
+- A rule from exemplar events (optional baseline, or `--groups` for a temporal correlation): `rule draft`. A rule the user already described in words: write the YAML with sigma-rules, then lint and evaluate it here.
+- A noisy rule with known false positives and true positives that must still fire: `rule tune`.
+- Embedded `rsigma.exemplars`: `rule test`. A separate corpus and expectations file: `rule backtest`.
+- Why a rule missed: `engine explain`. How a pipeline rewrote fields: `pipeline diff`.
+
+The write-lint-evaluate-convert loop, with the MCP tool beside each CLI command, is in [workflows.md](references/workflows.md).
+
+## Convert
+
+Native targets run inside rsigma. Anything else is delegated to an installed [sigma-cli](https://github.com/SigmaHQ/sigma-cli).
+
+```bash
+rsigma backend targets
+rsigma backend convert -t postgres rules/
+rsigma backend convert -t splunk rules/
+```
+
+Native targets are `postgres` (`postgresql`, `pg`), `lynxdb`, and `fibratus`, plus a backend-neutral `test` target that is not a deployment backend. `backend targets` is the live list. Delegated conversion needs `sigma` on `PATH` (override with `RSIGMA_SIGMA_CLI`). The Docker image has no Python, so delegation is a local-binary feature. On MCP, `convert_rules` delegates only when the server was started with `--allow-sigma-cli`. Builtin pipeline names (`ecs_windows`, `fibratus_windows`, `sysmon`) are not translated for delegated targets. Pass a sigma-cli pipeline name or a YAML path.
+
+See [backend convert](https://rsigma.io/cli/backend/convert/) and [sigma-cli delegation](https://rsigma.io/reference/backends/sigma-cli/).

skills/rsigma/references/workflows.md

@@ -0,0 +1,38 @@
+# Workflows
+
+Command names and the convert split are in [SKILL.md](../SKILL.md). This page is the loop. Flag tables are on [rsigma.io](https://rsigma.io/), not here.
+
+Author Sigma YAML with the sigma-rules skill. Use the steps below to check and run it.
+
+## Write, lint, evaluate, convert
+
+Prefer the MCP tool when `rsigma mcp serve` is connected. Otherwise use the CLI.
+
+1. **Draft.** Hand-authored YAML (sigma-rules), `rule draft` from exemplar events, or `reverse_convert` / `rule reverse` from a Lucene query. Call `parse_rule` (or `rule parse`) and stop if the structure is invalid.
+2. **Lint.** `lint_rules` or `rule lint`. Each finding has a rule id and a `fixable` flag. Apply a known-safe fix with `fix_rules` or `rule lint --fix`. Rewrite the rest by hand. Do not treat a count of checks as stable. The catalogue is the [linting guide](https://rsigma.io/guide/linting-rules/).
+3. **Evaluate.** `evaluate_events` or `engine eval` against a few positive and negative events. `match_detail` of `summary` or `full` explains why an event matched. When the events live on the rule as `rsigma.exemplars`, `test_exemplars` or `rule test` is the closed runner.
+4. **Tune.** For a noisy rule, `tune_rules` or `rule tune` with classified false positives and a true-positive set that must still fire. Review the returned filter before writing it.
+5. **Validate.** `validate_rules` or `rule validate` on the set, with pipelines when the rules depend on them.
+6. **Convert.** `convert_rules` or `backend convert` to the deployment target. Native targets run in-process. Other targets need sigma-cli, and on MCP they also need `--allow-sigma-cli`.
+
+Guide: [MCP server](https://rsigma.io/guide/mcp-server/).
+
+## Eval versus daemon
+
+`engine eval` reads a fixed input and exits. Use it to test a rule.
+
+`engine daemon` stays up, reloads rules, and exposes health and metrics. Use it when events are a stream. It needs the `daemon` feature. NATS input also needs `daemon-nats`, and OTLP logs arrive on `/v1/logs` on the API address with `daemon-otlp`, not through `--input`. Release binaries include all three; a `cargo install rsigma` build has only `daemon`.
+
+Guide: [Evaluating rules](https://rsigma.io/guide/evaluating-rules/), [Streaming detection](https://rsigma.io/guide/streaming-detection/).
+
+## Draft versus a rule you already know
+
+`rule draft` proposes a detection from exemplar events, optionally contrasted with a baseline. `rule draft --groups` proposes a temporal correlation from grouped, timed exemplars. Use draft when the user has events and wants a rule inferred from them.
+
+When the user describes the behavior in words, write the YAML with sigma-rules. Then run the loop above. Do not ask draft to invent a rule from a sentence.
+
+Guide: [Rule drafting](https://rsigma.io/guide/rule-drafting/).
+
+## Convert
+
+Native versus delegated targets are in the Convert section of [SKILL.md](../SKILL.md#convert). When delegation fails, read the error. If `sigma` could not be found or executed, install sigma-cli or set `RSIGMA_SIGMA_CLI`. If sigma-cli rejects the target, install that backend plugin (`sigma plugin install <name>`), then check `rsigma backend targets`.