Publish Skills

Publish a repo of agent skills (the open SKILL.md format) to the agent-skills marketplaces. The repo is the unit of publishing: make it public, validate, cut a release, and the auto-indexers (skills.sh, SkillsMP, claudeskills.info) pick it up. Then optionally wire the Claude /plugin marketplace and submit to the curated stores.

Golden rule: security first. These repos often carry a local App-in-Skill with real data (emails, ledgers, tokens). Never publish it. Confirm private data is gitignored and scan tracked files before anything goes public.

Run steps in order. Stop and surface anything a step can't resolve safely.

Step 1 — Security scan (blocking)

Publishing is outward-facing and hard to reverse. Verify BEFORE any push/release.

# 1a. Private runtime state must be gitignored, never tracked
grep -nE '\.data/|\.cache/|config\.local|\.env|exports/' .gitignore    # expect these ignored
git ls-files | grep -iE '\.data/|\.cache/|config\.local|\.env|\.pem|\.key' && echo "!!! TRACKED PRIVATE FILE — stop" || echo "clean: no private files tracked"

# 1b. Scan tracked files for real secrets / PII (tune patterns per repo)
git ls-files | while read f; do
  grep -HnaiE '(sk_live|sk_test|pk_live|bearer [A-Za-z0-9]|-----BEGIN|api[_-]?key["'"'"' :=]+[A-Za-z0-9]{16})' "$f" 2>/dev/null
done | grep -vE 'example\.com|_env"|password_env|api_key_env|REPLACE_WITH' | head

• Config templates must use example.com, Your Name, and *_env references — never real hosts, addresses, or key values.
• Third-party skills the user installed (e.g. a tracked .agents/skills/<other>/) must NOT be republished — untrack + gitignore them:

git rm -r --cached .agents && printf '\n.agents/skills/\n' >> .gitignore

Only proceed when 1a and 1b are clean.

Step 2 — Validate & fix (gh skill)

GitHub's official tooling validates against the agentskills.io spec and discovers skills//SKILL.md, /SKILL.md, and plugins/{scope}/skills/*/SKILL.md.

gh skill publish --dry-run          # validates ALL skills; one error blocks the whole release

Common fixes:

• Invalid frontmatter YAML (mapping values are not allowed…): a description contains an unquoted colon: space. Wrap the whole description value in double quotes.
• name ≠ directory name: rename so name: matches the folder.
• Missing license: add a root LICENSE (MIT is typical) and license: MIT to each skill's frontmatter.
• Body > 500 lines (context-efficiency warning): move large blocks (JSON schemas, long examples) into references/*.md and leave a one-line pointer.
• Install metadata present (metadata.github-*): gh skill publish --fix strips it; review, then commit.

Re-run --dry-run until it prints ok (a lone tag-protection warning is fine here — handled in Step 5).

Step 3 — Publish (public repo + release)

# Ensure the repo is public (auto-indexers only see public repos)
gh repo view <owner>/<repo> --json visibility,isPrivate

# Discovery topics — feed SkillsMP / claudeskills.info / GitHub search
gh repo edit <owner>/<repo> --add-topic agent-skills --add-topic claude-skills \
  --add-topic codex-skills --add-topic skill-md --add-topic ai-agents

# Commit any pending clean changes, then cut a release
git add -A && git commit -m "Publish skills" && git push
gh skill publish --tag vX.Y.Z        # creates the GitHub release the ecosystem recognizes

After this: npx skills add <owner>/<repo> and gh skill install <owner>/<repo> both work; gh skill search <name> confirms indexing (may take minutes-to-days).

Step 4 — Claude Code /plugin marketplace

Expose the same skills to Anthropic's /plugin system WITHOUT restructuring the flat skills/*/ layout: one bundle plugin whose source is the repo root and whose skills array points at each skill dir (strict: false). Write .claude-plugin/marketplace.json:

{
  "name": "<owner>-skills",
  "owner": { "name": "<Full Name>", "url": "https://github.com/<owner>" },
  "metadata": { "description": "…", "version": "X.Y.Z" },
  "plugins": [
    {
      "name": "<owner>-skills",
      "description": "…",
      "version": "X.Y.Z",
      "license": "MIT",
      "category": "productivity",
      "tags": ["agent-skills"],
      "source": "./",
      "strict": false,
      "skills": ["./skills/skill-a", "./skills/skill-b"]
    }
  ]
}

Validate JSON, then document in the README:

/plugin marketplace add <owner>/<repo>
/plugin install <owner>-skills

Keep the plugin name stable across releases so existing users don't break. This adds only the manifest — it does not create a plugins/ dir, so it won't collide with gh skill discovery.

Step 5 — Tag protection (immutable releases)

Marketplaces trust releases that can't be rewritten. Create a ruleset targeting tags with Restrict updates + Restrict deletions (GitHub UI: Settings › Rules › Rulesets › New ruleset → Target: Tags → pattern v*). Verify:

gh api repos/<owner>/<repo>/rulesets --jq '.[] | "\(.name): \(.enforcement) [\(.target)]"'   # want: active [tag]
gh skill publish --dry-run    # the tag-protection warning should be gone (prints `ok`)

Enforcement must be active (a disabled ruleset still warns).

