Skip to content
Merged
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
8 changes: 5 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,15 @@ load time, so JFrog capabilities are available to the agent out of the box.

## What's included

The plugin bundles two canonical skills, vendored (pinned) from
The plugin bundles three canonical skills, vendored (pinned) from
Comment thread
yanivt-jfrog marked this conversation as resolved.
[`jfrog/jfrog-skills`](https://github.com/jfrog/jfrog-skills) and committed under `skills/`:

- **`jfrog`** — interact with the JFrog Platform via the JFrog CLI, MCP server, and REST/GraphQL APIs
(Artifactory, Xray, builds, permissions, projects, release lifecycle, advanced security, and more).
- **`jfrog-package-safety-and-download`** — check package safety/curation status and download packages
through JFrog.
- **`jfrog-ai-catalog-skills`** — discover, install, manage, and publish agent skills hosted in the
JFrog AI Catalog via the JFrog CLI (`jf skills`) and JFrog Agent Guard.

The skills ship **with the plugin** (vendored and pinned). They are **not** downloaded at runtime, so
the plugin works offline and the skill set is reproducible for a given plugin version.
Expand Down Expand Up @@ -128,9 +130,9 @@ connection status is surfaced by OpenCode itself — this plugin only registers

This release changes behavior in ways that are **not** backward compatible:

- **Skill catalog changed (7 → 2).** The previous Artifactory skills — `skill-install`,
- **Skill catalog changed (7 → 3).** The previous Artifactory skills — `skill-install`,
`skill-publish`, `jfrog-cli`, `opencode-jfrog-mcp`, `jfrog-setup-package-managers`, `jfrog-curation`,
`jfrog-packages` — are replaced by the two canonical skills above. Invocations of the removed skill
`jfrog-packages` — are replaced by the three canonical skills above. Invocations of the removed skill
names no longer exist; that functionality now folds into the `jfrog` skill.
- **Package-manager auto-setup was removed.** Earlier versions ran `jf setup <pm>` automatically on
session start. That is gone; the plugin now emits an interim one-line nudge to run
Expand Down
4 changes: 2 additions & 2 deletions VENDOR.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,15 +15,15 @@ The vendoring source is declared in `sync-skills-vendor.json` at the repo root:
```json
{
"repo": "jfrog/jfrog-skills",
"pin": "v0.14.0",
"pin": "v0.16.0",
"paths": ["skills"]
}
```

| Field | Meaning |
| ------- | ------------------------------------------------------------------------------------------- |
| `repo` | The upstream GitHub repository (`owner/name`) to vendor from. |
| `pin` | The exact upstream ref to vendor (a tag, e.g. `v0.14.0`). Pin to a tag for reproducibility. |
| `pin` | The exact upstream ref to vendor (a tag, e.g. `v0.16.0`). Pin to a tag for reproducibility. |
| `paths` | The paths within the upstream repo to copy into this repo root. Currently just `skills`. |

## How the sync works
Expand Down
105 changes: 105 additions & 0 deletions skills/jfrog-ai-catalog-skills/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,105 @@
---
name: jfrog-ai-catalog-skills
description: >-
Discover, install, manage, and publish agent skills hosted in the JFrog AI
Catalog (Artifactory skills repositories) using the JFrog CLI (`jf skills`)
and the JFrog Agent Guard. Lists and searches available skills (catalog-wide
or scoped to a project), shows a skill's versions and which repos host it,
installs the latest or a pinned version, verifies the install, lists
installed skills, updates and removes them, and publishes (uploads) a local
skill bundle and releases new versions.
Use when the user asks what skills are available or installed, to
search/browse the catalog, to install/update/uninstall a skill, to see a
skill's versions, or to publish/upload/release a skill to JFrog /
Artifactory / the AI Catalog.
metadata:
role: workflow
---

# JFrog AI Catalog Skills

Discover, install, and manage agent skills from the JFrog AI Catalog
(Artifactory skills repositories), and publish your own skills back to it, all
through the JFrog CLI (`jf skills`) and the JFrog Agent Guard.

## Choose a reference file

Pick the row matching the user's intent and read that reference file.

| Intent | Read |
|--------|------|
| "What skills are available?" / browse the catalog / list versions / search by name | [references/discovering-skills.md](references/discovering-skills.md) |
| Install or update a skill (latest or a pinned version), or a download is blocked | [references/installing-skills.md](references/installing-skills.md) |
| "What's installed?" / remove an installed skill | [references/managing-installed-skills.md](references/managing-installed-skills.md) |
| Publish / upload / release a skill to the catalog | [references/publishing-skills.md](references/publishing-skills.md) |

## Prerequisites

- **Read the base `jfrog` skill first.** [`../jfrog/SKILL.md`](../jfrog/SKILL.md)
owns the shared guards this skill depends on, so this skill does **not** repeat
them — follow them there:
- 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.
- 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, 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
an explicit `--repo` are keyed by skill **name** and/or **repo**, not a
project.

## Workflow overview

```mermaid
flowchart TD
A[User request] --> B{jf CLI installed?}
B -->|No| C[Ask user to install jf CLI, then continue]
B -->|Yes| D{Intent}
C --> D
D -->|List all / versions| E[npx @jfrog/agent-guard --list-skills]
D -->|Install / update| F[Resolve slug + version, then jf skills install/update]
D -->|List installed / remove| G[jf skills list / rm -rf install dir]
D -->|Publish| H[Resolve/provision repo, validate bundle, jf skills publish]
```

## Gotchas

Catalog-specific rules only. The shared `jf` guards — single server per request,
stop-on-error, and cautious mutation — live in the base
[`jfrog` skill](../jfrog/SKILL.md); follow those too. Flow-specific rules live in
the reference files above.

- **Which operations mutate**: install and list are read-mostly; remove, registry
delete, and publish mutate state — the base skill's cautious-mutation rule
applies to those three.
- **Session pickup**: installs, updates, and removals usually take effect only at
the next agent session start, so tell the user to restart.
- **Don't leak the plumbing**: present skills/versions/repos to the user, never
the `npx`/Agent Guard commands, `--registry`, flags, or cursors. Run follow-ups
yourself.
- **Use the response templates verbatim**: where a reference file gives a "reply
using this exact template" block, fill the placeholders and send exactly that,
with the same wording every time and no extra preamble or commentary.
83 changes: 83 additions & 0 deletions skills/jfrog-ai-catalog-skills/references/discovering-skills.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,83 @@
# Discovering skills

List-all and versions go through the **Agent Guard**.

## List skills (page through the catalog)

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

| Flag | Required | Purpose |
|------|----------|---------|
| `--project <PROJECT>` | **Yes** | AI Catalog project to list. |
| `--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). |
| `--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). |

