Catalog API, MCP server and CLI

Overview

• npx skillfoxx: an installer that puts a catalog entry into your agents and keeps a lock file.
• The MCP server at https://skillfoxx.ru/api/mcp: search, entry cards, install plans per agent, project matching as in Match with Foxx AI.
• The REST API at /api/v1: entry lists, search, install recipes, project matching and file validation.
• Install recipes signed with Ed25519, and their JSON schema.
• The /catalog.json export under CC BY 4.0.
• Files for agents: /llms.txt, /server.json, /.well-known/mcp.json.

Every response is UTF-8 JSON. Catalog sections in paths and parameters: skills, mcp, cli, plugins, workflows, prompts.

CLI: npx skillfoxx

The installer puts catalog entries into the agents on your machine. The skillfoxx package is on npm under the MIT license and needs Node.js 18.18 or newer.

npx skillfoxx add mcp/vv-mcp-server

npx skillfoxx search postgres
npx skillfoxx list
npx skillfoxx doctor
npx skillfoxx update
npx skillfoxx remove mcp/vv-mcp-server

Source code, build and network

• The CLI source code is open: https://github.com/SkillFoxx-CLI/cli, MIT license. The npm bundle is not minified, so you can read it before running.
• GitHub Actions builds the npm package from this repository and signs the build provenance (SLSA): the package page shows which commit it came from. The owner approves every version with two-factor authentication.
• The CLI only talks to skillfoxx.ru (the signed entry recipe and the install counter), api.github.com and raw.githubusercontent.com (skill files at a pinned commit).
• The install counter is anonymous: entry, agent, event, CLI version, a random ID and a CI flag. No paths, environment variables or user names. Disable it with DO_NOT_TRACK=1.

• Source code on GitHub
• The skillfoxx package on npm

Commands

Options

Where the CLI writes

The CLI puts skill files into .agents/skills/<name> (~/.agents/skills for the user) and links them into each agent folder with a symbolic link. If it cannot create the link, it copies the folder. Where the table says none, the CLI prints instructions instead of editing a file.

What the CLI checks before installing

• The recipe signature, against keys built into the CLI. The CLI rejects a recipe with no signature, an unknown key, another entry or an issue time more than 24 hours ago.
• Skill files come from GitHub at the pinned commit, and the CLI checks the sha of every file and the overall digest.
• An entry that was removed or has an open incident does not install, exit code 3. No recipe or status unsupported: exit code 4.
• Broad access needs consent: a question in the terminal or the --yes flag. Without a terminal and without --yes the CLI exits with code 5.
• Recipes with status ai or review install with a warning.
• If node, python3, uvx or docker is missing, the CLI warns that the server will not start without it and goes on.

Configs, secrets and backups

• The CLI edits one config key at a time: comments, indentation and other servers stay where they are.
• Before an edit the CLI saves a copy to ~/.skillfoxx/backups and keeps the last 20 sets. An error or Ctrl+C rolls the install back.
• A secret never goes into a project file. The CLI writes a reference to an environment variable when the agent understands one (Claude Code, Gemini CLI, Cursor, VS Code, Zoo Code, OpenCode), otherwise it prints instructions.
• For the user the CLI writes the secret value into the agent config with mode 600, the way the agents do it themselves. The lock file never holds secret values.
• The CLI does not install Claude Code plugins itself: it prints the /plugin commands for the chat. It installs CLI tools with npm, pip, brew, cargo or go after you confirm.

Lock files and language

skillfoxx-lock.json in the project root (worth committing) and ~/.skillfoxx/lock.json for the user store the entry, recipe hash, commit, status, risk, agents, paths and dates. Set SKILLFOXX_HOME to move the ~/.skillfoxx folder.

The CLI takes the output language from LC_ALL, LC_MESSAGES or LANG, then from the system language (AppleLanguages on macOS). If it cannot tell, it prints Russian. The --lang flag sets the language explicitly.

Exit codes

Telemetry

After add, update and remove the CLI sends POST /api/v1/installs with the entry, agent, event, CLI version, a CI flag and a random install id from ~/.skillfoxx/config.json. Paths, variables and the user name are never sent. Disable it with DO_NOT_TRACK=1, DISABLE_TELEMETRY=1 or SKILLFOXX_TELEMETRY=0.

