Pinecone Codex Plugin — Contributor Guide

How this repo is wired up: the sync pipeline from pinecone-io/skills, the validators, and the release workflow. Open this file in a browser — it is self-contained.

1. Overview

Pinecone publishes one base skills library — pinecone-io/skills — that is intentionally environment-agnostic. The base repo fans out to one downstream plugin repo per agentic IDE: Claude Code, Cursor, and (this repo) Codex. Nothing rewrites a skill after it leaves the base repo. Every Codex-specific value — the bare skill names, the codex_plugin: source tag, the per-target wording — comes from targets/codex.yaml upstream, and tools/build.py renders the tree before it is ever copied here. Read a sync PR as content, not as a transform.

2. Repo layout

3. Sync pipeline (upstream → here)

The base repo's .github/workflows/sync-skills.yml is dispatch-only. It renders every target with uv run tools/build.py --all --check, runs tools/reconcile.py against this repo to report what the sync is about to change, then rsync -a --deletes dist/codex/skills/ over skills/ here and opens a PR on branch sync/skills, labelled skill-sync.

The --delete matters: skills/ is owned entirely by the base repo, so a file you add there by hand is removed by the next sync. Everything outside skills/ — .codex-plugin/, .agents/, .mcp.json, scripts/, docs/, README.md — is owned here and the rsync never sees it.

A PLUGIN_SYNC_PAT personal access token gives the upstream workflow push permission on this repo. The PR body carries the reconcile report and a git checkout plus build.py command that reproduces the diff byte for byte.

4. Validators

All validators are plain Python 3 — stdlib only, no uv or pyyaml needed in CI. Run the whole suite locally:

python3 scripts/check_all.py

5. Release workflow

.github/workflows/release.yml fires on pull_request.types: [closed] against main and only proceeds when github.event.pull_request.merged == true. Bump type is decided by PR labels:

• bump:major → X.0.0
• bump:minor → X.Y+1.0
• neither (default) → X.Y.Z+1

The job:

1. Reads .codex-plugin/plugin.json, bumps the version, writes it back.
2. Generates changelog bullets from gh pr view --json commits --jq '.commits[].messageHeadline', filtering out chore: and create-pull-request entries.
3. Inserts a ## [X.Y.Z] - YYYY-MM-DD block after the # Changelog header.
4. Commits as github-actions[bot], pushes the version-bump commit and a v<version> tag.
5. Creates a GitHub release with auto-generated notes.

6. Codex plugin spec essentials

.codex-plugin/plugin.json shape

{
  "name": "pinecone",              // required, lowercase kebab-case
  "version": "0.1.0",              // semver
  "description": "...",            // user-facing summary
  "skills": "./skills/",           // path, must start with ./
  "mcpServers": "./.mcp.json",     // path, must start with ./
  "interface": {
    "displayName": "Pinecone",
    "category": "Productivity",
    "capabilities": ["Read", "Write"],
    "defaultPrompt": ["Use Pinecone to ...", "..."],
    "brandColor": "#10A37F"
  }
}

Path rules: every path is relative to the plugin root, must start with ./, and must stay inside the plugin root. Assets (icons, logos, screenshots) belong under ./assets/ when present.

.agents/plugins/marketplace.json shape

{
  "name": "pinecone-codex-plugins",
  "interface": { "displayName": "Pinecone for Codex" },
  "plugins": [
    {
      "name": "pinecone",
      "source": { "source": "local", "path": "./" },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}

For Git-backed entries the source object uses "source": "git-subdir" with url, path, and a ref or sha.

7. Adding a new skill manually

Skills belong in pinecone-io/skills, and the next sync deletes anything added here by hand. Add a skill directly only for a throwaway local test:

1. Create skills/<skill-name>/SKILL.md. The directory name is the slug (bare, no pinecone- prefix).
2. Frontmatter must contain name: <same-as-directory> and a single-line description. No allowed-tools key.
3. If the skill ships Python helpers, put them in skills/<skill-name>/scripts/. Every Pinecone(...) call that sets source_tag= must use codex_plugin:<skill>[_<operation>].
4. Run python3 scripts/check_all.py. Iterate until green.
5. Update README.md's skills table.
6. Open a PR. validate.yml will run. Merge once green and the release workflow will tag a new version.

8. Troubleshooting

Source: pinecone-io/pinecone-codex-plugin · base skills: pinecone-io/skills · Codex plugin docs: developers.openai.com/codex/plugins/build.