Step 6 — Curated / manual marketplaces (need the user's login)

These can't be fully automated — prepare the artifacts, hand off the click.

Agensi (agensi.io, curated, ~70% creator revenue): build a clean zip per skill from tracked files only (never the working tree — avoids private .data/):

mkdir -p dist/agensi
git archive --format=zip --prefix=<skill>/ -o dist/agensi/<skill>.zip HEAD:skills/<skill>
unzip -Z1 dist/agensi/<skill>.zip | grep -iE '\.data/|\.cache/|\.env' && echo "!!! sensitive" || echo clean

Then the user: sign up → connect Stripe Connect → Creator Dashboard → Submit a Skill → upload zip → price → passes 8-point security scan.

Buda Marketplace (buda.im/docs/sell-skills, monetized, GitHub-App based — no zip, reads the repo directly). Uses this repo's existing skills//SKILL.md layout as-is (also lists agents//AGENTS.md and teams/*/TEAM.md); each SKILL.md needs only name + description frontmatter, which become the listing. The user:

1. Developer Portal → Plugin Repos → Connect GitHub → install the Buda GitHub App, granting the repo (private is fine; Buda asks only Contents: Read-only and never stores source).
2. Add Repository → pick from dropdown → Buda scans and populates My Listings as pending.
3. Per listing set Pricing tier (free / one-time / subscription) and the Publish toggle.
4. Review is brief — usually approved within ~24h (pending → published). Push changes, then click Sync to update all listings; users get the latest on next install. Payouts are monthly, less Buda's platform fee.

OpenClaw ClawHub (clawhub.ai): community listing — submit the public repo URL.

Codex / OpenAI (openai/plugins, curated, PR-based): the old openai/skills is deprecated. Fork openai/plugins, add plugins/<name>/.codex-plugin/plugin.json + skills/<name>/SKILL.md (match an existing plugin's manifest, e.g. build-web-apps), push a branch to the fork. OpenAI restricts PR creation from external accounts (GraphQL/REST 403→404), so don't try to open it programmatically — hand the user a one-click compare URL: https://github.com/openai/plugins/compare/main...<owner>:plugins:<branch>?expand=1

Step 7 — MCP servers → registries & directories (only if you ship an MCP server)

Steps 1-6 publish a SKILL.md repo. If what you're shipping also exposes an MCP server (e.g. an app's /api/mcp), it has its own channels. busabase/skills is the reference — one repo feeds skills + Claude Code + Codex marketplaces + the MCP Registry. Templates (server.json, .mcp.json, .codex-plugin/plugin.json, .mcpb manifest) and the full per-channel review checklists live in [references/mcp-and-directories.md](./references/mcp-and-directories.md).

Zero-review — do now:

• Official MCP Registry (registry.modelcontextprotocol.io) — a metadata catalog pointing at your

hosted server/package. Add a server.json, then: ``bash brew install mcp-publisher mcp-publisher login github # → io.github.<user>/ (own the repo) # or: mcp-publisher login dns --domain <domain> --private-key <KEY> # → com.<domain>/ mcp-publisher publish # validates + publishes; live instantly, reactive moderation only ` Versions are immutable — bump version to update. Automate on v* tags with login github-oidc`.

• Codex marketplace — codex plugin marketplace add <owner>/<repo> (self-serve, zero-review; an

alternative to the openai/plugins PR route in Step 6). Verified layout (Codex is strict): the marketplace file must be .agents/plugins/marketplace.json, and each plugin a subdir plugins/<name>/ (source.path: "./plugins/<name>") holding its own .codex-plugin/plugin.json ("skills": "./skills/"). On install Codex bundles only files inside the plugin subdir — symlinks and ../ escapes are silently dropped — so the skill must be a real copy at plugins/<name>/skills/<name>/SKILL.md, synced from the canonical skills/<name>/. A root-level marketplace.json or root .codex-plugin/ does not resolve. (Codex .mcp.json also differs from Claude Code's — see below.) Full templates in the references file.

• Claude Code — already wired in Step 4; its /plugin also carries a bundled MCP via .mcp.json.

Review-gated — second wave (worth it once the product has a public HTTPS MCP server + OAuth + a privacy policy). Prep the checklist in the references file, then hand off the submit:

• ChatGPT App Directory (Apps SDK) — MCP-server-as-app; identity verification + working demo login

with sample data (signup-to-test = rejected) + stability. Submit in the OpenAI Developer Platform.

• Anthropic Connectors directory — remote MCP; Team/Enterprise org, 11-step form, privacy policy

mandatory (missing = instant reject), must own the API/domain, tools need readOnlyHint/destructiveHint.

• Anthropic Desktop Extensions — .mcpb bundle (mcpb init → mcpb pack), test on Windows + macOS.

Distribution cheat-sheet

Notes

• The whole repo publishes together — gh skill publish fails if ANY skill has an error, so keep every skill valid.
• Bump the release tag on every publish so indexers and /plugin users get the update.
• This skill can publish the repo it lives in (dogfood): run Steps 1-5 against <owner>/<repo> = this repo.
• Steps 1-6 are the SKILL.md-repo track; Step 7 is a separate MCP-server track — do it only when an MCP server is part of what you ship. The four zero-review channels (skills index, Claude Code, Codex, MCP Registry) ship today; the human-reviewed directories are a deliberate second wave.
• Never hand-maintain the Codex skill copy. The canonical skill is skills/<name>/; the Codex

plugins/<name>/skills/<name>/ is build output (Codex can't symlink/../-escape). Wire scripts/sync-codex-plugins.sh as a pre-commit hook (+ optional CI drift check) so the copy regenerates from canonical and can never go stale — script + hook in the references file.