diff --git a/AGENTS.md b/AGENTS.md index 794f732..675db31 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,34 +2,187 @@ Guidance for AI coding agents working in this repository. -## What this repository is +## Project Overview -A collection of skills for AI coding agents working with the Pro Cycling Manager game. Skills are packaged instructions and scripts that extend agent capabilities. +`agent-skills` (published as the **PCMStack** marketplace) is a content repository of agent +skills and plugins for [Pro Cycling Manager](https://www.cyanide-studio.com/) — an unofficial +community project, not affiliated with Cyanide Studio or Nacon. -## Creating a New Skill +There is **no application code**: no `package.json`, no build step, no test suite, no CI. The +deliverables are Markdown, JSON manifests, and a shell script. Everything an agent changes +here is read by _another_ agent at runtime, so prose quality and accuracy are the product. -Skills follow the [Agent Skills](https://agentskills.io/) format, so they work with any agent that reads it. +Key formats and technologies: -Prefer the `/skill-creator:skill-creator` skill (if available in your agent environment, otherwise skip this step) to create a new skill (or to edit and -improve an existing one). It walks through capturing intent, drafting `SKILL.md`, running -test prompts, and optimizing the description for reliable triggering. Then apply the -repository conventions below to the result. +- [Agent Skills](https://agentskills.io/) — the `SKILL.md` format, portable across agents. +- Claude Code plugin + marketplace manifests (`.claude-plugin/`). +- Codex plugin manifests (`.codex-plugin/`) and the `.agents/plugins/` marketplace. +- MCP servers declared per-plugin in `.mcp.json`. +- Bash scripts; SQLite (`sqlite3`) and Node 22+ (`npx`) at skill runtime, not at authoring time. -### Directory Structure +### Repository Layout ``` -skills/ - {skill-name}/ # kebab-case directory name - SKILL.md # Required: skill definition - scripts/ # Optional: executable scripts - {script-name}.sh # Bash scripts - {script-name}.mjs # Node scripts - references/ # Optional: supporting docs loaded on demand - lib/ # Optional: shared code for scripts +.claude-plugin/marketplace.json # Claude Code marketplace definition +.agents/plugins/marketplace.json # Codex/agents marketplace definition +plugins/ + pcm/ + .claude-plugin/plugin.json # Claude Code plugin manifest + .codex-plugin/plugin.json # Codex plugin manifest (adds `interface` block) + .mcp.json # MCP servers bundled with the plugin (pcm-mcp) + assets/ # logo.svg + app-icon.png, referenced by the Codex manifest + skills/ + pcm-database/ # kebab-case + SKILL.md # Required: skill definition + scripts/open-cdb.sh # Optional: {script-name}.sh / .mjs + references/ # Optional: docs loaded on demand + pcm-startlist/ + SKILL.md +AGENTS.md / CLAUDE.md # CLAUDE.md is a one-line `@AGENTS.md` include +README.md # human-facing; keep it short, guidance lives here ``` +Skills live **inside a plugin** (`plugins/{plugin}/skills/{skill}/`), not at the repo root. +The only plugin is `pcm`, containing `pcm-database` and `pcm-startlist`. + +## Setup Commands + +No install step. Clone and edit. + +Optional tools used when validating changes (invoked ad hoc via `npx`, not dependencies): + +```bash +npx prettier --check "**/*.{md,json}" # formatting +``` + +To exercise a skill end-to-end you need the runtime prerequisites the skills themselves +require: **Node 22+** (for `npx cdb-converter`) and **sqlite3** on `PATH`. A real `.cdb` +file is needed for anything beyond a dry read — never commit one. + +## Development Workflow + +Install the marketplace locally in Claude Code to test plugin changes: + +``` +/plugin marketplace add /Users//Dev/agent-skills +/plugin install pcm@pcmstack +``` + +Then exercise the skill with realistic prompts (e.g. "who's the best climber in my team?", +"build the startlist for the Tour de France") and check that it triggers _and_ that the +instructions hold up. The `defaultPrompt` array in +[plugins/pcm/.codex-plugin/plugin.json](plugins/pcm/.codex-plugin/plugin.json) is a good +source of test prompts. + +Prefer the `/skill-creator:skill-creator` skill (if available in your agent environment, +otherwise skip it) to create or improve a skill. It walks through capturing intent, drafting +`SKILL.md`, running test prompts, and optimizing the description for reliable triggering. +Then apply the repository conventions below to the result. + +## Testing Instructions + +There is no automated test suite. "Testing" here means validation plus behavioural checks: + +```bash +bash -n plugins/pcm/skills/pcm-database/scripts/open-cdb.sh # syntax-check scripts +python3 -m json.tool .json > /dev/null # validate each JSON manifest +npx prettier --check "**/*.{md,json}" # formatting +``` + +Behavioural checks that matter more than the above: + +- **Triggering** — install the plugin and confirm the skill fires on paraphrases, not just the + exact words in its `description`, and in French as well as English (users write both). + Descriptions are the trigger surface; treat a miss as a bug in the description. +- **Cross-manifest consistency** — a skill or plugin added or renamed under `plugins/` must + stay resolvable from both `plugin.json` files (`"skills": "./skills/"`) and both marketplace + files. Renames are the main source of breakage here; grep the old name repo-wide. +- **Script safety** — every script must refuse to clobber user data. `open-cdb.sh` backs up + the `.cdb` first and exits rather than overwriting an existing output; keep that property. +- **Factual accuracy** — schema notes under `references/` describe a real game database. If you + can't verify a column or constraint against an actual `.cdb`, don't assert it. + +## Code Style + ### Naming Conventions -- **Skill directory**: `kebab-case` (e.g., `pcm-database`) -- **SKILL.md**: Always uppercase, always this exact filename -- **Scripts**: `kebab-case.sh` or `kebab-case.mjs` (e.g., `open-cdb.sh`) +- **Plugin directory**: `kebab-case` (e.g. `pcm`), matching `name` in both plugin manifests. +- **Skill directory**: `kebab-case` (e.g. `pcm-database`), matching `name` in its frontmatter. +- **SKILL.md**: always uppercase, always this exact filename. +- **Scripts**: `kebab-case.sh` or `kebab-case.mjs` (e.g. `open-cdb.sh`). +- **References**: `kebab-case.md` (e.g. `database-schema.md`). + +### SKILL.md + +- YAML frontmatter with `name` (matching the directory) and `description`. +- The `description` is what an agent matches a user request against: state what the skill does + **and when to use it**, including phrasings and languages users actually type. Existing + descriptions list trigger phrases explicitly — follow that pattern. +- Body is prose in the second person addressed to the agent, explaining _why_ a rule exists, + not just the rule. Lead with the decision the agent has to make. +- Keep `SKILL.md` focused; push long schema dumps and constraint lists into `references/` and + point at them from the body so they load on demand. +- Wrap Markdown at ~95 characters, matching the existing files. + +### Shell scripts + +- `#!/usr/bin/env bash` + `set -euo pipefail`. +- Header comment: what it does, `Usage:` line, and required runtime. +- Validate argument count and file existence up front; exit with meaningful codes + (`64` usage, `66` missing input, `69` missing dependency, `73` refusing to overwrite). +- Comment the non-obvious decisions — why a backup keeps the `.cdb` extension, why + `--normalize` is passed — rather than restating the command. +- `chmod +x` new scripts. + +### JSON manifests + +- Two-space indent; keep `$schema` where present. +- Descriptions in manifests are user-facing marketing copy; keep the "Unofficial, not + affiliated with Cyanide Studio or Nacon" disclaimer wherever it already appears. +- Bump the plugin `version` in **both** `.claude-plugin/plugin.json` and + `.codex-plugin/plugin.json` together — they must not drift (both are `0.1.0` today). + +## Build and Deployment + +There is no build. Distribution is the git repository itself: users add +`https://github.com/PCMStack/agent-skills` as a marketplace and the manifests at the root are +read directly. Merging to `main` is the release. + +Consequences worth remembering: + +- Every path in a manifest is resolved relative to that manifest's plugin directory or the + repo root — a broken relative path ships silently. +- Adding a new plugin means a new `plugins/{name}/` directory **plus** entries in both + `.claude-plugin/marketplace.json` and `.agents/plugins/marketplace.json`. +- Plugin assets are resolved relative to the plugin directory, which is why `assets/` lives + under `plugins/pcm/` rather than at the repo root. + +## Pull Request Guidelines + +- Commit and PR titles follow Conventional Commits: `feat:`, `docs:`, `fix:` — e.g. + `feat: add pcm-startlist skill`. +- One skill or one coherent change per PR. +- Before opening: JSON manifests parse, scripts pass `bash -n`, and the skill has been + exercised against at least a few realistic prompts. Say in the PR description what you + tested it with. +- Branch off `main`; `main` is the release branch. + +## Security and Data Handling + +- **Never commit a `.cdb` file, a save, or anything from a user's game directory.** They are + large, personal, and copyrighted game data. +- Skills operate on files that may be irreplaceable (a career save can be hundreds of hours). + The invariant every skill and script must preserve: **treat the original `.cdb` as + read-only** — back it up, write edits to a new file, never overwrite in place. +- No secrets or credentials belong in this repository. The bundled MCP server (`pcm-mcp`, run + via `npx -y pcm-mcp`) runs locally on the user's machine and needs none. +- `.claude/settings.local.json` is local, machine-specific permission state — don't extend it + as a way to encode project conventions, and don't rely on paths inside it. + +## Additional Notes + +- `CLAUDE.md` is deliberately a single `@AGENTS.md` include. Keep guidance in this file only. +- `README.md` still lists "Coming soon" under Available Skills; it lags the actual contents. +- Related projects, useful when a skill's behaviour depends on them: + [cdb-converter](https://github.com/PCMStack/converter) (lossless `.cdb` ⇄ SQLite) and + [pcm-mcp](https://github.com/PCMStack/mcp) (MCP server for querying/editing PCM databases). diff --git a/README.md b/README.md index 1e0e157..a6d4049 100644 --- a/README.md +++ b/README.md @@ -1,27 +1,142 @@ -# PCM Agent Skills +
+ PCMStack -A collection of skills for AI coding agents working with [Pro Cycling Manager](https://www.cyanide-studio.com/). Skills are packaged instructions and scripts that extend agent capabilities. +# PCMStack Agent Skills -Skills follow the [Agent Skills](https://agentskills.io/) format, so they work with any agent that reads it. +Read and edit any Pro Cycling Manager database by asking an AI assistant: rosters, startlists, rider ratings changed in plain language. -## Available Skills +[Install](#install) · [Skills](#whats-inside) · [How it works](#how-it-works) · [Development](#development) -Coming soon +
-## Usage +> [!NOTE] +> Unofficial community project. Not affiliated with, endorsed by, or supported by Cyanide +> Studio or Nacon. -Skills are automatically available once installed. The agent will use them when relevant tasks are detected. +Pro Cycling Manager keeps the entire game world — riders, teams, contracts, races — in a +binary `.cdb` file. It is not readable as-is, but it is a SQLite database in disguise, and the +conversion is lossless in both directions. This repository packages that knowledge as +[Agent Skills](https://agentskills.io/): instructions and scripts that teach an AI coding +agent how to open a PCM database, answer questions from real data, and write changes back +without ever putting your save at risk. -## Skill Structure +``` +You ▸ Who are my three best climbers, and how old are they? +You ▸ Bump Pogačar's descending to 80 in a copy of my save +You ▸ Build the startlist for Almería — 20 teams, sprinters up front +``` -Each skill contains: +## Install -- `SKILL.md` — Instructions for the agent -- `scripts/` — Helper scripts for automation (optional) -- `references/` — Supporting documentation, loaded on demand (optional) +The repository is a marketplace containing a single plugin, `pcm`. In **Claude Code**: -## Resources +``` +/plugin marketplace add PCMStack/agent-skills +/plugin install pcm@pcmstack +``` -- [cdb-converter](https://github.com/PCMStack/converter) — Convert Pro Cycling Manager CDB files to/from SQLite. -- [pcm-mcp](https://github.com/PCMStack/mcp) — MCP server for querying and editing Pro Cycling Manager game databases -- [Agent Skills](https://agentskills.io/) — The skill format used here +Then just ask. Skills trigger on their own when a request matches — no command to remember. + +
+Other agents + +The skills follow the portable `SKILL.md` format, so any agent that reads Agent Skills can +use them. Point your agent at `plugins/pcm/skills/`, or clone the repository and add it as a +local marketplace: + +``` +/plugin marketplace add /path/to/agent-skills +``` + +Codex-compatible manifests live in `.agents/plugins/marketplace.json` and +`plugins/pcm/.codex-plugin/plugin.json`. + +
+ +### Requirements + +| Requirement | Why | +| ----------- | ----------------------------------------------------------------- | +| Node 22+ | Runs `cdb-converter` via `npx` for the `.cdb` ⇄ SQLite conversion | +| `sqlite3` | Querying and editing the converted database | +| A `.cdb` | A career save, an official release, or a community update | + +Node and `sqlite3` are only needed at runtime, when a skill actually opens a database. + +## What's inside + +### `pcm-database` + +Open, explore and edit a PCM database. The skill picks between two routes on its own: + +- **pcm-mcp** — the bundled [MCP server](https://github.com/PCMStack/mcp) discovers your saves + on disk and exposes targeted tools (search a cyclist, read a roster, update ratings). Best + for lookups and one-off edits. +- **SQLite** — a lossless `.cdb → sqlite` conversion via + [cdb-converter](https://github.com/PCMStack/converter), giving unrestricted SQL: JOINs, + aggregates, bulk edits. The only option for a file the agent has locally, and the right one + for anything analytical. + +It ships `scripts/open-cdb.sh` (backup + convert + table inventory in one step) and two +reference documents the agent loads on demand: the schema naming conventions with ready-made +queries, and the constraints that must hold for the game to accept an edited database. + +### `pcm-startlist` + +Compose a race startlist — which teams take part, which riders each brings — and export the +`.xml` file PCM imports. The skill resolves the race and the rosters from your database, picks +riders that fit the profile (sprinters for flat finishes, climbers for mountains), and +delegates serialization to `pcm_generate_startlist_xml` so the file is always well-formed. + +## How it works + +``` +your request ──▶ agent ──▶ SKILL.md + │ + ├─▶ pcm-mcp (MCP) ──▶ saves on disk, targeted reads/writes + └─▶ cdb-converter ──▶ database.sqlite ──▶ SQL ──▶ database_edited.cdb +``` + +> [!IMPORTANT] +> A career save can represent hundreds of hours. Every skill and script here treats the +> original `.cdb` as **read-only**: it is backed up first, edits are written to a _new_ file, +> and nothing is ever overwritten in place. Load the edited database in-game and verify it +> before deleting your backup. + +## Development + +There is no build step and no application code — the deliverables are Markdown and JSON +manifests, read by another agent at runtime. + +``` +.claude-plugin/marketplace.json # Claude Code marketplace +.agents/plugins/marketplace.json # Codex/agents marketplace +plugins/pcm/ + .claude-plugin/plugin.json # plugin manifest + .codex-plugin/plugin.json # plugin manifest (Codex, adds `interface`) + .mcp.json # bundled MCP servers + assets/ # logo + app icon + skills/ + pcm-database/ + SKILL.md # required — the skill definition + scripts/ # optional helper scripts + references/ # optional docs, loaded on demand + pcm-startlist/ + SKILL.md +``` + +Install the marketplace from a local clone to try changes, then exercise the skills with +realistic prompts and check they trigger on paraphrases — a description that misses is a bug. +Validation before opening a PR: + +```bash +bash -n plugins/pcm/skills/pcm-database/scripts/open-cdb.sh # syntax-check scripts +python3 -m json.tool .json > /dev/null # validate manifests +npx prettier --check "**/*.{md,json}" # formatting +``` + +## Related projects + +- [cdb-converter](https://github.com/PCMStack/converter) — lossless `.cdb` ⇄ SQLite conversion +- [pcm-mcp](https://github.com/PCMStack/mcp) — MCP server for querying and editing PCM databases +- [Agent Skills](https://agentskills.io/) — the portable skill format used here