Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
124 changes: 90 additions & 34 deletions skills/jfrog-ai-catalog/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,50 +48,105 @@ Pick the row matching the user's intent and read that reference file.
- The [environment check](../jfrog/SKILL.md#environment-check) — confirm `jf`
is installed before the first `jf` call, and install it if missing.
- The [server selection rules](../jfrog/SKILL.md#server-selection-rules-mandatory)
— resolve the default `<SID>` once and reuse it, pass `--server-id <SID>`
after the subcommand on every `jf` call, and use one server per request.
**Resolve it now, before any `jf` call:**
```bash
jf config show 2>/dev/null \
| awk '/^Server ID:/{id=$NF} /^Default:[[:space:]]*true/{print id; exit}'
# stdout: the default server-id; if empty, stop and ask which server to use
```
— pass `--server-id <SERVER_ID>` after the subcommand on every `jf` call, and use
one server per request. `<SERVER_ID>` comes from the next bullet: in
this skill it is the AI Governance server, not the jf CLI default
server the base skill uses.
- The stop-on-error rule — on any `jf` failure, stop and never switch servers.

One addition specific to this skill: never `cat` or parse
`~/.jfrog/jfrog-cli.conf.v6` (it can hold access tokens); list servers only
with `jf config show`, which redacts secrets.
- **Agent Guard registry.** Catalog discovery and repo provisioning run through
`npx --yes @jfrog/agent-guard`. `<REGISTRY_URL>` is the npm registry that
provides the `@jfrog/agent-guard` package itself: use `JFROG_AGENT_GUARD_REPO`
if set, otherwise
`https://releases.jfrog.io/artifactory/api/npm/coding-agents-npm/`. Pass the
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.**
It is required for `--list-skills`, `--list-skill-versions`,
`--provision-skills-repository`, `--list-agent-plugins`,
`--list-agent-plugin-versions`, `--provision-agent-plugins-repository`, and
listing AI Catalog policies (`references/listing-policies.md`).
Resolve it with this priority:
1. Parse `~/.jfrog/setup.json` (if present) and read `.servers["<SID>"].currentActiveProject`.
2. Fall back to `$JF_PROJECT`.
3. If still empty, ask the user for the project key - do **not** guess.
- **The AI Governance server and project.** The AI Governance server is the
JFrog Platform server (a jf CLI server ID) that governs the user's AI
assets: its AI Catalog lists the skills, plugins and MCP servers they may
use, and Agent Guard, where the organization has turned it on, enforces
that. The AI Governance project is the JFrog project on that server that
scopes the AI Catalog: which skills, plugins and MCP servers the user sees
and may install. Both are saved in `setup.json` in the JFrog CLI home
directory, separately from the jf CLI default server; the AI Governance
server can be the same server as that default or a different one. The user
chooses both in
`/jfrog-init`; another skill saves one only when it is missing or unclear
and the user answers that skill's question.
Read and change the file only through `jfrog-ai-governance-config.mjs`.

In this skill, flows that need a project (listed below) use the AI
Governance server and project. Flows that need a server but no project use
the AI Governance server; only when no AI Governance server is saved do they
use the jf CLI default server instead. Read both once, before the first
`jf` or Agent Guard call:

```bash
PROJECT=$(jq -r --arg sid "<SID>" '.servers[$sid].currentActiveProject // empty' \
~/.jfrog/setup.json 2>/dev/null)
[ -z "$PROJECT" ] && PROJECT="${JF_PROJECT:-}"
node <skill_path>/scripts/jfrog-ai-governance-config.mjs get
```

`<SERVER_ID>` is the AI Governance server ID that `get` returned (`serverId`), and
`<PROJECT>` is its AI Governance project key (`project`). Flows that need
`<PROJECT>`: browsing or searching skills and plugins, listing versions,
installing (the repository comes from the versions listing), updating a
skill (only from a repository still in the project's `--allowed-only`
listing), listing policies, and publishing with no repository named.
Removing an installed skill or plugin touches local files only: it needs
neither and skips this read and the status handling below. All other
flows need only `<SERVER_ID>`.
Then act on `status`:
- `ok` — continue with `<SERVER_ID>` and `<PROJECT>`.
- `no_project` — the server is set, the project is not (e.g. the user told
`/jfrog-init` they don't use AI Catalog). When the flow needs `<PROJECT>`,
ask: "Which AI Governance project on `<host>` should I use? I need its
project key." (`<host>` is the host of the `jpdUrl` that `get` returned.)
The answer is `<PROJECT>` from now on. Save it by running
`node <skill_path>/scripts/jfrog-ai-governance-config.mjs set "<SERVER_ID>" "<PROJECT>"`.
Never take the key from `JF_PROJECT` or other env vars; they are no longer
used (`get` notes them on stderr).
- `ambiguous` — several servers are saved (e.g. set up for more than one
JFrog platform) and none is marked as the AI Governance server. Run
`node <skill_path>/scripts/jfrog-ai-governance-config.mjs list`, show the
user each `serverId` with its `jpdUrl`, and ask: "Which of these is your AI
Governance server?" Wait for the answer, `<SERVER_ID>`, save it with
`node <skill_path>/scripts/jfrog-ai-governance-config.mjs set "<SERVER_ID>"`,
and run `get` again.
- `missing` — AI Governance is not set up. If the flow needs
`<PROJECT>`, reply with this exact line and stop:
"AI Governance isn't set up. Run `/jfrog-init` to set it up."
When publishing, reply instead: "AI Governance isn't set up. Run
`/jfrog-init` to set it up, or tell me a repository to publish to."
Otherwise `<SERVER_ID>` is the jf CLI default server:

```bash
jf config show 2>/dev/null \
| awk '/^Server ID:/{id=$NF} /^Default:[[:space:]]*true/{print id; exit}'
# stdout: the default server-id; if empty, stop and ask which server to use
```

Then say once: "Using `<SERVER_ID>` from your jf CLI config."
- `corrupt` — `setup.json` can't be read. Ask the user to run
`/jfrog-init` to repair the AI Governance setup, and stop.

If a `jfrog-ai-governance-config.mjs set` command above fails, show the
user its error. For a rejected project key, ask once more; otherwise, or if
the second key is rejected too, ask the user to run `/jfrog-init` to repair
the AI Governance setup, and stop.

When the user names another JFrog server or project, say: "Your AI Governance
server is `<SERVER_ID>` with project `<PROJECT>`. To change it, run
`/jfrog-init`." If they want to change it, stop; the AI Governance server and
project are chosen in `/jfrog-init`, so they run that first.

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
silently correct a display name to a key. If the project key 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/plugin **name** and/or **repo**,
not a project.
`default`, never invent one.
- **Agent Guard registry.** Catalog discovery and repo provisioning run through
`npx --yes @jfrog/agent-guard`. `<REGISTRY_URL>` is the npm registry that
provides the `@jfrog/agent-guard` package itself: use `JFROG_AGENT_GUARD_REPO`
if set, otherwise
`https://releases.jfrog.io/artifactory/api/npm/coding-agents-npm/`. Always pass
the same `<SERVER_ID>` to Agent Guard as `--server "<SERVER_ID>"` so it targets the same
server as your `jf` calls.
- **Bundle manifests differ by type.** Skill bundles require `SKILL.md`
in the bundle root; plugin bundles require `plugin.json`. Validate the
correct file before installing or publishing.
Expand All @@ -106,8 +161,9 @@ flowchart TD
C --> D
D -->|List all skills / versions| E[npx @jfrog/agent-guard --list-skills --allowed-only]
D -->|List policies for skills| M[Resolve project, run list-skill-policies.mjs]
D -->|Install / update skill| F[Resolve slug + version, then jf skills install/update]
D -->|List installed skills / remove| G[jf skills list / rm -rf install dir]
D -->|Install skill| F[Resolve slug + version, then jf skills install]
D -->|Update skill| N[Resolve project, run jfrog-update-skill.mjs]
D -->|List installed skills / remove| G[jf skills list / jfrog-remove-skill.mjs]
D -->|Publish skill| H[Resolve/provision repo, validate bundle, jf skills publish]
D -->|List all plugins / versions| I[npx @jfrog/agent-guard --list-agent-plugins]
D -->|Install / update plugin| J[Resolve slug + version, then jf agent plugins install/update]
Expand Down
10 changes: 5 additions & 5 deletions skills/jfrog-ai-catalog/references/discovering-plugins.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,14 +6,14 @@ List-all and versions go through the **Agent Guard**.

```bash
npx --yes --registry <REGISTRY_URL> @jfrog/agent-guard \
--list-agent-plugins --project "<PROJECT>" [--name <PATTERN>] [--server "<SID>"] [--page-size <N>] [--cursor <C>] [--format json]
--list-agent-plugins --project "<PROJECT>" [--name <PATTERN>] --server "<SERVER_ID>" [--page-size <N>] [--cursor <C>] [--format json]
```

| Flag | Required | Purpose |
|------|----------|---------|
| `--project <PROJECT>` | **Yes** | AI Catalog project to list. |
| `--project <PROJECT>` | **Yes** | AI Governance project to list. |
| `--name <PATTERN>` | No | Find plugins by name: server-side, case-insensitive substring, scoped to the project. |
| `--server <SID>` | No | jf CLI config entry to authenticate with (defaults to the resolved single server). |
| `--server <SERVER_ID>` | **Yes** | The AI Governance server (its jf CLI server ID). |
| `--page-size <N>` | No | Results per page. Pass `50` to stay bounded. The Agent Guard defaults to 500 if omitted. |
| `--cursor <C>` | No | Continuation cursor from a previous page's JSON, to fetch the next page. |
| `--format json` | No | Raw page JSON instead of the default compact TSV (name + last-updated). |
Expand Down Expand Up @@ -45,7 +45,7 @@ repo-scoped (Artifactory registry contents), unlike `--list-agent-plugins`, whic
project-scoped:

```bash
jf agent plugins list --repo "<repo>" --server-id "<SID>" --format json
jf agent plugins list --repo "<repo>" --server-id "<SERVER_ID>" --format json
```

Never run a bare `jf agent plugins list` (it errors): always pass `--repo <key>` here, or
Expand All @@ -70,7 +70,7 @@ line instead:

```bash
npx --yes --registry <REGISTRY_URL> @jfrog/agent-guard \
--list-agent-plugin-versions --project "<PROJECT>" --agent-plugin "<slug>" [--server "<SID>"] [--page-size <N>] [--cursor <C>] [--format json]
--list-agent-plugin-versions --project "<PROJECT>" --agent-plugin "<slug>" --server "<SERVER_ID>" [--page-size <N>] [--cursor <C>] [--format json]
# JSON: versions[].version, versions[].locations[].repoKey (page through with cursor like above)
```

Expand Down
10 changes: 5 additions & 5 deletions skills/jfrog-ai-catalog/references/discovering-skills.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,15 +13,15 @@ path — see *List a repo's skills* for when it's appropriate to use.

```bash
npx --yes --registry <REGISTRY_URL> @jfrog/agent-guard \
--list-skills --project "<PROJECT>" --allowed-only [--name <PATTERN>] [--server "<SID>"] [--page-size <N>] [--cursor <C>] --format json
--list-skills --project "<PROJECT>" --allowed-only [--name <PATTERN>] --server "<SERVER_ID>" [--page-size <N>] [--cursor <C>] --format json
```

| Flag | Required | Purpose |
|------|----------|---------|
| `--project <PROJECT>` | **Yes** | AI Catalog project to list. |
| `--project <PROJECT>` | **Yes** | AI Governance project to list. |
| `--allowed-only` | **Yes** | Limit results to skills allowed by project policy. Never omit it. |
| `--name <PATTERN>` | No | Find skills by name: server-side, case-insensitive substring, scoped to the project. |
| `--server <SID>` | No | jf CLI config entry to authenticate with (defaults to the resolved single server). |
| `--server <SERVER_ID>` | **Yes** | The AI Governance server (its jf CLI server ID). |
| `--page-size <N>` | No | Results per page. Pass `50` to stay bounded. The Agent Guard defaults to 500 if omitted. |
| `--cursor <C>` | No | Continuation cursor from a previous page's JSON, to fetch the next page. |
| `--format json` | **Yes** | Raw page JSON used to render the result. |
Expand Down Expand Up @@ -70,7 +70,7 @@ repo-scoped (Artifactory registry contents), unlike `--list-skills`, which is
project-scoped:

```bash
jf skills list --repo "<repo>" --server-id "<SID>" --format json
jf skills list --repo "<repo>" --server-id "<SERVER_ID>" --format json
```

Never run a bare `jf skills list` (it errors): always pass `--repo <key>` here, or
Expand Down Expand Up @@ -104,7 +104,7 @@ same result" means the one fully-paged, merged result, not a single HTTP call.

```bash
npx --yes --registry <REGISTRY_URL> @jfrog/agent-guard \
--list-skill-versions --project "<PROJECT>" --skill "<slug>" --allowed-only [--server "<SID>"] [--cursor <C>] --format json
--list-skill-versions --project "<PROJECT>" --skill "<slug>" --allowed-only --server "<SERVER_ID>" [--cursor <C>] --format json
# JSON: versions[].version, versions[].locations[].repoKey, versions[].locations[].allowStatus, exhausted, cursor
```

Expand Down
16 changes: 8 additions & 8 deletions skills/jfrog-ai-catalog/references/installing-plugins.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,11 +13,11 @@ Install by **slug** (the registry `slug`/`name`, never a display name). Latest
version is used by default, and the user may pass an explicit version.
**The `jf agent plugins install` command takes no project.** Resolving which repo hosts
the slug uses `--list-agent-plugin-versions` (below), which does require `--project`, so
use `<PROJECT>` resolved at session start (see SKILL.md Prerequisites).
use the AI Governance project `<PROJECT>` (see SKILL.md Prerequisites).

```bash
jf agent plugins install "<slug>" \
--server-id "<SID>" \
--server-id "<SERVER_ID>" \
--version "latest" \
--repo "<repo>" \
--harness "<harness>" \
Expand Down Expand Up @@ -63,7 +63,7 @@ up where the slug is hosted with the Agent Guard:

```bash
npx --yes --registry <REGISTRY_URL> @jfrog/agent-guard \
--list-agent-plugin-versions --project "<PROJECT>" --agent-plugin "<slug>" [--server "<SID>"] --format json
--list-agent-plugin-versions --project "<PROJECT>" --agent-plugin "<slug>" --server "<SERVER_ID>" --format json
# read versions[].version and versions[].locations[].repoKey
```

Expand Down Expand Up @@ -98,7 +98,7 @@ After install, confirm the slug shows up as installed — don't guess where
the source of truth for what's actually installed:

```bash
jf agent plugins list --server-id "<SID>" --harness "<harness>" --format json \
jf agent plugins list --server-id "<SERVER_ID>" --harness "<harness>" --format json \
| jq -e --arg slug "<slug>" '.[] | select(.name == $slug)' >/dev/null \
&& echo "installed" || echo "MISSING from installed list"
```
Expand All @@ -116,13 +116,13 @@ To upgrade an installed plugin to a newer version, use the CLI (it re-downloads
and reinstalls in place):

```bash
jf agent plugins update --slug "<slug>" --server-id "<SID>" --harness "<harness>" --version "latest" --quiet
jf agent plugins update --slug "<slug>" --server-id "<SERVER_ID>" --harness "<harness>" --version "latest" --quiet
# Preview without touching Artifactory:
jf agent plugins update --slug "<slug>" --server-id "<SID>" --harness "<harness>" --dry-run
jf agent plugins update --slug "<slug>" --server-id "<SERVER_ID>" --harness "<harness>" --dry-run
# Reinstall even if already at the target version:
jf agent plugins update --slug "<slug>" --server-id "<SID>" --harness "<harness>" --force --quiet
jf agent plugins update --slug "<slug>" --server-id "<SERVER_ID>" --harness "<harness>" --force --quiet
# Update all installed plugins at once:
jf agent plugins update --all --server-id "<SID>" --harness "<harness>" --quiet
jf agent plugins update --all --server-id "<SERVER_ID>" --harness "<harness>" --quiet
```

Note: unlike `jf skills update`, the slug is passed as `--slug <slug>` (a named
Expand Down
Loading
Loading