These events feed the install counter on each card: distinct devices in 30 days, add events only, CI runs excluded. The number appears from 10 installs. The server deletes events older than 90 days.

MCP server

Address https://skillfoxx.ru/api/mcp, streamable HTTP transport without sessions, JSON responses. No key, up to 120 requests per minute per IP address.

Only report_install writes to the database: it adds an anonymous event to the install counter. The other tools only read the catalog.

claude mcp add --transport http skillfoxx https://skillfoxx.ru/api/mcp

{
  "mcpServers": {
    "skillfoxx": {
      "url": "https://skillfoxx.ru/api/mcp"
    }
  }
}

{
  "servers": {
    "skillfoxx": {
      "type": "http",
      "url": "https://skillfoxx.ru/api/mcp"
    }
  }
}

[mcp_servers.skillfoxx]
url = "https://skillfoxx.ru/api/mcp"

Tools

lang takes ru or en, default ru. section: skills, mcp, cli, plugins, workflows, prompts. agent in plan_install: claude-code, cursor, vscode, codex, gemini-cli, devin, cline, zoo-code, opencode, zed, sourcecraft, coddy, antigravity, kiro; the spellings vs-code, github-copilot, windsurf, roo-code and gemini work too. If the entry has no recipe for that agent, you get agent_not_supported with the supported list. If there is no recipe at all, plan is null and message says why.

Reporting an install

• The agent calls plan_install, asks the user, installs the entry and calls report_install with the reportToken only after the install succeeded.
• The token lives 2 hours and is bound to the entry and the IP address. One address counts one MCP install of an entry per day.
• If you installed with npx skillfoxx, skip report_install: the CLI reports by itself. If the user opted out of statistics, do not call it.

Send recommend_for_project a summary of the project, never code or secrets. The server passes that text to OpenAI for semantic matching and does not store it.

REST API

Base URL https://skillfoxx.ru/api/v1. No key. Limits count per IP address per minute, and going over returns 429.

GET /api/v1/entries

Published entries, 50 per page. Order as in the catalog: editors’ picks first, then repository ★, then publish date.

Response: page, totalPages, totalDocs and entries with id, type, slug, title, titleOriginal, tagline, url, source, riskLevel, isRuStack, stars (repository ★), license, install (method and command). Cached for 5 minutes, CORS open.

curl 'https://skillfoxx.ru/api/v1/entries?lang=en&section=mcp&ru=1&page=1'

GET /api/v1/search

Search over published entries. q from 2 to 120 characters, lang, limit up to 50 (default 12). The response is {"hits": [...]} with id, title, titleOriginal, tagline, type, href. href is relative and has no language prefix. When few entries match the words, search adds entries by meaning through OpenAI embeddings. Cached for 1 minute. This address sends no CORS header, so call it from your own server when you need it in a browser.

curl 'https://skillfoxx.ru/api/v1/search?q=postgres&lang=en&limit=5'

GET /api/v1/recipe/<slug>

Finds the sections that have this slug: {"matches": [{"section", "slug", "title"}]}. npx skillfoxx add <slug> uses it. The recipe itself comes from the address with a section, described below.

curl https://skillfoxx.ru/api/v1/recipe/vv-mcp-server

POST /api/v1/scan

Project matching, as on the Match with Foxx AI page (/scan). Body {"input": "...", "lang": "en"}, input from 3 to 50,000 characters: a task description or a package.json. Response: answer (model text), sources (entries with href and what matched) and mode (project or question). The input goes to OpenAI. Up to 20 requests per minute. A 429 with {"error": "quota"} means requests for today are used up; with "needLogin": true you can continue after signing in with Yandex ID.

curl -X POST https://skillfoxx.ru/api/v1/scan \
  -H 'content-type: application/json' \
  -d '{"input": "Next.js online store with Stripe payments", "lang": "en"}'

POST /api/v1/validate

File validation, as on the /validator page. Body {"content": "...", "format": "skill_md"}. format: skill_md, plugin_json, server_json, agents_md or cursor_mdc; without it the server detects the format. content up to 200,000 characters. Up to 60 requests per minute.

POST /api/v1/installs

An internal address for CLI events. The server accepts only requests with the User-Agent skillfoxx-cli/<version>; everything else gets 202 and nothing is recorded. Your own integration should use report_install in MCP to feed the counter.

