# Agent skills

> Bundled skills/tigerfs pack, install-time staging to agent config dirs, SKILL.md navigation (files, data, ops, recipes), and mount-time copy behavior.

- Repository: timescale/tigerfs
- GitHub: https://github.com/timescale/tigerfs
- Human docs: https://grok-wiki.com/public/docs/timescale-tigerfs-60719456a5c3
- Complete Markdown: https://grok-wiki.com/public/docs/timescale-tigerfs-60719456a5c3/llms-full.txt

## Source Files

- `skills/tigerfs/SKILL.md`
- `skills/tigerfs/files.md`
- `skills/tigerfs/data.md`
- `skills/tigerfs/ops.md`
- `scripts/install.sh`
- `scripts/test-install.sh`

---

---
title: "Agent skills"
description: "Bundled skills/tigerfs pack, install-time staging to agent config dirs, SKILL.md navigation (files, data, ops, recipes), and mount-time copy behavior."
---

TigerFS ships a portable `skills/tigerfs/` instruction pack (open `SKILL.md` format) that teaches coding agents how to use mounted PostgreSQL as files. Release archives bundle the pack via Goreleaser; `scripts/install.sh` copies it into detected agent config directories or stages it under `~/.config/tigerfs/skills/tigerfs/`. The `tigerfs mount` command does not install skills—installation runs at binary install time (or via manual copy from a clone).

## Bundled pack layout

The repository maintains five markdown files under `skills/tigerfs/`:

| File | Role |
|------|------|
| `SKILL.md` | Entry skill: mode detection, mount layout, safe editing, quick reference, anti-patterns, links to detail files |
| `files.md` | File-first: `.build/`, frontmatter, `.tables/`, history, log, savepoints, undo |
| `data.md` | Data-first: `.info/`, pipeline paths, PATCH writes, import/export, DDL staging |
| `ops.md` | CLI: `mount`, `create`, `fork`, `status`, `unmount`, config |
| `recipes.md` | Workflow and application patterns (kanban, knowledge base, session context, multi-agent undo) |

`SKILL.md` frontmatter registers the skill for agent loaders:

```yaml
name: tigerfs
description: How to discover, read, write, and search data in a TigerFS-mounted PostgreSQL database using file tools.
```

<Note>
Skill packs are plain files—no model provider or hosted service is required. Any agent that loads `SKILL.md` from a filesystem or catalog path can use the same pack.
</Note>

## Release bundling

Goreleaser includes the pack in every release archive:

```yaml
files:
  - skills/tigerfs/*
```

After `curl -fsSL https://install.tigerfs.io | sh`, the extracted tarball contains `skills/tigerfs/` beside the `tigerfs` binary. `install.sh` runs skill installation immediately after copying the binary.

## Install-time copy and staging

`scripts/install.sh` implements all automated skill placement. Flow:

```mermaid
sequenceDiagram
  participant User
  participant install_sh as install.sh
  participant Archive as release tar.gz
  participant Stage as ~/.config/tigerfs/skills
  participant Agent as agent skills dir

  User->>install_sh: curl | sh
  install_sh->>Archive: extract tigerfs + skills/tigerfs
  install_sh->>install_sh: install_skills(skills_src)
  alt stdout is TTY or TIGERFS_INTERACTIVE=1
    install_sh->>User: agent menu (read /dev/tty)
    User->>install_sh: 1..N, a, or s
    opt choice a or N
      install_sh->>Agent: copy_skills_to_agent (rm -rf tigerfs, cp -r)
    opt choice s or no agents
      install_sh->>Stage: stage_skills
    end
  else piped / non-interactive
    install_sh->>Stage: stage_skills
    install_sh->>User: print cp -r hints for detected agents
  end
```

### Interactive vs non-interactive

<ParamField body="trigger" type="condition">
Runs `interactive_install_skills` when stdout is a terminal (`-t 1`) **or** `TIGERFS_INTERACTIVE=1`. Otherwise calls `stage_skills` only.
</ParamField>

| Mode | Trigger | Result |
|------|---------|--------|
| Interactive | TTY or `TIGERFS_INTERACTIVE=1` | Menu: install to one/all detected agents, skip (stage only), or stage when none detected |
| Non-interactive | `curl … \| sh` with piped stdin | Skills copied to `~/.config/tigerfs/skills/tigerfs/`; script prints `cp -r` commands per detected agent |

Interactive prompts read from `/dev/tty` so `curl | sh` can still ask questions without consuming the install pipe. Tests force interactivity with `TIGERFS_INTERACTIVE=1` and a fake stdin file (`scripts/test-install.sh`).

### `copy_skills_to_agent` behavior

For each selected agent:

1. `rm -rf "$agent_skills_dir/tigerfs"` — full replace on upgrade (removes stale files such as retired skill filenames).
2. `mkdir -p "$agent_skills_dir"`
3. `cp -r "$src" "$agent_skills_dir/tigerfs"`

Expected files after install (asserted in `scripts/test-install.sh`): `SKILL.md`, `files.md`, `data.md`, `recipes.md`, `ops.md`.

### Staging directory

`stage_skills` writes the same tree to:

```
~/.config/tigerfs/skills/tigerfs/
```

If agent directories exist under `$HOME`, the script prints per-agent copy lines, for example:

```bash
cp -r ~/.config/tigerfs/skills/tigerfs ~/.claude/skills/tigerfs
```

If no agents are detected, it prints a generic example (`~/.claude/skills/`).

