Skip to content

AGENTS.md

Latest commit

 

History

History
41 lines (28 loc) · 2.8 KB

AGENTS.md

File metadata and controls

41 lines (28 loc) · 2.8 KB
Raw

AGENTS.md

This file provides guidance to OpenAI Codex when working with this repository.

Project Overview

Zeabur Toolkit Skills — a plugin providing skills that drive the Zeabur GraphQL API (https://api.zeabur.com/graphql) with plain curl. Compatible with both Claude Code and OpenAI Codex. No build system, no compiled code, no dependencies — the entire plugin is declarative markdown skill files.

No CLI: skills must never reference npx zeabur or any Zeabur CLI. Everything goes through curl + GraphQL.

Architecture

  • plugins/toolkit/.codex-plugin/plugin.json — Codex plugin manifest
  • plugins/toolkit/.claude-plugin/plugin.json — Claude Code plugin manifest
  • plugins/toolkit/skills/<name>/SKILL.md — one skill per kebab-case directory: YAML frontmatter (name, description) followed by structured documentation

Skills

Skill Purpose
auth Access Token setup, the shared zapi curl pattern, verification
server-catalog Browse providers / regions / plans, cheapest-machine sweep
server-rent Rent a clean Ubuntu VPS (price confirmation required)
server-manage Status / power / reboot / reinstall
deploy Path router — asks with ZeaburOS (k3s) recommended, vanilla k3s and self-managed as peers
subdomain zeabur.app binding + HTTPS wiring
kubernetes-* kubectl-only cluster operations (workloads / network / storage / observability), shared contract in plugins/toolkit/references/kubernetes.md

The toolkit principle: recommend, never railroad

Each platform step is unbundled and independently usable — server, runtime, domain, TLS compose freely. At any fork the user hasn't decided, present common options with Zeabur's recommendation first (see the deploy skill's question), then honor the pick; a user-named choice is always honored without debate. Never require a piece the operation doesn't need — subdomain binds to any public IP, kubernetes-* operates any reachable k3s, and nothing creates a Zeabur project.

Recommended composition: rent → ZeaburOS (installK3s) or vanilla k3s → kubectl → subdomain + HTTPS (auto-issued by the ZeaburOS ingress-controller; cert-manager only on vanilla k3s).

Conventions

  • API calls: use the zapi helper pattern from the auth skill; check .errors before reading data.
  • Money and destruction need explicit consent: renting charges immediately; reinstalling wipes the disk. Present the concrete consequence and get an explicit yes. Pass an operationID (uuidgen) on charging mutations so retries cannot double-charge.
  • Secrets stay put: the API token never leaves the local machine; TLS private keys never leave the user's server.
  • Skill naming: plain kebab-case directories, no prefix.
  • Commits: Conventional Commits in English.