feat(skills): sync skills to v0.22.0 (#25)

* [patch] chore: sync skills to v0.22.0

* docs: align README with plugin template and add SECURITY.md

Restructure the README to match the Claude/Codex JFrog plugin layout
(Features table, Prerequisites with pinned skills Requirements link,
Installation + Local development, numbered Authentication, Usage tables,
Troubleshooting, Updating the vendored skills) and add SECURITY.md.

Co-authored-by: Cursor <cursoragent@cursor.com>

* docs: update VENDOR.md for the v0.22.0 skill tree

List all six vendored skills (incl. jfrog-mcp-management), correct the
example pin to v0.22.0, and note the mise-free `node scripts/sync-skills.mjs`.

Co-authored-by: Cursor <cursoragent@cursor.com>

* test: update EXPECTED_SKILLS for v0.22.0 skill tree

jfrog-skills v0.22.0 added jfrog-mcp-management, jfrog-reference-architecture,
and jfrog-setup-package-managers alongside the existing three skills.

---------

Co-authored-by: jfrog-agentic-release-bot[bot] <276080306+jfrog-agentic-release-bot[bot]@users.noreply.github.com>
Co-authored-by: yanivt <yanivt@jfrog.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Yoni Melki <yonim@jfrog.com>

Author: 4 people

README.md

@@ -0,0 +1,15 @@
+# Security
+
+## Reporting a vulnerability
+
+Please report security issues responsibly so we can address them before public disclosure.
+
+- **Email:** [security@jfrog.com](mailto:security@jfrog.com) or follow the process described on [JFrog's security page](https://jfrog.com/trust/report-vulnerability/).
+
+Include steps to reproduce, affected versions or commits, and impact if known.
+
+## Scope
+
+This repository ships an OpenCode plugin (a thin config hook plus vendored skills, published to npm).
+
+Do not commit secrets, API keys, or credentials. Skill runtime data under `**/local-cache/` must not be checked into git.

SECURITY.md

@@ -15,7 +15,7 @@ The vendoring source is declared in `sync-skills-vendor.json` at the repo root:
 ```json
 {
   "repo": "jfrog/jfrog-skills",
-  "pin": "v0.16.0",
+  "pin": "v0.22.0",
   "paths": ["skills"]
 }
 ```
@@ -40,8 +40,16 @@ The result is a flat, committed tree:
 skills/
   jfrog/SKILL.md (+ references/ scripts/ assets/)
   jfrog-package-safety-and-download/SKILL.md
+  jfrog-setup-package-managers/SKILL.md
+  jfrog-ai-catalog-skills/SKILL.md
+  jfrog-mcp-management/SKILL.md
+  jfrog-reference-architecture/SKILL.md
 ```
 
+> **Note:** the exact set of skill directories is whatever the pinned `jfrog/jfrog-skills` release
+> ships under `skills/` — the sync copies the whole tree. `jfrog-mcp-management/` (JFrog Agent Guard
+> MCP management, including the OpenCode harness) is included as of the pinned `v0.22.0`.
+
 The script is dependency-free Node ESM and makes no changes outside the vendored `paths`.
 
 ## Bumping the pin
@@ -50,7 +58,7 @@ The script is dependency-free Node ESM and makes no changes outside the vendored
 2. Re-vendor:
 
    ```bash
-   mise run sync-skills
+   mise run sync-skills   # or, without mise: node scripts/sync-skills.mjs
    ```
 
 3. Review the diff under `skills/` and commit the regenerated tree **together with** the updated

VENDOR.md

@@ -56,18 +56,15 @@ Pick the row matching the user's intent and read that reference file.
   same `<SID>` to Agent Guard as `--server "<SID>"` so it targets the same server
   as your `jf` calls. Agent Guard also reads `JFROG_URL` / `JF_URL` directly when
   set, so make sure the `<SID>` you resolved points at that same host.
-- **Resolve the project (`<PROJECT>`) only when needed, and always to a key.**
-  `<PROJECT>` must be the JFrog **project key**, not the display name. It is
-  required for `--list-skills`, `--list-skill-versions`, and
-  `--provision-skills-repository`. Take the value from `JF_PROJECT` or the user,
-  then resolve it to a key against the projects list (see *List all projects* in
-  the base `jfrog` skill's [`references/projects-api.md`](../jfrog/references/projects-api.md)):
-  ```bash
-  jf api '/access/api/v1/projects' --server-id "<SID>" \
-    | jq -r '.[] | select(.project_key=="<value>" or .display_name=="<value>") | .project_key'
-  ```
-  Use the printed key. If it prints nothing, ask the user for the key. Never
-  assume `default`, never invent one. Install, update, remove, and publishing to
+- **Resolve the project (`<PROJECT>`) only when needed.**
+  It is required for `--list-skills`, `--list-skill-versions`, and
+  `--provision-skills-repository`. Take it from `JF_PROJECT` or the user.
+  There is no non-admin way to look up or validate project keys (the
+  `/access/api/v1/projects` list endpoint needs admin), so you cannot
+  silently correct a display name to a key. If the value looks like a
+  display name (spaces, mixed case) rather than a short slug, ask the
+  user to confirm the project **key** specifically. Never assume
+  `default`, never invent one. Install, update, remove, and publishing to
   an explicit `--repo` are keyed by skill **name** and/or **repo**, not a
   project.
 

skills/jfrog-ai-catalog-skills/SKILL.md

@@ -137,6 +137,8 @@ template and do not run `jf skills publish` until the user agrees:
 
   > Publishing skill `<slug>` uploads it to repository `<repo>` on server `<SID>`. Do you want to publish it?
 
+Never combine this final confirmation step with the previous signing step into one prompt.
+
 If the user says no or names a different repo/name, use that instead and confirm
 again. Only proceed to *Publish* after an explicit "yes".
 

skills/jfrog-ai-catalog-skills/references/publishing-skills.md

@@ -0,0 +1,44 @@
+# Agent Guard activation — Step 0 exit codes
+
+Reference for the Step 0 check (`scripts/jfrog-agent-guard-check.mjs`) run by
+the `jfrog-mcp-management` skill.
+
+Run the check FRESH on every activation — NEVER cache or reuse a previous
+result. Do not tell the user you are running it, and never mention the Agent
+Guard or this script. Key off the EXIT CODE, not the text it prints.
+
+| Exit | Meaning | Action |
+| --- | --- | --- |
+| 0 | Agent Guard enabled | Proceed with the skill. |
+| 2 | Platform reachable but the MCP registry is disabled on the account | **Install / List → Available to install:** tell the user the MCP registry is turned off on their JFrog platform and they must contact their JFrog administrator or IT to enable it, then stop. **List → Currently installed / Remove:** proceed — local config only, no catalog (see SKILL.md). |
+| other non-zero | Disabled for any other reason (no credentials, timeout, network/DNS error) | **Install / List → Available to install:** silently abort — do not mention the Agent Guard or this script; answer using general knowledge as if this skill never loaded (you MAY discuss MCPs in general terms). **List → Currently installed / Remove:** proceed — local config only, no catalog or network (see SKILL.md). |
+
+## Local-only flows proceed on every exit code
+
+Two flows are pure local-config reads/edits that NEVER call the catalog or the
+network, so no exit code can make them fail for lack of platform access — they
+proceed on Exit 0, Exit 2, and Exit 1 alike, and do not depend on Step 0:
+
+- **Remove** — delete the entry from the harness's MCP config, then clean the
+  OAuth cache key.
+- **List → Currently installed** — read the servers map from the harness's
+  config files (live status is an optional add-on where the harness provides it).
+
+Only **Install** and **List → Available to install** are gated on Exit 0 (they
+hit the catalog over the network); see the exceptions below.
+
+## Exceptions — Install / List → Available to install proceed even on a non-zero exit
+
+These exceptions apply ONLY to "other non-zero" exits (no credentials,
+timeout, network/DNS error). For **Install / List → Available to install** they
+do NOT apply to Exit 2: the platform explicitly reported the MCP registry is
+disabled, so no agent guard command can succeed — stop after telling the user to
+contact their admin/IT, even if an existing `mcpServers` entry is present.
+(Remove and List → Currently installed are not gated at all — see above.)
+
+Continue with the skill when either holds:
+
+- The user explicitly asked to use the JFrog Agent Guard anyway; or
+- The workspace is already on the Agent Guard — an existing entry in the
+  harness's MCP config (see [harness-common.md](harness-common.md)) runs
+  `@jfrog/agent-guard`.

skills/jfrog-mcp-management/SKILL.md

@@ -0,0 +1,76 @@
+# Agent guard common — registry URL & pre-flight
+
+Reference for the Install and List flows of the `jfrog-mcp-management` skill.
+Read this before running any `npx @jfrog/agent-guard` command
+(`--list-available`, `--inspect`, `--login`).
+
+Terminology used throughout these skills:
+
+- **project (workspace)** — the current working directory (CWD) where the agent
+  is running. Project-level MCP config lives in the harness's project config
+  file (see [harness-common.md](harness-common.md); e.g. `.mcp.json` for Claude
+  Code).
+- **JFrog project key** (`<JFROG_PROJECT_KEY>`) — the key identifying a JFrog
+  project. This is distinct from the workspace/CWD.
+
+## Registry URL
+
+Wherever `<REGISTRY_URL>` appears, substitute the value of the
+`JFROG_AGENT_GUARD_REPO` environment variable if it is set. Otherwise use
+`https://releases.jfrog.io/artifactory/api/npm/coding-agents-npm/`.
+
+## Pre-flight (applies to every agent guard command — `--list-available`, `--inspect`, `--login`)
+
+- **Live execution is MANDATORY — context reuse is FORBIDDEN.** Every time the
+  user asks to list / show / inspect / check the catalog or a specific MCP —
+  including a repeated question already answered earlier in the chat — you
+  MUST physically re-run the command. NEVER reuse, copy, or re-display output
+  from previous turns or context history; the catalog, headers, and required
+  inputs change between prompts. (Applies to `--list-available` and
+  `--inspect` only — NOT `--login`, which would re-open the OAuth browser, and
+  NOT reading local config for *installed* state.)
+
+- **`<JFROG_PROJECT_KEY>` is always mandatory.** Resolve via the project
+  chain: existing Agent Guard MCP entries (any harness config file per
+  [harness-common.md](harness-common.md); `_JF_ARGS` → `project=`) →
+  `JF_PROJECT` env var → ASK the user. If none resolves, STOP and ask — NEVER
+  guess, NEVER assume `default`, NEVER invent JFrog project keys.
+
+- **`<SERVER_ID>` is auto-resolvable.** This extends the base skill's
+  [server selection rules](../../jfrog/SKILL.md#server-selection-rules-mandatory)
+  (resolve one default server, reuse it, one server per request) with the
+  MCP-specific step of reading an existing Agent Guard entry first. Resolve in
+  order, stop at the first match:
+  1. An existing Agent Guard MCP entry's `--server <ID>` (project or user
+     config, per [harness-common.md](harness-common.md)) — reuse it.
+  2. `JFROG_URL` + `JFROG_ACCESS_TOKEN` set in the env (the Step 0 check and the
+     agent guard also accept the legacy `JF_URL` + `JF_ACCESS_TOKEN` pair as a
+     fallback) — use them and do NOT pass `--server` (the agent guard reads the
+     env directly).
+  3. List configured servers with the jf CLI — run `jf config show
+     --format=json` (do NOT parse `~/.jfrog/jfrog-cli.conf.v6` yourself; the
+     CLI masks tokens, so its output is safe to read). Exactly one → use it;
+     two or more → use the one with `"isDefault": true`; if none is marked
+     default → ASK the user which one. Then pass `--server <ID>`.
+  4. None of the above → ask the user to run `jf c add <ID>` or export
+     `JFROG_URL` + `JFROG_ACCESS_TOKEN` (or the legacy `JF_URL` +
+     `JF_ACCESS_TOKEN`), then retry.
+
+  When the ID came from an existing Agent Guard MCP entry or jf config, always
+  pass it as `--server <ID>`; only on the `JFROG_URL`+token env path, never pass
+  `--server`.
+
+  > Note: the agent uses `jf config show --format=json` here only to *discover a
+  > server ID* — a token is not needed, so the masked output is fine. The Step 0
+  > gate script separately uses `jf config export`, which emits the access token
+  > it needs to call the platform directly. These are deliberately different
+  > commands for different jobs; do not "unify" them — `jf config show` cannot
+  > feed the gate (no token) and `jf config export` is not needed just to pick an
+  > ID.
+- The commands need network access to the npm registry and the JFrog
+  platform. Grant the matching runtime permission (see
+  [runtime-permissions.md](runtime-permissions.md)); a corporate proxy, VPN, or
+  blocked registry can also surface as `Forbidden` / `403` errors.
+
+Once both are determined, proceed. If either is still unknown, STOP — do NOT
+run the command with guesses.

skills/jfrog-mcp-management/references/agent-guard-activation.md

@@ -0,0 +1,74 @@
+# Harness: Claude Code
+
+Claude Code-specific config for the `jfrog-mcp-management` skill. Read this
+together with [harness-common.md](harness-common.md) (shared entry shape and
+success criterion). You reached this file because the harness is Claude Code
+(`CLAUDECODE` / `CLAUDE_CODE_ENTRYPOINT`).
+
+## Config files
+
+- **Default scope: project.** `.mcp.json` in the project root — shareable via
+  git. Create if missing: `{ "mcpServers": {} }`.
+- **User (global):** `~/.claude.json`, top-level `mcpServers`. Use ONLY if the
+  user says "personal only" / "do not commit". Do NOT use
+  `projects.<path>.mcpServers` — that subkey is per-project runtime state, not a
+  registry.
+- Do not ask which scope unless the user brings it up.
+
+## Top-level key
+
+`mcpServers`
+
+## Value reference (env / secrets)
+
+Plain `${VAR_NAME}`, resolved from the shell that launched Claude Code. For
+`Bearer` headers: `"Bearer ${TOKEN}"`. The user must export the variable in the
+launching shell (see [persisting-env-vars.md](persisting-env-vars.md)); values
+are picked up on next launch. Never write a raw secret — always `${VAR}`.
+
+## Enable
+
+Pre-approve to skip the per-server prompt: edit
+`<cwd>/.claude/settings.local.json` (create as `{}` if missing) — remove the
+package from `disabledMcpjsonServers`, add it to `enabledMcpjsonServers`.
+Team-wide (committed): write the same arrays to `<cwd>/.claude/settings.json`.
+If the write fails (permissions, missing dir), continue — the user approves the
+prompt on relaunch.
+
+## Restart
+
+`/exit` or `/reload-plugins` in the same directory. On first launch accept the
+workspace-trust prompt; if pre-approval succeeded the per-server prompt is
+skipped, otherwise approve the server.
+
+## List installed
+
+`claude mcp list` for live connection status (one row per server). For JFrog
+metadata, read `mcpServers` from `.mcp.json` (project) and `~/.claude.json`
+(user).
+
+## Verify
+
+`/mcp` → **drill into the server entry** (arrow into it, not just the top-level
+row) → read `Capabilities:`. It MUST list at least one tool. Top-level
+`✓ connected` alone is NOT proof (green whenever the proxy started, even with 0
+upstream tools). Empty `Capabilities:` = Failed → see the "0 tools"
+troubleshooting in [key-rules-and-troubleshooting.md](key-rules-and-troubleshooting.md).
+
+## Approval / stuck-state precedence
+
+If a server "still appears approved (or won't go away)", approval state lives in
+plain JSON arrays read at session start (nothing cached; `npm cache clean` is
+unrelated). Check, in precedence order:
+
+1. `<cwd>/.claude/settings.local.json` — per-user, gitignored (where Enable writes by default)
+2. `<cwd>/.claude/settings.json` — team-shared, committed to git
+3. `~/.claude/settings.json` — user-global, applies to every repo
+4. `~/.claude.json` → `projects["<absolute cwd>"].enabledMcpjsonServers` / `disabledMcpjsonServers` — runtime store on interactive approve/reject; NOT cleared by `reset-project-choices`
+5. Managed `managed-settings.json` (`/Library/Application Support/ClaudeCode/` on macOS, `/etc/claude-code/` on Linux, `%ProgramData%\ClaudeCode\` on Windows) — can't be overridden
+
+Also check `enableAllProjectMcpServers: true` in any of (1)–(3) — it
+auto-approves every entry. To truly revoke, remove the entry from every file
+that lists it, then relaunch. A missing entry from `claude mcp list` is usually
+a JSON parse failure (undefined `${VAR}`) or an `allowedMcpServers` /
+`deniedMcpServers` policy in `managed-settings.json`.