---
title: AGENTS.md
---

# nutshell-skills

Shared AI agent skills and commands for TiDB Cloud operations.
Skills are knowledge documents (not code libraries) consumed by Claude Code, OpenCode, and Codex.

## Repository Structure

```
nutshell-skills/
  skills/                   # AI skill definitions (SKILL.md + companion files)
    {skill-name}/
      SKILL.md              # Skill entry point (YAML frontmatter + markdown)
      *.md                  # Optional companion markdown files (lazy-loaded)
      *.sh                  # Optional bash helper scripts
      *.mjs                 # Optional Node.js scripts
      components/           # Optional per-component sub-files
  commands/                 # OpenCode command definitions (*.md)
  sync-skills.sh            # Symlinks skills/ to agent home directories
  package.json              # Minimal deps (playwright, better-sqlite3)
```

## Build / Test / Lint

There is no build system, test suite, or linter. This is a knowledge repository.

```bash
# Install dependencies (needed for clinic-login.mjs Playwright flow)
npm install

# Distribute skills to agent directories (all agents, global)
./sync-skills.sh
# Creates symlinks in ~/.claude/skills/, ~/.config/opencode/skills/,
# ~/.codex/skills/, ~/.pi/skills/

# Sync specific agents only
./sync-skills.sh --agent claude,pi

# Filter skills by category or category.prefix
./sync-skills.sh --skill platform,diagnosis.tikv

# Project-level install (symlinks into <project>/.claude/skills/ etc.)
./sync-skills.sh --agent claude --skill platform --project ~/lc/tidb

# List available skills
./sync-skills.sh --list
```

No TypeScript compilation, no test runner, no CI pipeline.

## File Formats

### Skill Definition (skills/{name}/SKILL.md)

Every skill directory MUST contain a `SKILL.md`. Directories without it are skipped by sync.

```yaml
---
name: kebab-case-name
description: |
  Multi-line description using pipe character.
  Explains when to use this skill.
---
```

- `name`: Required. Kebab-case, matches directory name.
- `description`: Required. Pipe (`|`) multi-line. Describes the skill's domain.
- No `model:` or `tools:` keys -- skills are pure knowledge.

Body is markdown containing: domain knowledge, API references, PromQL queries,
bash/TypeScript code examples, data schemas, and methodology documentation.

### Command Definition (commands/*.md)

```yaml
---
description: Short description of what the command does
agent: agent-name
---
```

- References skills via `@.opencode/skills/{name}/SKILL.md` (OpenCode include syntax).
- Can also reference companion files: `@.opencode/skills/{name}/components/foo.md`.
- Accepts positional args as `$1`, `$2`, `$3`.

### Helper Scripts (skills/{name}/*.sh)

Bash scripts providing reusable functions for auth, API calls, and data processing.

Conventions:
- Use `#!/bin/bash` shebang.
- `set -e` for top-level scripts, omit for sourced libraries.
- `export -f function_name` for all public functions (enables subshell use).
- Token/session caching via `.env` file (`ENV_FILE="${ENV_FILE:-.env}"`).
- Auth pattern: check cached token -> extract from browser/cookies -> fetch new -> save.
- Status/error messages go to stderr (`>&2`), data output goes to stdout.
- Use `local` for all function-scoped variables.
- Use `jq` for JSON parsing, `curl -s` for HTTP requests.
- Use `--data-urlencode` for query parameters with special characters.

### Node.js Scripts (skills/{name}/*.mjs)

ES module scripts (`.mjs`) for tasks requiring browser automation.

Conventions:
- Use `#!/usr/bin/env node` shebang.
- ES module imports (`import { ... } from "..."`).
- Playwright for browser automation (headless: false for SSO flows).
- `process.exit(1)` on fatal errors with descriptive stderr messages.

## Code Style

### Markdown (SKILL.md, commands/*.md)

- YAML frontmatter: 2-space indent, no duplicate keys, `|` for multi-line values.
- No trailing whitespace.
- No emoji in documentation.
- Use `|` tables for structured data (columns, parameters, metrics).
- Code blocks with language tags: `bash`, `promql`, `typescript`, `tsx`, `json`, `yaml`.
- Use `**bold**` for critical warnings and key terms.
- Section headers use `##` (H2) for top-level sections within a skill.

### Bash Style

- `snake_case` for function names and local variables.
- `UPPER_CASE` for environment variables and constants.
- Quote all variable expansions: `"${VAR}"`, not `$VAR`.
- Use `$()` for command substitution, not backticks.
- Guard against empty values before using them.
- Pattern: `local var=$(command)` then check `[ -z "$var" ]`.

### TypeScript (in markdown code blocks only)

TypeScript appears only inside SKILL.md code blocks as reference schemas and examples.
- Interfaces use PascalCase (`V2ScalingEvent`, `WorkloadTimelineEntry`).
- Export `const` for data objects, `interface` for types.
- Use `"UP" | "DOWN"` union types for enumerations.

## Git Conventions

- Branch naming: `{user}/{description}` (e.g., `shenjun/add-autoscaler-dashboard-skill`).
- Commit messages: imperative, lowercase start (e.g., `add clinic-api and o11y-metrics-api skills`).
- No CI checks -- manual review via PR.

## Adding a New Skill

1. Create `skills/{skill-name}/SKILL.md` with required YAML frontmatter.
2. Add helper scripts (`.sh`, `.mjs`) if the skill needs auth or automation.
3. Run `./sync-skills.sh` to create symlinks.
4. Verify the skill appears in `~/.claude/skills/`, `~/.config/opencode/skills/`, and `~/.codex/skills/`.

## Adding a New Command

1. Create `commands/{command-name}.md` with YAML frontmatter (`description`, `agent`).
2. Reference skills via `@.opencode/skills/{name}/SKILL.md`.
3. Use `$1`, `$2`, `$3` for positional arguments.

## Security

- Never commit `.env` files, secrets, or credentials.
- Auth tokens are cached in `.env` (gitignored) with expiration timestamps.
- Helper scripts auto-refresh expired tokens without user interaction.
- Clinic shell helpers: `clinic-api/scripts/clinic-shell.sh` sources `clinic-auth.sh`; use internal `CLINIC_API_KEY` from `.env` (see clinic-api skill).
- `o11y-token.sh` uses Auth0 client_credentials flow with `O11Y_CLIENT_ID`/`O11Y_CLIENT_SECRET`.

## Domain Context

Skills serve TiDB Cloud infrastructure operations:

| Skill | Domain |
|-------|--------|
| clinic-api | Cluster metadata lookup (tenant, cluster, topology) via Clinic REST API |
| o11y-metrics-api | Prometheus-compatible metrics from TiDB Cloud O11Y platform |
| autoscaler-dashboard | HPA scaling evaluation methodology, scoring rubric, and report page generation |

Skills are designed to be injected into AI agent context windows.
They should be self-contained, retrieval-first (prefer documented knowledge over model pre-training),
and include concrete code examples agents can execute directly.