# Agent skill

> A SKILL.md that teaches Claude Code, Codex and claude.ai how to model data in SkimmerDB and use it well.

MCP tools tell an agent *what* it can call. The SkimmerDB skill tells it *how to use them
well*: which namespaces and ids to choose, what goes in `text` and what in `meta`, which calls
to make, what SQL supports, and what to do with each error. It's one `SKILL.md` file in the
format Claude Code, Codex and claude.ai all read.

- [Download SKILL.md](https://skimmerdb.com/skills/skimmerdb/SKILL.md)
- [Download skimmerdb.zip](https://skimmerdb.com/skills/skimmerdb.zip) (the same file, zipped, for claude.ai)

## Install

### Claude Code

For every project, put it in your home folder; for one repository, in its `.claude/skills/`.

```sh title="shell"
mkdir -p ~/.claude/skills/skimmerdb
curl -so ~/.claude/skills/skimmerdb/SKILL.md https://skimmerdb.com/skills/skimmerdb/SKILL.md
```

### Codex

For every project, `~/.agents/skills/`; for one repository, its `.agents/skills/`.

```sh title="shell"
mkdir -p ~/.agents/skills/skimmerdb
curl -so ~/.agents/skills/skimmerdb/SKILL.md https://skimmerdb.com/skills/skimmerdb/SKILL.md
```

### claude.ai and Claude Desktop

Customize > Skills > **+** > Upload a skill, and pick `skimmerdb.zip`. Skills need a paid plan
with code execution turned on.

## What's in it

- **When to use it**: storing, searching or analyzing data in SkimmerDB, or code that calls
  its API, its clients or its MCP server.
- **Connecting**: the MCP tools when they're connected, else the REST API with a key in
  `SKIMMERDB_KEY`, else the Python and TypeScript clients in your code. Keys are never printed,
  committed or put in URLs, and apps get narrow keys.
- **Modeling**: one query reads one namespace; stable natural ids; `text` for what's searched
  and `meta` for what's filtered; flat metadata, one type per key, times as integer seconds,
  tags as booleans. The [Data model](/guides/data-model) guide in brief.
- **Writing and reading**: batching, `PATCH`, deletes, imports, `wait`, filters, regex,
  cursors, vectors, hybrid search, counts and warm-up.
- **SQL**: what's supported, what isn't yet, and three example queries.
- **Recipes**: agent memory, agent analytics and logs, and a knowledge base for RAG.
- **Errors**: what each status means and what to do about it.

The skill works alongside the [MCP server](/mcp): connect both and the agent has the tools and
the judgment to use them.