{
  "markdown": "# Pubky Agent Skills\n\nAgent skills that help AI coding tools build on and operate the [Pubky](https://pubky.org)\nprotocol — install once and get accurate, drift-resistant context for the SDKs, data specs,\nauth flow, and infrastructure in every editor and CLI.\n\nA skill is a folder under [`skills/`](./skills) containing a `SKILL.md`. It follows the open\n**[Agent Skills](https://agentskills.io)** standard, so the same files work across Claude\nCode, Codex, Cursor, OpenCode, Gemini CLI, and others. The repo doubles as a Claude Code\nplugin marketplace.\n\n> Replaces the single-file [`pubky-ai-kit`](https://github.com/pubky/pubky-ai-kit) context\n> doc. The old monolith loaded ~1,300 lines all at once; these skills load a thin always-on\n> overview and pull in topic reference files only when relevant.\n\n> ℹ️ **Private during development.** The repo is private for now, so installs require access\n> to `pubky/agent-skills` until it's made public.\n\n## Skills\n\nOne plugin (`pubky`), four skills split by **audience / task** — not by SDK language (every\nSDK re-expresses the same protocol spine, so language is a reference-file dimension, not a\nskill boundary). Each skill auto-activates on its own triggers.\n\n| Skill | For | Covers |\n| :-- | :-- | :-- |\n| **`pubky`** | Building web / server apps | `@synonymdev/pubky` (JS/WASM) + the `pubky` Rust crate, `pubky-app-specs`, the `pubkyauth` flow, `pubky://` `/pub` storage, consuming the Nexus read API, testnet |\n| **`pubky-mobile`** | Building native iOS / Android / React Native apps | `@synonymdev/react-native-pubky`, `pubky-core-ffi`, Pubky Ring deeplink auth, mobile-only safety gotchas |\n| **`pubky-infra`** | Operating / self-hosting | homeserver, Nexus indexer, `pubky-docker` stack, `homegate`, `pkdns`, relays |\n| **`nexus-scout`** | Asking questions *of* the social graph | read-only Cypher over the public [nexus-scout](https://nexus-scout.pubky.app) gateway: followers, tags, threads, reputation, follow distance. Vendored verbatim from upstream |\n\n## Install\n\nEvery tool installs from this repo via a marketplace, extension, or managed CLI — no manual\nclones. **Claude Code** and **Codex** have native plugin marketplaces, **Gemini CLI** installs\nit as an extension, and **Cursor** imports it from GitHub in its UI; for every other tool, the\nGitHub CLI (`gh skill`) installs straight into that tool's skills directory.\n\n### Claude Code\n\n```sh\n/plugin marketplace add pubky/agent-skills\n/plugin install pubky@pubky-agent-skills\n/reload-plugins\n```\n\nTurn on auto-update so new commits flow in: `/plugin` → **Marketplaces** → `pubky-agent-skills`\n→ **Enable auto-update** (off by default for third-party marketplaces). Claude Code then fetches\nupdates at startup; run `/reload-plugins` to activate them. The four skills auto-activate on\ntheir triggers; to invoke one manually it's namespaced, e.g. `/pubky:pubky-infra`.\n\n### Codex CLI\n\n```sh\ncodex plugin marketplace add pubky/agent-skills\ncodex plugin add pubky@pubky-agent-skills\n```\n\nUpdate with `codex plugin marketplace upgrade pubky-agent-skills`, then re-run\n`codex plugin add pubky@pubky-agent-skills`. (Same commands work as `/plugin …` inside the\nCodex TUI.)\n\n### Cursor\n\nImport straight from GitHub in the UI — no CLI needed:\n\n1. Open **Cursor Settings** (`Cmd+Shift+J`).\n2. Go to the **Rules** tab.\n3. Click **Add Rule** → **Remote Rule (GitHub)**.\n4. Enter `https://github.com/pubky/agent-skills`.\n5. Select the skills to import.\n\nCursor copies them into `.cursor/skills/` and auto-discovers them (Cursor 2.4+). Re-import to\npull updates.\n\n### Gemini CLI\n\nInstalls as a native extension; `--auto-update` keeps it current automatically:\n\n```sh\ngemini extensions install https://github.com/pubky/agent-skills --auto-update\n```\n\nWithout `--auto-update`, refresh manually with `gemini extensions update pubky-agent-skills`\n(or `--all`). List with `/extensions list`.\n\n### OpenCode, Copilot, … (GitHub CLI)\n\nOther tools that read the `SKILL.md` standard install via `gh skill` (GitHub CLI **≥ 2.90**) —\nit writes into the host's own skills directory:\n\n```sh\ngh skill install pubky/agent-skills --all --agent opencode --scope user\ngh skill install pubky/agent-skills --all --agent github-copilot --scope user\n```\n\n`--agent` picks the host (`opencode`, `codex`, `claude-code`, `github-copilot`, …). Pull\nupdates with `gh skill update --all`.\n\n### Hermes (Nous Research)\n\n```sh\nhermes skills install pubky/agent-skills/pubky\nhermes skills install pubky/agent-skills/pubky-mobile\nhermes skills install pubky/agent-skills/pubky-infra\nhermes skills install pubky/agent-skills/nexus-scout\n```\n\nUpdate with `hermes skills update`.\n\n## Updates\n\nMerge to `main` and it ships — there's no release step. How updates reach installed tools:\n\n- **Claude Code** — auto-fetched at startup once auto-update is enabled, then a one-time\n  `/reload-plugins` to activate.\n- **Gemini CLI** — fully automatic if installed with `--auto-update`; otherwise\n  `gemini extensions update pubky-agent-skills`.\n- **Codex** — `codex plugin marketplace upgrade pubky-agent-skills` + re-add.\n- **Cursor** — re-import the Remote Rule from the Rules tab.\n- **gh skill hosts (OpenCode, Copilot, …)** — `gh skill update --all`.\n- **Hermes** — `hermes skills update`.\n\nFor reproducibility, pin a tag/commit instead of tracking `main` (`--pin` with `gh skill`,\n`#tag` when adding the Codex marketplace, `--ref` with Gemini, or `ref`/`sha` in a Claude Code\nmarketplace source).\n\n## Layout\n\n```\n.claude-plugin/marketplace.json   # Claude Code marketplace + the pubky plugin\n.codex-plugin/plugin.json         # Codex\ngemini-extension.json             # Gemini CLI\nskills/<name>/SKILL.md            # thin, always-loaded: trigger + overview + routing table\nskills/<name>/references/*.md     # progressive-disclosure detail, loaded on demand\nskills/nexus-scout/SKILL.md       # EXCEPTION: byte copy of upstream's file — never hand-edit\n```\n\n## Future: MCP server\n\nA Pubky MCP server (homeserver / Nexus tools) will live in its own repo (mirroring\n`supabase/agent-skills` + `supabase/mcp`). When it ships, this plugin can auto-wire it by adding\na root `.mcp.json` that points at the hosted endpoint — no separate install step for users. The\nserver source stays out of this repo.\n\n## Updating the skill content from upstream\n\nThe reference files are **generated from upstream Pubky repos, not hand-edited**. To refresh\nthem after upstream changes, run this in Claude Code from the repo root:\n\n```sh\n/sync-references\n```\n\nIt fetches the tracked source repos, regenerates only the references whose sources changed\n(executing/verifying every code snippet against a local testnet), refreshes the vendored\nskills, and opens a signed **draft PR**. For a full rebuild of all 21 references, run\n`/sync-references --initial`.\n\n**`skills/nexus-scout/SKILL.md` is different: it is a byte copy**, not generated. It is authored\nupstream in [`pubky/nexus-scout`](https://github.com/pubky/nexus-scout) — which compiles it into\nthe gateway binary and serves it at [`/llms.txt`](https://nexus-scout.pubky.app/llms.txt) — and\nrefreshed here by `node maintenance/vendor-skills.mjs`. Editing it locally is pointless: the next\nsync overwrites it. Send corrections upstream.\n\nOne-time prerequisite — a local Postgres 18 for the snippet testnet (no Docker needed):\n\n```sh\nbrew install postgresql@18 && brew services start postgresql@18\n```\n\n(This regenerates the *content*; the **Updates** section above is about how the published\nskills reach installed tools.) See [`maintenance/README.md`](./maintenance/README.md) for how\nthe pipeline works.\n\n## Maintaining this repo\n\nSee [CLAUDE.md](./CLAUDE.md). The load-bearing rule: **shared concepts live in exactly one\nplace** (`skills/pubky/references/{concepts,app-specs,shipped-vs-planned}.md`); other skills\n**link, never copy**. Per [pubky-knowledge-base `.ai-rules.md`](https://github.com/pubky/pubky-knowledge-base-v2/blob/main/.ai-rules.md),\nreference files should link to maintained upstream sources and keep only short \"what this means\nin Pubky\" summaries rather than re-copying drift-prone API detail.\n\n## Security\n\nSkills are loaded into an agent's context and can instruct it to run bundled scripts — treat\nthis repo like any other code dependency. Changes go through PR review. Never put secrets or\ncredentials in a `SKILL.md` — they'd be pulled straight into model context.\n",
  "bytes": 8379,
  "sha": "a4cf21abc6d2c0507df679f67013f96a8557abc3ccc410fdbddaaabb8e604d25",
  "repo_slug": "pubky/agent-skills",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_pubky_agent_skills_4ab06e46/readme"
}