# nutshell-skills

A shared knowledge repository of AI-consumable skills for TiDB Cloud operations. Skills are knowledge documents (not code libraries) consumed by [Claude Code](https://claude.ai/code), [OpenCode](https://github.com/opencode-ai/opencode), and [Codex](https://github.com/openai/codex) agents.

## Quick Start

```bash
npm install                # install deps (playwright, better-sqlite3)
./sync-skills.sh           # symlink skills to ~/.claude/skills/, ~/.config/opencode/skills/, and ~/.codex/skills/
```

## Skills

| Skill | Domain | Description |
|-------|--------|-------------|
| clinic-api | Cluster Metadata & Observability | Query PingCAP Clinic cluster information & O11Y Data(Logs,Metrics,Slow Query Published. TOPSQL, SQL Statement, System Table is on the way.) |
| devops-api | Software Delivery & Operations | Manage Ops Portal release changes and deployments, query tenants, clusters, and TiCDC metadata, handle incidents and cluster operations, and manage bastion access |
| op-clinic-grafana-access | On-Premises Clinic and Grafana Access | Access and normalize On-Premises Clinic dashboard queries, bundles, and online Grafana metrics through a reusable Chrome login session |
| oncall-toolkit | Oncall Workflow | Jira and Pingkai oncall workflow helper for report, RCA, list, close, and labor flows |
| oncall-api | Oncall Scheduling | Drive the oncall-v2 service REST API (oncall.pingcap.net) to read and manage on-call schedules, rotations, overrides, teams, and handover notifications |
| o11y-metrics-api | Observability | Prometheus-compatible metrics from TiDB Cloud O11Y platform |
| tidbcloud-serverless-pool-routing | Observability | Resolve Serverless (Starter/Essential) shared-pool names into `control_plane_info`/vendor-region routing identities for parent metrics and logs APIs |
| autoscaler-dashboard | Scaling Evaluation | HPA scaling evaluation methodology, scoring rubric, and report generation |
| manage-ticdc-changefeeds | CDC Management | Manage TiCDC changefeeds |
| ticdc-health-inspection | CDC Health | TiCDC new-architecture health inspection with architecture-aware metric rules and verdicts |
| ticdc-next-gen-deploy | CDC Deployment | Deploy or destroy TiCDC next-gen test stacks via TiUP over SSH with optional changefeed setup |
| tidbcloud-serverless-daily-inspection | Diagnosis | Pool-wide TiKV daily inspection and Feishu-ready reporting for Serverless shared pools |
| tidbcloud-api | Cluster Management | TiDB Cloud TiDBX API for Starter, Essential, and Premium tier operations |
| tidb-perf-diagnosis | Performance | TiDB Cloud performance diagnosis and troubleshooting (latency, OOM, hotspots, slow queries) |
| tikv-fast-tune | Performance | TiKV performance diagnosis using a deterministic Fast Tune decision tree |
| db9 | Database | Instant serverless Postgres databases via the db9 CLI |
| security | Security | AI agent security guardrails and system instructions |
| tidbcloud-http | Database | Query TiDB Cloud over HTTP bypass serverlss driver |
| tidbcloud-cli | TiDB Cloud Management | Manage TiDB Cloud resources via the official TiDB Cloud CLI tool |
| jira-api | AI Support / Jira | Team-shareable Jira REST API workflow for PingCAP Jira search, support-ticket to GTOC/TCOC escalation, issue linking, custom fields, and DM task creation |

## 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)
│       ├── knowledge/       # Optional lazy-loaded knowledge files
│       └── references/      # Optional reference documentation
├── diagnosis/               # Diagnosis and inspection workflows
│   └── {name}/
├── ops/                     # Operational workflows and deployment helpers
│   └── {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 symlinks for Claude, OpenCode, and Codex
```

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.

## Adding a New Skill

1. Create `skills/{name}/SKILL.md` with required frontmatter:

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

2. Add optional helpers (`.sh`, `.mjs`) and companion files as needed.
3. Run `./sync-skills.sh` to distribute.

Directory name must match the `name` field. Directories without `SKILL.md` are skipped by sync.

## License

Internal use only.