<Warning>
README and CHANGELOG mention skills “automatically installed at mount time.” The `tigerfs mount` implementation (`internal/tigerfs/cmd/mount.go`) has no skill-copy hook—only `scripts/install.sh` performs automated installation today.
</Warning>

## Supported coding agents

Detection checks for a marker directory under `$HOME`. Installation targets the agent-specific skills path:

| Agent | Detection dir | Install path (under `$HOME`) |
|-------|---------------|------------------------------|
| Claude Code | `.claude` | `.claude/skills/tigerfs/` |
| Cursor | `.cursor` | `.cursor/skills/tigerfs/` |
| Codex CLI | `.codex` | `.agents/skills/tigerfs/` |
| Gemini CLI | `.gemini` | `.gemini/skills/tigerfs/` |
| Windsurf | `.codeium/windsurf` | `.codeium/windsurf/skills/tigerfs/` |
| Antigravity | `.gemini/antigravity` | `.gemini/antigravity/skills/tigerfs/` |
| Kiro | `.kiro` | `.kiro/steering/tigerfs/` |

Menu choices: `a` = all detected, `s` = skip (stage only), `1`…`N` = one detected agent (display order, not fixed agent index).

## SKILL.md navigation model

`SKILL.md` is the hub agents load first. It branches on **mode** and **task**, then defers to sibling files.

### Mode routing

| Signal on path | Mode | Detail file |
|----------------|------|-------------|
| `.md` / `.txt` files, workspace layout | File-first | [files.md](files.md) |
| `.info/` at table root | Data-first | [data.md](data.md) |

### Task routing from SKILL.md

| User intent | Routed to |
|-------------|-----------|
| Workspaces, frontmatter, history, undo paths | `files.md` |
| Row/column access, pipelines, bulk export, DDL | `data.md` |
| Kanban, knowledge base, session context, safe exploration | `recipes.md` (Recipes 1–7; SKILL.md maps intents to recipe numbers) |
| Mount, create, fork, cloud backends | `ops.md` |

### Cross-cutting sections in SKILL.md

- **Directory structure** — file-first tree (`.history`, `.log`, `.savepoint`, `.undo`, `.tables/`, `.build/`).
- **Safe editing** — savepoint JSON, preview via `.undo/…/.info/summary`, apply via `touch …/.apply`, multi-entry atomic-rename log groups.
- **Quick reference** — tool-oriented table (`Read`, `Write`, `Glob`, `Grep`, `Bash`).
- **Directory scanning safety** — never recurse `.log/`, `.by/`, `.export/`, etc.; use targeted paths.
- **Anti-patterns** — e.g. do not use `Write`/`Edit` to revert content; use `.undo/`; kanban uses directories + `mv`, not `status` frontmatter.

Detail files link back to SKILL.md for shared workflows (e.g. `files.md` → “Common Workflows” for undo steps).

## Install paths compared

<Tabs>
  <Tab title="curl | sh">
    Binary + `skills/tigerfs/` from archive; `install.sh` stages or copies to agent dirs.
  </Tab>
  <Tab title="git clone / go install">
    Pack lives at `skills/tigerfs/` in the repo. No automatic copy to `~/.claude/skills`—point the agent at the repo path or run `cp -r skills/tigerfs ~/.claude/skills/tigerfs` (or equivalent).
  </Tab>
  <Tab title="tigerfs mount">
    Mounts PostgreSQL only; does not update agent skill directories.
  </Tab>
</Tabs>

<Steps>
  <Step title="Install or stage skills">
    Run `curl -fsSL https://install.tigerfs.io | sh` (interactive TTY shows the agent menu), or copy from `~/.config/tigerfs/skills/tigerfs/` after a non-interactive install.
  </Step>
  <Step title="Verify files">
    Confirm `SKILL.md`, `files.md`, `data.md`, `recipes.md`, and `ops.md` exist under your agent’s `tigerfs/` skill directory.
  </Step>
  <Step title="Mount and use">
    `tigerfs mount CONNECTION MOUNTPOINT` — agents apply loaded skills when operating on the mount path.
  </Step>
</Steps>

Optional verification for the install script itself:

```bash
./scripts/test-install.sh
```

## Portable integration (BYOC/BYOK)

- **Source of truth**: markdown in `skills/tigerfs/`, not embedded in the `tigerfs` binary.
- **Distribution**: release tarball, git tree, or staged `~/.config/tigerfs/skills/tigerfs/`.
- **Agent binding**: filesystem copy into each product’s skills folder (or symlink). Grok-Wiki and other doc generators can treat the pack as a repository-local catalog entry without tying to one LLM vendor.

Reload or restart the agent session after upgrading skill files so new instructions (e.g. undo log grouping) take effect.

## Related pages

<CardGroup>
  <Card title="Installation" href="/installation">
    curl installer, platform prerequisites, and first binary install.
  </Card>
  <Card title="Quickstart" href="/quickstart">
    First mount and exploration after skills are in place.
  </Card>
  <Card title="Workflow recipes" href="/workflow-recipes">
    Kanban, knowledge base, and session patterns from recipes.md.
  </Card>
  <Card title="File-first workspaces" href="/file-first-workspaces">
    Workspaces, frontmatter, and .tables/ backing access.
  </Card>
  <Card title="History, savepoints, and undo" href="/history-savepoints-undo">
    .history, .log, .savepoint, and .undo behavior the skills teach.
  </Card>
  <Card title="CLI reference" href="/cli-reference">
    mount, create, fork, and other commands documented in ops.md.
  </Card>
</CardGroup>