Skip to content

docs: rewrite README and expand AGENTS.md #8

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mpicciolli wants to merge 1 commit into
base: main
Choose a base branch
from
+304 −36
Open

docs: rewrite README and expand AGENTS.md #8

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
193 changes: 173 additions & 20 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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/<you>/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 <file>.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).
147 changes: 131 additions & 16 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,27 +1,142 @@
# PCM Agent Skills
<div align="center">
<img src="plugins/pcm/assets/logo.svg" alt="PCMStack" width="96">

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
</div>

## 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.

<details>
<summary>Other agents</summary>

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`.

</details>

### 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 <file>.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