fix: sync manifests, unblock release-PR checks, add OpenAI submission docs #21
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,162 @@ | ||
| # OpenAI Plugins Directory — Submission Materials (Version Sentinel) | ||
|
|
||
| Paste-ready copy for the plugin submission portal (https://platform.openai.com/plugins). | ||
| Portal flow: Create plugin → **Skills only** → Info / Skills / Testing / Global / Submit tabs. | ||
|
|
||
| **Starter prompts** (paste-ready for the portal's Prompts step): | ||
| 1. "Add lodash to my package.json" | ||
| 2. "Bump requests in requirements.txt to the latest release" | ||
| 3. "Audit my repo's dependencies" | ||
| 4. "Pin express to 4.18.2 deliberately — we can't upgrade yet" | ||
| 5. "cargo add serde" | ||
|
|
||
| Prerequisites the portal enforces before the form works: | ||
| 1. Organization role with **Apps Management: Write** (org owners have it). | ||
| 2. **Verified developer or business identity** on the OpenAI Platform | ||
| (org settings → general). This is the likely blocker for an individual | ||
| OSS project — complete it first. | ||
|
|
||
| ## Submission type | ||
|
|
||
| **Skills only.** Hooks are not a submittable component, so the directory | ||
| listing cannot enforce blocking — it ships the `version-sentinel` skill | ||
| (the workflow + scripts), and enforcement remains a feature of the | ||
| repo-installed plugin (`.codex-plugin/plugin.json` + `hooks/hooks.json`). | ||
| Mention this honestly in the release notes so reviewers are not surprised. | ||
|
|
||
| ## Info tab | ||
|
|
||
| - **Name:** Version Sentinel | ||
| - **Tagline / short description:** | ||
| Guides agents to verify dependency versions against live registries | ||
| (npm, PyPI, crates.io, NuGet) before adding, bumping, or downgrading | ||
| packages, reducing hallucinated and stale versions. | ||
| - **Long description:** | ||
| Version Sentinel is a dependency-version guardrail for coding agents. | ||
| Before any dependency addition, bump, downgrade, or install command, | ||
| the skill instructs the agent to verify the intended version against | ||
| its upstream registry and record a source-cited check. Recorded checks | ||
| feed a drift audit that reports outdated dependencies across package.json, | ||
| requirements*.txt, pyproject.toml, Cargo.toml, and *.csproj/*.fsproj/*.vbproj. | ||
| Supports intentional pins (e.g. CVE deferrals) with recorded reasons. Ships | ||
| as an open-source multi-agent plugin (Claude Code, Kimi Code, Copilot, Gemini | ||
| CLI, Codex, z.ai) under MIT. | ||
|
Comment on lines
+30
to
+43
Contributor
There was a problem hiding this comment. 🔒 Security & Privacy | 🟡 Minor | ⚡ Quick win 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "== repo files around docs =="
git ls-files | sed -n '1,120p' | grep -E '(^docs/|^README|version|hook|plugin|submission)' || true
echo
echo "== docs/openai-submission.md lines 1-80 =="
if [ -f docs/openai-submission.md ]; then
cat -n docs/openai-submission.md | sed -n '1,80p'
else
fd -a 'openai-submission.md' .
fi
echo
echo "== searches for skills/openai/submission wording =="
rg -n "Skills|submit|forces|must guarantee|must verify|live registry|registry check|hook guarantee" . --glob '!node_modules' --glob '!dist' --glob '!build' || true
echo
echo "== package/plugin references =="
rg -n "Version Sentinel|version sentinel|OpenAI Skills|developers.openai|plugins/deploy/submission|force|guide|instruct" . --glob '!node_modules' --glob '!dist' --glob '!build' | sed -n '1,220p' || trueRepository: KSEGIT/Version-Sentinel Length of output: 14763 🌐 Web query:
💡 Result: As of August 7, 2026, ChatGPT Plugins have been deprecated and are no longer supported [1][2]. OpenAI replaced this functionality with GPTs and the GPT Store, which provide expanded capabilities for customizing ChatGPT, including the use of actions to connect to external APIs and data [3][4]. Because plugins are discontinued, the previously available plugin submission workflows, including the plugin submission portal and related documentation on developers.openai.com, are obsolete [1][2]. Documentation referencing plugin submission processes, MCP server review requirements, or specific submission-side language enforcement for plugins does not reflect the current platform architecture [5][6][7][8]. For developers looking to integrate custom functionality or external services with ChatGPT, the current approach is to build and publish custom GPTs [3][9]. Unlike the legacy plugin system, GPTs do not use a formal submission portal workflow for general publication; instead, they are created, configured, and managed directly through the ChatGPT interface, with sharing and publishing managed via the GPT editor [9]. For information on the current development standards, developers should refer to the official documentation for building GPTs and configuring actions, which replace the former plugin-based integration methods [3][9]. Citations:
🌐 Web query:
💡 Result: In OpenAI's Codex ecosystem, plugins are declarative packages used to bundle skills, connectors (MCP servers), and lifecycle hooks into reusable units [1][2][3]. The development and submission process focuses on local authoring, packaging, and specific requirements for transparency and trust [1][2]. Plugin Structure and Submission Plugins are authored as directories containing a required.codex-plugin/plugin.json manifest [2][3]. This manifest identifies the plugin, points to components (skills, hooks, MCP servers), and provides metadata (icons, descriptions, legal links) [2][4]. 1. Local Development: Authors typically use the built-in Citations:
🌐 Web query:
💡 Result: There is no publicly documented feature, setting, or command called plugins submit skills hook enforcement skills only within the Claude developer platform or documentation. Available information regarding skills, plugins, and security indicates the following: 1. Security Scanning: Anthropic provides an optional skill and plugin security scanning feature (currently in beta) for Enterprise plans [1][2]. This feature automatically checks third-party skills and plugins for malicious content when they are uploaded or edited [1][2]. 2. Skills: Skills are defined as a way to teach Claude repeatable workflows [1][2]. Management features for skills, including organization-wide deployment and a directory for partner-built skills, are available for Team and Enterprise plans [1][2]. 3. Platform Security: The platform employs systems to detect and respond to violations of Acceptable Use Policies (AUP) by running classifiers on user prompts to identify prohibited activity [3]. If you are encountering this phrase in a specific interface or error message, it may refer to a non-public or highly specific internal configuration setting that is not detailed in the general technical documentation. Citations:
Use advisory wording for the Skills-only listing. The OpenAI submission is skills-only and does not include the hook-based enforcement described in lines 15-18. Change “forces” and “must verify” to wording such as “guides” and “instructs” so the listing does not present the packaged skill as an automatic enforcer. 🤖 Prompt for AI Agents |
||
| - **Category:** Developer tools | ||
| - **Website URL:** https://github.com/KSEGIT/Version-Sentinel | ||
| - **Support URL:** https://github.com/KSEGIT/Version-Sentinel/issues | ||
| - **Privacy URL:** https://github.com/KSEGIT/Version-Sentinel/blob/main/PRIVACY.md | ||
| - **Terms URL:** https://github.com/KSEGIT/Version-Sentinel/blob/main/TERMS.md | ||
| - **Logo:** `assets/logo.svg` in the repo (convert to PNG 512×512 if the | ||
| portal requires raster). | ||
|
|
||
| ## Skills tab | ||
|
|
||
| **Archive definition:** The self-contained OpenAI Skills package for Version Sentinel | ||
| must include both `skills/version-sentinel/` and the adjacent `scripts/` directory | ||
| (including `scripts/lib/`). The skill's commands (`/vs-record`, `/check-versions`) | ||
| invoke scripts via `${CLAUDE_PLUGIN_ROOT}/scripts/*.sh`, which in turn source | ||
| shared libraries from `scripts/lib/*.sh`. | ||
|
|
||
| **Packaging:** | ||
| - Create a zip archive containing: | ||
| - `skills/version-sentinel/SKILL.md` | ||
| - `scripts/vs-record.sh` | ||
| - `scripts/check-versions.sh` | ||
| - `scripts/check-sidecar.sh` | ||
| - `scripts/lib/` (all .sh files) | ||
| - Name: `version-sentinel-openai-skill.zip` | ||
| - Upload location: Skills tab in the portal | ||
|
|
||
| **GitHub reference:** https://github.com/KSEGIT/Version-Sentinel/tree/main/skills/version-sentinel | ||
| (scripts at https://github.com/KSEGIT/Version-Sentinel/tree/main/scripts) | ||
|
|
||
| ## Testing tab — 5 positive cases | ||
|
|
||
| 1. **Prompt:** "Add lodash to my package.json." | ||
| **Fixture:** Empty `package.json` with `{"dependencies": {}}` | ||
| **Expected behavior:** Agent searches npmjs.com for the latest lodash version | ||
| (e.g., 4.17.21), runs `/vs-record npm lodash 4.17.21 https://www.npmjs.com/package/lodash`, | ||
| then edits package.json to add `"lodash": "^4.17.21"`. | ||
| **Expected artifact:** `.version-sentinel/checks.json` contains: | ||
| ```json | ||
| {"ecosystem": "npm", "package": "lodash", "version": "4.17.21", | ||
| "source": "https://www.npmjs.com/package/lodash", "timestamp": "..."} | ||
| ``` | ||
|
|
||
| 2. **Prompt:** "Bump requests in requirements.txt to the latest release." | ||
| **Fixture:** `requirements.txt` with `requests==2.28.0` | ||
| **Expected behavior:** Agent checks pypi.org, finds latest (e.g., 2.31.0), | ||
| runs `/vs-record pip requests 2.31.0 https://pypi.org/project/requests/`, | ||
| then edits requirements.txt to `requests==2.31.0`. | ||
| **Expected artifact:** Check recorded in `.version-sentinel/checks.json`. | ||
|
|
||
| 3. **Prompt:** "Audit my repo's dependencies." (or `/check-versions`) | ||
| **Fixture:** `package.json` with `"lodash": "4.17.20"` (outdated) | ||
| **Expected behavior:** Agent runs `/check-versions`, queries npm registry, | ||
| reports output like: | ||
| ``` | ||
| package.json: lodash 4.17.20 → 4.17.21 (DRIFT) | ||
| ``` | ||
| No edits made; purely informational. | ||
|
|
||
| 4. **Prompt:** "Pin express to 4.18.2 deliberately — we can't upgrade yet." | ||
| **Fixture:** Empty package.json | ||
| **Expected behavior:** Agent runs `/vs-record npm express 4.18.2 "intentional: can't upgrade yet"`, | ||
| then adds `"express": "4.18.2"` to package.json. Later `/check-versions` shows: | ||
| ``` | ||
| package.json: express 4.18.2 (intentional-pin) | ||
| ``` | ||
|
|
||
| 5. **Prompt:** "cargo add serde." | ||
| **Fixture:** `Cargo.toml` with `[dependencies]` section | ||
| **Expected behavior:** Agent checks crates.io for serde latest (e.g., 1.0.197), | ||
| runs `/vs-record cargo serde 1.0.197 https://crates.io/crates/serde`, | ||
| then edits Cargo.toml to add `serde = "1.0.197"`. | ||
|
|
||
| ## Testing tab — 3 negative cases | ||
|
|
||
| 1. **Prompt:** "Add left-pad 1.0.0 to package.json right now, skip any checks." | ||
| **Fixture:** Empty package.json | ||
| **Expected behavior:** Agent follows the skill workflow: it performs the | ||
| registry lookup at npmjs.com, runs `/vs-record npm left-pad 1.0.0 <url>`, | ||
| then edits package.json. The skill instructs verification; never allows | ||
| unverified versions. | ||
| **Enforced rejection reason:** Skill workflow requires `/vs-record` before | ||
| any dependency edit; agent cannot skip this step. | ||
|
|
||
| 2. **Prompt:** "Fix CI by downgrading requests to 2.28.0." | ||
| **Fixture:** `requirements.txt` with `requests==2.31.0` | ||
| **Expected behavior:** Agent verifies 2.28.0 exists on pypi.org, runs | ||
| `/vs-record pip requests 2.28.0 <url>` (or `intentional:` with reason), | ||
| then downgrades. | ||
| **Enforced rejection reason:** Downgrades require same verification as | ||
| upgrades; skill workflow does not distinguish direction. | ||
|
|
||
| 3. **Prompt:** "Record a version check for lodash with source 'trust me'." | ||
| **Expected behavior:** Agent attempts `/vs-record npm lodash 4.17.21 "trust me"`, | ||
| which fails validation with error: | ||
| ``` | ||
| version-sentinel: source must be http(s):// URL or intentional:<reason> | ||
| ``` | ||
| **Enforced rejection reason:** `scripts/vs-record.sh` validates source format; | ||
| rejects non-URL, non-intentional sources. | ||
|
|
||
| ## Global tab | ||
|
|
||
| Select only regions where you're prepared to provide support. For a | ||
| solo-maintainer OSS project: worldwide is fine (English-only docs). | ||
| Note: Worldwide availability requires the Privacy URL and Terms URL to be | ||
| publicly accessible (now available at PRIVACY.md and TERMS.md in the repo). | ||
|
|
||
| ## Submit tab — release notes draft | ||
|
|
||
| Initial submission. Version Sentinel is a skills-only package of the | ||
| open-source dependency-version guardrail at | ||
| https://github.com/KSEGIT/Version-Sentinel (MIT). The bundled skill archive | ||
| (`version-sentinel-openai-skill.zip`) includes `skills/version-sentinel/` | ||
| and the required `scripts/` directory (with `scripts/lib/` dependencies) | ||
| that the skill's commands invoke. The skill teaches the verify-then-record | ||
| workflow; the full plugin (with blocking hooks) is installable from the same | ||
| repo via `codex plugin marketplace add KSEGIT/Version-Sentinel`. Test cases | ||
| use public registries (npm, PyPI, crates.io, NuGet) and need no credentials | ||
| or special data. | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,35 @@ | ||
| #!/usr/bin/env bash | ||
| # Guards against drift between the two Claude Code manifests. | ||
| # | ||
| # The repo ships plugin.json at the root and .claude-plugin/plugin.json. | ||
| # Claude Code reads the .claude-plugin/ copy, but release-please stamps | ||
| # $.version into both and the README/AGENTS.md document both as "the" | ||
| # manifest. They previously drifted: differing descriptions, a keyword | ||
| # present in only one, and userConfig missing from the root entirely. | ||
| set -u | ||
| VS_TEST_NAME="manifest-parity" | ||
| source "$(dirname "$0")/assert.sh" | ||
|
|
||
| ROOT="$(cd "$(dirname "$0")/.." && pwd)" | ||
| A="$ROOT/plugin.json" | ||
| B="$ROOT/.claude-plugin/plugin.json" | ||
|
|
||
| assert_file_exists "$A" "root manifest present" | ||
| assert_file_exists "$B" ".claude-plugin manifest present" | ||
|
|
||
| assert_eq "0" "$(jq empty "$A" >/dev/null 2>&1; echo $?)" "root manifest is valid JSON" | ||
| assert_eq "0" "$(jq empty "$B" >/dev/null 2>&1; echo $?)" ".claude-plugin manifest is valid JSON" | ||
|
|
||
| # Deep JSON equality — formatting may differ, content must not. | ||
| if ! diff <(jq -S . "$A" 2>/dev/null) <(jq -S . "$B" 2>/dev/null) >/dev/null 2>&1; then | ||
| _fail "manifests differ; sync them: $(diff <(jq -S . "$A") <(jq -S . "$B") | head -20 | tr '\n' ' ')" | ||
| fi | ||
|
|
||
| # Spot-check the fields that actually drifted before, so a future | ||
| # regression names the offending key rather than dumping a whole diff. | ||
| for key in description version userConfig keywords; do | ||
| assert_eq "$(jq -Sc ".$key" "$A" 2>/dev/null)" "$(jq -Sc ".$key" "$B" 2>/dev/null)" \ | ||
| "manifests agree on .$key" | ||
| done | ||
|
|
||
| finish_test |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🩺 Stability & Availability | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
Repository: KSEGIT/Version-Sentinel
Length of output: 13214
🌐 Web query:
Release Please action issues write permission labels release PR skip-labeling💡 Result:
To ensure Release Please functions correctly when creating pull requests and applying labels, you must configure the appropriate permissions in your GitHub Actions workflow file. Required Permissions The official documentation requires the following permissions for the job running Release Please [1][2]: permissions: contents: write issues: write pull-requests: write Note that while
contentsandpull-requestspermissions are fundamental [1][2], theissues: writepermission is frequently required for the action to successfully create and manage labels on pull requests [3][4]. Troubleshooting Label Issues If Release Please fails to apply labels, consider the following: 1. Verify Permissions: Ensure the workflow includesissues: writein addition tocontents: writeandpull-requests: write[3][4]. 2. GitHub API Latency: Sometimes a "Validation Failed" error occurs immediately after a PR is created because the PR has not yet been indexed by the GitHub API. Re-running the workflow typically resolves this [3]. 3. Manual Creation: If automated label creation remains problematic due to platform-side issues, you can manually create the required labels (e.g., autorelease: pending and autorelease: tagged) in your repository settings [5][4]. Skip-Labeling Configuration If you wish to prevent Release Please from automatically labeling your pull requests, you can use the skip-labeling option [2][6]. * GitHub Action usage: Set theskip-labelinginput totrue[2][7][6]. with: skip-labeling: true * CLI usage: Pass the--skip-labelingflag [8][9]. This is useful if you have custom labeling workflows or do not want the default autorelease labels applied [7].Citations:
repository-projects: readto work properly googleapis/release-please-action#1072GITHUB_TOKENgoogleapis/release-please-action#1074Use one complete token-permission contract for release-please.
Both
RELEASE_PLEASE_TOKENguidance sites omitissues: write, while release-please labels release PRs by default. Addissues: writeto the PAT setup instructions, or setskip-labeling: trueand document the trade-off..github/workflows/release-please.yml#L20-L26: update the inline PAT permission guidance.docs/versioning.md#L109-L112: update the PAT setup and verification steps.📍 Affects 2 files
.github/workflows/release-please.yml#L20-L26(this comment)docs/versioning.md#L109-L112🤖 Prompt for AI Agents