# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## What This Is

A shared knowledge repository of AI-consumable skills and commands for TiDB Cloud operations. Skills are knowledge documents (not code libraries) consumed by Claude Code, OpenCode, Codex, and Pi agents. There is no build system, test suite, or linter.

## Commands

```bash
npm install                                                   # Install deps (playwright, better-sqlite3)
./sync-skills.sh                                              # Symlink all skills to all agents (global)
./sync-skills.sh --agent claude,pi                            # Specific agents only
./sync-skills.sh --skill platform,diagnosis.tikv              # Filter by category or category.prefix
./sync-skills.sh --agent claude --skill platform --project ~/lc/tidb  # Combined
./sync-skills.sh --list                                       # Show available skills
```

## Architecture

```
skills/
├── platform/                # Platform tools and APIs
│   └── {name}/
│       ├── SKILL.md         # Skill entry point (YAML frontmatter + markdown body)
│       ├── *.sh             # Optional bash helpers (auth, API calls)
│       ├── *.mjs            # Optional Node.js scripts (browser automation)
│       └── components/      # Optional per-component sub-files
├── diagnosis/               # Diagnosis and inspection workflows
│   └── {name}/
└── utilities/               # General-purpose utilities
    └── {name}/
commands/*.md                # OpenCode command definitions (reference skills via @include)
agents/*.md                  # AI agent definitions with tool permissions
sync-skills.sh               # Creates directory symlinks to agent home dirs
```

Skills are injected into AI agent context windows. They must be self-contained, retrieval-first (documented knowledge over model pre-training), and include executable code examples.

### Skill Categories

**platform/** (9 skills) - TiDB Cloud platform APIs and data access
- `clinic-api`, `tidbcloud-api`, `tidbcloud-cli`, `tidbcloud-http`, `devops-api`
- `o11y-auth`, `o11y-metrics-api`, `o11y-data`, `o11y-data-export`

**diagnosis/** (4 skills) - Performance diagnosis and health inspection
- `tidb-perf-diagnosis`, `tikv-fast-tune`, `ticdc-health-inspection`, `autoscaler-dashboard`

**utilities/** (1 skill) - General-purpose tools
- `db9`

## File Formats

### SKILL.md Frontmatter

```yaml
---
name: kebab-case-name
description: |
  Multi-line description.
---
```

- `name` and `description` are required. No `model:` or `tools:` keys (skills are pure knowledge).
- Directory name must match `name` field.
- Directories without SKILL.md are skipped by sync.

### Command Frontmatter

```yaml
---
description: What the command does
agent: agent-name
---
```

References skills via `@.opencode/skills/{name}/SKILL.md`. Positional args: `$1`, `$2`, `$3`.

### Agent Frontmatter

```yaml
---
name: kebab-case
description: |
  What the agent does.
tools: Tool1, Tool2, Tool3
---
```

## Style

- YAML: 2-space indent, no duplicate keys, `|` for multi-line values
- Markdown: no trailing whitespace, no emoji, `|` tables for structured data, code blocks with language tags
- Bash: `snake_case` functions/locals, `UPPER_CASE` constants, quote all variables (`"${VAR}"`), `$()` not backticks, `set -e` for top-level scripts, `export -f` for public functions, stderr for status, stdout for data
- Git: branch `{user}/{description}`, imperative lowercase commit messages

## Adding Content

**New skill:** Create `skills/{category}/{name}/SKILL.md` with frontmatter, add helpers if needed, run `./sync-skills.sh`.

**New command:** Create `commands/{name}.md` with frontmatter, reference skills via `@.opencode/skills/{name}/SKILL.md`.

## Key Reference

`AGENTS.md` is the authoritative source for all conventions, file formats, and domain context.