From 54d9c3278a6b0463ca50d4772f4b40d0fc2c13d5 Mon Sep 17 00:00:00 2001 From: Mathieu Picciolli Date: Wed, 12 Aug 2026 07:46:48 -0400 Subject: [PATCH 1/6] docs: add AGENTS.md and link from CLAUDE.md --- AGENTS.md | 45 +++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 1 + 2 files changed, 46 insertions(+) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..dcfdc64 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,45 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## What this repository is + +A collection of [Agent Skills](https://agentskills.io/) for Pro Cycling Manager, published as `PCMStack/agent-skills` and installed via `npx skills add PCMStack/agent-skills`. There is no build, no test suite, and no lint config — the deliverable is prose plus a few helper scripts. "Working on this codebase" almost always means writing or revising skill instructions. + +The audience for every file under `skills/` is an _agent_, not a human. Content is judged on whether it changes what an agent does: what route it picks, what it verifies, what it refuses to do. + +## Layout + +``` +skills// + SKILL.md # always loaded — frontmatter + instructions + references/*.md # loaded on demand, only when SKILL.md says to + scripts/*.sh # optional helpers, invoked by the agent +``` + +`README.md` at the root doubles as the public index: it lists shipped skills, and a "Planned Skills" table of the ~9 remaining domains (startlists, season planning, transfers, training, modding, stages, assets, mods, save repair). **When a new skill ships, move it out of that table into "Available Skills" in the same commit** — the README is the only place the roadmap lives. + +## Writing a SKILL.md + +Follow `skills/pcm-db-editor/SKILL.md` as the reference implementation; it encodes the house style. + +- **Frontmatter is `name` + `description` only.** The description is the trigger — it must be long and over-inclusive, listing the vocabulary a user would actually use _and_ explicitly covering the cases where they never say the technical term ("even if they never say the words 'cdb' or 'database', and even if they only want to read something"). Under-triggering is the failure mode that matters. +- **Explain the reasoning, not just the rule.** Every constraint states _why_, so the agent can generalize when reality doesn't match the doc — e.g. no DDL "because the CDB data types and column indices are encoded in each column's declared type string". +- **Split by load cost.** SKILL.md carries decision-making (which route, what's forbidden, how to report). `references/` carries lookup material (naming tables, worked queries). SKILL.md must name the reference file _and the moment to read it_ ("as soon as you're writing anything beyond a single-table SELECT"). +- **Route tables over prose** when there's a fork in the road, and state the discriminating fact — pcm-db-editor routes purely on _where the file physically lives_, because that determines what can touch it. +- Prefer imperatives with a stated cost ("`cp save.cdb save.cdb.bak` costs nothing") over generic caution. + +## Non-negotiable domain invariants + +These hold across every current and planned skill, because a PCM career represents hundreds of hours: + +- The user's original file is **read-only**. Back it up before touching anything; write results to a _new_ file. +- **Watch default output paths.** `npx cdb-converter save.sqlite` writes to `save.cdb` — plausibly the user's original. Always pass an explicit output path. +- **Never answer from memory about PCM's schema.** Column names drift between game years (2014→2026 share the container format, not the columns). Every recipe in `references/` starts from a discovery query for this reason; keep it that way when adding recipes. +- Tell the user to load the edited file in-game and verify before deleting the backup. + +## Scripts + +Bash, `set -euo pipefail`, distinct exit codes (64 usage / 66 missing input / 69 missing dependency / 73 output exists), and **refuse to clobber** rather than prompt. Each script ends by printing the next commands the agent should run, so the script hands control back rather than being a black box. External dependencies are Node 22+ (`npx cdb-converter`) and `sqlite3` on PATH — check for them and exit cleanly if absent. + +Test a script change by running it against a real `.cdb`; there is no harness. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md From c48676c892d2267b693da2f390832d82b6ca1b55 Mon Sep 17 00:00:00 2001 From: Mathieu Picciolli Date: Wed, 12 Aug 2026 07:47:57 -0400 Subject: [PATCH 2/6] docs: update AGENTS.md and README.md for consistency in links and content --- AGENTS.md | 56 ++++++++++++++++++++++--------------------------------- README.md | 4 ++-- 2 files changed, 24 insertions(+), 36 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index dcfdc64..6362702 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,45 +1,33 @@ -# CLAUDE.md +# AGENTS.md -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. +Guidance for AI coding agents working in this repository. ## What this repository is -A collection of [Agent Skills](https://agentskills.io/) for Pro Cycling Manager, published as `PCMStack/agent-skills` and installed via `npx skills add PCMStack/agent-skills`. There is no build, no test suite, and no lint config — the deliverable is prose plus a few helper scripts. "Working on this codebase" almost always means writing or revising skill instructions. +A collection of skills for AI coding agents working with Pro Cycling Manager game. Skills are packaged instructions and scripts that extend agent capabilities. -The audience for every file under `skills/` is an _agent_, not a human. Content is judged on whether it changes what an agent does: what route it picks, what it verifies, what it refuses to do. +## Creating a New Skill -## Layout +Always use the `/skill-creator:skill-creator` skill 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. + +### Directory Structure ``` -skills// - SKILL.md # always loaded — frontmatter + instructions - references/*.md # loaded on demand, only when SKILL.md says to - scripts/*.sh # optional helpers, invoked by the agent +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 ``` -`README.md` at the root doubles as the public index: it lists shipped skills, and a "Planned Skills" table of the ~9 remaining domains (startlists, season planning, transfers, training, modding, stages, assets, mods, save repair). **When a new skill ships, move it out of that table into "Available Skills" in the same commit** — the README is the only place the roadmap lives. - -## Writing a SKILL.md - -Follow `skills/pcm-db-editor/SKILL.md` as the reference implementation; it encodes the house style. - -- **Frontmatter is `name` + `description` only.** The description is the trigger — it must be long and over-inclusive, listing the vocabulary a user would actually use _and_ explicitly covering the cases where they never say the technical term ("even if they never say the words 'cdb' or 'database', and even if they only want to read something"). Under-triggering is the failure mode that matters. -- **Explain the reasoning, not just the rule.** Every constraint states _why_, so the agent can generalize when reality doesn't match the doc — e.g. no DDL "because the CDB data types and column indices are encoded in each column's declared type string". -- **Split by load cost.** SKILL.md carries decision-making (which route, what's forbidden, how to report). `references/` carries lookup material (naming tables, worked queries). SKILL.md must name the reference file _and the moment to read it_ ("as soon as you're writing anything beyond a single-table SELECT"). -- **Route tables over prose** when there's a fork in the road, and state the discriminating fact — pcm-db-editor routes purely on _where the file physically lives_, because that determines what can touch it. -- Prefer imperatives with a stated cost ("`cp save.cdb save.cdb.bak` costs nothing") over generic caution. - -## Non-negotiable domain invariants - -These hold across every current and planned skill, because a PCM career represents hundreds of hours: - -- The user's original file is **read-only**. Back it up before touching anything; write results to a _new_ file. -- **Watch default output paths.** `npx cdb-converter save.sqlite` writes to `save.cdb` — plausibly the user's original. Always pass an explicit output path. -- **Never answer from memory about PCM's schema.** Column names drift between game years (2014→2026 share the container format, not the columns). Every recipe in `references/` starts from a discovery query for this reason; keep it that way when adding recipes. -- Tell the user to load the edited file in-game and verify before deleting the backup. - -## Scripts - -Bash, `set -euo pipefail`, distinct exit codes (64 usage / 66 missing input / 69 missing dependency / 73 output exists), and **refuse to clobber** rather than prompt. Each script ends by printing the next commands the agent should run, so the script hands control back rather than being a black box. External dependencies are Node 22+ (`npx cdb-converter`) and `sqlite3` on PATH — check for them and exit cleanly if absent. +### Naming Conventions -Test a script change by running it against a real `.cdb`; there is no harness. +- **Skill directory**: `kebab-case` (e.g., `pcm-db-editor`) +- **SKILL.md**: Always uppercase, always this exact filename +- **Scripts**: `kebab-case.sh` or `kebab-case.mjs` (e.g., `open-cdb-sh`) diff --git a/README.md b/README.md index 12a0570..4de0c96 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ PCM is a game built on files: a binary `.cdb` database holding your whole career ### pcm-db-editor -Opens, explores and edits Pro Cycling Manager save files and game databases (`.cdb`). Routes between the [pcm-mcp](https://github.com/mpicciolli/pcm-mcp) MCP server for saves living on your own machine, and a lossless `cdb → SQLite` conversion for files you can read directly — then writes changes back to a new file, never over your career. +Opens, explores and edits Pro Cycling Manager save files and game databases (`.cdb`). Routes between the [pcm-mcp](https://github.com/PCMStack/pcm-mcp) MCP server for saves living on your own machine, and a lossless `cdb → SQLite` conversion for files you can read directly — then writes changes back to a new file, never over your career. **Use when:** @@ -96,5 +96,5 @@ Each skill contains: ## Resources -- [pcm-mcp](https://github.com/mpicciolli/pcm-mcp) — MCP server for Pro Cycling Manager saves +- [pcm-mcp](https://github.com/PCMStack/pcm-mcp) — MCP server for Pro Cycling Manager saves - [cdb-converter](https://www.npmjs.com/package/cdb-converter) — lossless `.cdb` ↔ SQLite converter From caed20f6c481f7cf4b8bfa0626078880d795866b Mon Sep 17 00:00:00 2001 From: Mathieu Picciolli Date: Wed, 12 Aug 2026 08:07:32 -0400 Subject: [PATCH 3/6] docs: add clarification on skill format in AGENTS.md --- AGENTS.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 6362702..3a02bb9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,6 +8,8 @@ A collection of skills for AI coding agents working with Pro Cycling Manager gam ## Creating a New Skill +Skills follow the [Agent Skills](https://agentskills.io/) format, so they work with any agent that reads it. + Always use the `/skill-creator:skill-creator` skill 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 From 08929d0126ccdd67c67f3e65b1ce5a3b13816116 Mon Sep 17 00:00:00 2001 From: Mathieu Picciolli Date: Wed, 12 Aug 2026 08:24:00 -0400 Subject: [PATCH 4/6] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 3a02bb9..d10a402 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,7 +4,7 @@ Guidance for AI coding agents working in this repository. ## What this repository is -A collection of skills for AI coding agents working with Pro Cycling Manager game. Skills are packaged instructions and scripts that extend agent capabilities. +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. ## Creating a New Skill From 795b0bb8e716310a1b0d51a8a6cbac42830e9739 Mon Sep 17 00:00:00 2001 From: Mathieu Picciolli Date: Wed, 12 Aug 2026 08:24:24 -0400 Subject: [PATCH 5/6] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index d10a402..b494a19 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -32,4 +32,4 @@ skills/ - **Skill directory**: `kebab-case` (e.g., `pcm-db-editor`) - **SKILL.md**: Always uppercase, always this exact filename -- **Scripts**: `kebab-case.sh` or `kebab-case.mjs` (e.g., `open-cdb-sh`) +- **Scripts**: `kebab-case.sh` or `kebab-case.mjs` (e.g., `open-cdb.sh`) From 08e0d2dd644f286ae520b32596af1ee7ee93ec3e Mon Sep 17 00:00:00 2001 From: Mathieu Picciolli Date: Wed, 12 Aug 2026 08:28:56 -0400 Subject: [PATCH 6/6] docs: clarify usage of skill-creator in AGENTS.md --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index b494a19..23cd285 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,7 +10,7 @@ A collection of skills for AI coding agents working with the Pro Cycling Manager Skills follow the [Agent Skills](https://agentskills.io/) format, so they work with any agent that reads it. -Always use the `/skill-creator:skill-creator` skill to create a new skill (or to edit and +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.