Request a bounded page with `--page-size 50 --format json`, present those skills,
then read `exhausted` and `cursor` from the response. If `exhausted` is `false`
there are more. Tell the user and offer to fetch the next page with
`--cursor <cursor>`. Do not silently page through the whole catalog.

**Presenting results (use this exact format).** Render the skills as this table,
sorted by name, and nothing else (no commands, URLs, flags, or cursors):

| Skill | Last updated |
|-------|-------------|
| `<name>` | `<lastUpdated>` |

For a `--name` search with no matches, reply with one line instead:

> No skills match "`<query>`".

To offer a follow-up (a skill's versions or repos), ask in plain language
("want the versions for one of these?") and run the command yourself.

## List a repo's skills

To see what is published in one specific skills repository (for example, to check
a repo before or after publishing to it), list it directly with the CLI. This is
repo-scoped (Artifactory registry contents), unlike `--list-skills`, which is
project-scoped:

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

Never run a bare `jf skills list` (it errors): always pass `--repo <key>` here, or
`--harness <h>` for installed skills (see `managing-installed-skills.md`).

**Presenting results (use this exact format).** Render the skills as this table,
sorted by name, and nothing else (no commands, URLs, or flags):

Skills in `<repo>`:

| Skill | Version | Description |
|-------|---------|-------------|
| `<name>` | `<version>` | `<description>` |

Include the **Description** column only when the listing provides one (drop it if
every skill's description is empty). If the repo holds no skills, reply with one
line instead:

> No skills published in `<repo>`.

## A skill's versions and hosting repos

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

**Presenting versions (use this exact format).** Newest version first:

Versions of `<slug>`:

| Version | Hosted in |
|---------|-----------|
| `<version>` | `<repoKey>`[, `<repoKey>`…] |
Loading
Loading