Install recipes and signatures

A recipe says what gets installed (a skill, MCP server, plugin, CLI or rules), from which commit and which variables it needs. The methodology page explains how we build and recheck recipes.

curl -i https://skillfoxx.ru/api/v1/recipe/mcp/vv-mcp-server

Response: entry (slug, type, section, url, canonicalSource), recipe (an object per the schema, or null), status, reason (only for unsupported and review), risk (level and reasons), officialVendor, checkedAt, hash, blocked (an open incident of severity high or critical, otherwise null) and issuedAt. The URL and reasons come from the Russian card. Cached for 5 minutes, ETag and 304 on If-None-Match, up to 60 requests per minute, 404 for an entry that is not in the catalog.

• Recipe JSON schema

Statuses

Ed25519 signature

Every recipe response is signed. The x-skillfoxx-signature header looks like v1;kid=<key>;sig=<base64url signature>. The signed message is the string skillfoxx-recipe-v1, a newline and the exact response body bytes.

Public keys (SPKI DER, base64) live at /.well-known/skillfoxx-recipe-keys.json, and the CLI ships the same list. Under the rotation plan a new key appears in the list 30 days before the server switches, and the old one goes away 30 days after.

// verify.mjs, Node.js 18+: node verify.mjs
import { createPublicKey, verify } from 'node:crypto'

const base = 'https://skillfoxx.ru'
const { keys } = await (await fetch(`${base}/.well-known/skillfoxx-recipe-keys.json`)).json()
const res = await fetch(`${base}/api/v1/recipe/mcp/vv-mcp-server`)
const body = await res.text()
const [, kid, sig] = /^v1;kid=(sf-[0-9a-f]{8});sig=([A-Za-z0-9_-]+)$/.exec(res.headers.get('x-skillfoxx-signature'))
const key = createPublicKey({ key: Buffer.from(keys.find((k) => k.kid === kid).publicKey, 'base64'), format: 'der', type: 'spki' })
console.log(kid, verify(null, Buffer.from('skillfoxx-recipe-v1\n' + body), key, Buffer.from(sig, 'base64url')))

Verify the signature before parsing the JSON, and check that entry.section and entry.slug match your request. The CLI also rejects a response whose issuedAt is older than 24 hours.

• Signing public keys

Catalog export

Every published entry in one file: /catalog.json with Russian texts and /catalog.en.json with English ones (Russian where a translation is missing). The server builds the file on request and keeps it in memory for up to an hour.

Top level: version, generatedAt, lang, license (name, url, attribution, scope), count and entries. Entry fields: slug, section, type, title, titleOriginal, tagline, url, canonicalSource, source, risk, officialVendor, recipe, recipeStatus, recipeCheckedAt, recipeHash, updatedAt.

Cached for an hour, ETag and 304 on If-None-Match, a Link header with rel="license". Up to 20 requests per minute. If the database is down the server serves the previous version, or 503 with Retry-After when it has none.

curl -O https://skillfoxx.ru/catalog.en.json

curl -s https://skillfoxx.ru/catalog.en.json | jq -r '.entries[] | select(.recipeStatus == "auto") | .url'

• /catalog.json
• /catalog.en.json

llms.txt and files for agents

• /llms.txt
• /server.json
• /.well-known/mcp.json
• /rss.xml

Limits and caching

Per-minute limits live in server memory. For a full copy of the catalog take catalog.json instead of crawling pages: it is faster for you and lighter for the site.

Licenses

• SkillFoxx texts and metadata in the API, MCP and export are available under CC BY 4.0. Credit SkillFoxx (skillfoxx.ru) with a link.
• Entry code belongs to its authors under their own licenses. Responses and the export never include it, only links to the original source.
• The skillfoxx CLI is MIT licensed. Licenses of bundled libraries are in THIRD_PARTY_LICENSES.txt inside the package.
• Stars and licenses of entries come from GitHub and describe the whole repository.

Contact

Report a mistake in an entry or recipe with the “Report a problem” button on the entry page. Suggest your own skill or server through the submission form. API and CLI news goes to the @skillfoxxru Telegram channel.

• Submit an entry
• How we select and check entries
• Terms of use
• Privacy policy