feat(mcp): add the MCP reference page, browse, and submit tools

GLOSSARY.md

@@ -25,7 +25,7 @@ Shared terms match the skilld CLI glossary (`skilld-dev/skilld/GLOSSARY.md`). Th
 | collection | `layers/collections`, `/@login/slug` | collection N—N Skill | "collection" |
 | watch | `layers/identity` | account N—N Repository or collection | "watch" |
 | digest | `layers/identity` email | account 1—1 digest schedule | "digest" |
-| track | `/skills/<slug>`, `layers/registry` | track 1—N Skill | "track" |
+| track | `/skills/<slug>`, `layers/registry`, MCP `list_tracks` and `get_track` | track 1—N Skill | "track" |
 | comparison | `/compare/<slug>`, `layers/marketing` | comparison N—N Skill | "comparison" |
 | trending | `/skills/trending`, ADR-0004 | Repository 1—N social mention | "trending" |
 | trending award | `skill_trending_awards`, ADR-0011 | Skill 1—N trending award | "#3 trending" |
@@ -145,12 +145,14 @@ Collisions
 
 ### track
 
-**Is:** a page of Skills for one kind of work, at `/skills/<slug>`. A person writes its label, its second-person line and its pinned Skills; a classifier category fills in the depth beneath them.
+**Is:** a page of Skills for one kind of work a developer wants done, at `/skills/<slug>`. A person writes its label, its second-person line and its pinned Skills; a classifier category fills in the depth beneath them.
 
 **Use for:** "hand-picked" names a track's pinned Skills in UI copy. "Pinned" stays in the code.
 
 **Never:** cluster, category, outcome, topic, use case (in UI). `CLUSTERS` and `abstractness_category` are the internal names and stay in the code.
 
+**Frozen identifiers:** the MCP tools `list_tracks` and `get_track`. Agents and directory listings call them by name, so a rename breaks every connected app.
+
 **Collides with:** collection. A track is ours, permanent, and one per kind of work. A collection belongs to a curator, at `/@login/slug`, and any number can exist.
 
 ### collection

docs/runbooks/agent-app-directories.md

@@ -39,13 +39,9 @@ A project with EU data residency cannot submit a plugin with an MCP server.
 
 2. Upload the ZIP. Select **Upload new or existing plugin** and choose the verified developer identity.
 3. Connect the `skilld` MCP server and choose **No authentication**.
-4. The portal shows a domain-verification token. Set it as a Worker secret:
-
-   ```sh
-   pnpm exec wrangler secret put NUXT_OPENAI_APPS_CHALLENGE --config wrangler.jsonc
-   ```
-
-   Then check that `https://skilld.dev/.well-known/openai-apps-challenge` prints the token, and complete the challenge.
+4. The portal shows a domain-verification token. Add it to `vars` in `wrangler.jsonc` as `NUXT_OPENAI_APPS_CHALLENGE` through a pull request.
+   The deploy workflow is the only path to production, and the token is public, so it belongs in the repository.
+   After the deploy, check that `https://skilld.dev/.well-known/openai-apps-challenge` prints the token, and complete the challenge.
 5. Scan the tools and resolve every finding.
 6. In **Review details**, add the demo video URL. The review needs a video of the five positive test cases in ChatGPT.
 7. Submit for review, accept the policy attestations, and publish after approval.
@@ -63,14 +59,14 @@ Any paid Claude plan can submit. Use these fields in the portal.
 | One-liner | Search curated agent skills, see who wrote each one, and get the command that runs it in your coding agent. |
 | Description | `longDescription` in `integrations/openai-plugin/plugin.json` |
 | Categories | Developer tools |
-| Documentation URL | `https://skilld.dev/developers?setup=mcp&app=claude` |
+| Documentation URL | `https://skilld.dev/developers/mcp` |
 | Privacy policy URL | `https://skilld.dev/privacy` |
-| Support contact | `https://github.com/skilld-dev/skilld.dev/issues` |
+| Support contact | `harlan@harlanzw.com` |
 | Icon | `public/logo-icon.png` |
 | Slug | `skilld`. The slug is permanent after publication |
-| Use cases | Find agent skills by topic, check provenance before a run, open curated collections, get run and install commands |
+| Use cases | Find agent skills by topic, check provenance and freshness before a run, browse a track or the trending board |
 | Requirements | None. Every tool works without an account |
-| Data access | Reads data only |
+| Data access | Reads data, and `submit_repository` queues an index request |
 | Company | Harlan Wilton, `https://skilld.dev`, `harlan@harlanzw.com` |
 | Authentication | No authentication |
 | Data handling | First-party API. No health data. No sponsored content |

integrations/openai-plugin/plugin.json

@@ -11,24 +11,36 @@
   "homepage": "https://skilld.dev/developers?setup=mcp",
   "repository": "https://github.com/skilld-dev/skilld.dev",
   "license": "MIT",
-  "keywords": ["agent skills", "SKILL.md", "coding agents", "codex", "developer tools"],
+  "keywords": [
+    "agent skills",
+    "SKILL.md",
+    "coding agents",
+    "codex",
+    "developer tools"
+  ],
   "extensions": {
     "com.openai": {
       "interface": {
         "displayName": "skilld",
         "shortDescription": "Curated agent skills by humans",
-        "longDescription": "skilld searches skilld.dev, a curated registry of agent skills. A skill is a SKILL.md file that a maintainer writes in their own GitHub repository. It teaches a coding agent how to use a library, a framework, or a workflow.\n\nAsk for a skill by topic, such as Tailwind CSS, Nuxt, or database migrations. skilld returns the matching skills with their author, source repository, GitHub star count, and skilld.dev page. For one skill, it shows the exact SKILL.md and commit on GitHub, when the skill last changed, and the full skill text, so you can read a skill before you run it. It also opens curated collections, where a curator explains why each skill is in the set.\n\nEvery skill comes with its commands. npx skilld run gives the skill to a coding agent for one session and writes no files. npx skilld install keeps the skill in a project. skilld runs and installs nothing itself. You run the command in your own terminal or coding agent.\n\nskilld needs no account and reads public registry data only.",
+        "longDescription": "skilld searches skilld.dev, a curated registry of agent skills. A skill is a SKILL.md file that a maintainer writes in their own GitHub repository. It teaches a coding agent how to use a library, a framework, or a workflow.\n\nAsk for a skill by topic, such as Tailwind CSS, Nuxt, or database migrations. skilld returns the matching skills with their author, source repository, GitHub star count, and skilld.dev page. For one skill, it shows the exact SKILL.md and commit on GitHub, when the skill last changed, and the full skill text, so you can read a skill before you run it.\n\nYou can also browse. A track is a page of skills for one kind of work, such as testing and debugging or design and interface work. The trending board shows which skills developers talked about on X and Bluesky, with a post that mentioned each one, and which skills gained GitHub stars fast. You can also list every skill that one GitHub repository publishes.\n\nEvery skill comes with its commands. npx skilld run gives the skill to a coding agent for one session and writes no files. npx skilld install keeps the skill in a project. skilld runs and installs nothing itself. You run the command in your own terminal or coding agent.\n\nskilld needs no account. It reads public registry data, and it can ask skilld.dev to index the skills in a public GitHub repository. A person still reviews which skills the registry admits.",
         "developerName": "Harlan Wilton",
         "category": "Developer Tools",
-        "capabilities": ["Search agent skills", "Show skill provenance and source", "Open curated collections", "Return run and install commands"],
+        "capabilities": [
+          "Search agent skills",
+          "Show skill provenance and source",
+          "Browse tracks and trending skills",
+          "Return run and install commands",
+          "Submit a repository for indexing"
+        ],
         "websiteURL": "https://skilld.dev",
-        "supportURL": "https://github.com/skilld-dev/skilld.dev/issues",
+        "supportURL": "https://skilld.dev/developers/mcp#support",
         "privacyPolicyURL": "https://skilld.dev/privacy",
         "termsOfServiceURL": "https://skilld.dev/terms",
         "defaultPrompt": [
           "Find a skill for Tailwind CSS and give me the run command.",
-          "Who wrote the web-design-guidelines skill, and when did it last change?",
-          "What is in the Agent builder essentials collection on skilld?"
+          "Which skills help with testing and debugging?",
+          "What skills are developers talking about this week?"
         ],
         "brandColor": "#E11D48",
         "brandColorDark": "#FB7185",
@@ -51,16 +63,16 @@
               "expected_behavior": "Names Vercel Labs as the publisher. Links the SKILL.md file on GitHub and gives its commit, the last repository push date, and the last skill change date."
             },
             {
-              "description": "Read a skill before running it",
-              "prompt": "Show me the SKILL.md of vercel-labs/agent-skills/web-design-guidelines before I run it.",
-              "tools_triggered": "get_skill",
-              "expected_behavior": "Returns the SKILL.md text with a link to its source file on GitHub, and the npx skilld run command for the skill."
+              "description": "Browse a track",
+              "prompt": "Which skills help with testing and debugging?",
+              "tools_triggered": "list_tracks, get_track",
+              "expected_behavior": "Finds the Testing and debugging track and lists its skills, each with its author, skilld.dev page, and npx skilld run command."
             },
             {
-              "description": "Open a curated collection",
-              "prompt": "What is in the agent-building-stack collection by harlan-zw on skilld?",
-              "tools_triggered": "get_collection",
-              "expected_behavior": "Returns the Agent builder essentials collection: its skills, the curator's reason for each skill, and the npx skilld add @harlan-zw/agent-building-stack command that installs the whole collection."
+              "description": "See what developers talk about",
+              "prompt": "What skills are developers talking about this week?",
+              "tools_triggered": "list_trending",
+              "expected_behavior": "Lists this week's trending skills in rank order. Each row says why it is there: developers mentioned it on X or Bluesky, with one post, or its GitHub stars rose. Each row gives an npx skilld run command. It does not call any skill popular or safe."
             },
             {
               "description": "Get the run command for one skill",
@@ -75,7 +87,7 @@
               "prompt": "Write a new SKILL.md for my React project and publish it on skilld."
             },
             {
-              "description": "Change registry data. Every skilld tool is read only.",
+              "description": "Change registry data. skilld has no tool that edits or deletes a skill.",
               "prompt": "Delete the tailwind skill from skilld.dev."
             },
             {
@@ -89,7 +101,7 @@
       },
       "publication": {
         "countries": [],
-        "release_notes": "First release. Search skilld.dev for agent skills, show who wrote each skill and where its source lives, open curated collections, and return run and install commands."
+        "release_notes": "First release. Search skilld.dev for agent skills, show who wrote each skill and where its source lives, browse tracks and the trending board, and return run and install commands."
       }
     }
   }

layers/identity/app/layouts/account.vue

@@ -15,7 +15,7 @@ const navigation = computed<NavigationMenuItem[]>(() => [
   { label: 'Your skills', icon: 'i-lucide-heart', to: '/me', active: route.path === '/me' && !['email', 'repositories', 'skillgen', 'account'].includes(String(route.query.view)) },
   { label: 'Repository coverage', icon: 'i-lucide-git-fork', to: '/me?view=repositories', active: route.path === '/me' && route.query.view === 'repositories' },
   { label: 'Email updates', icon: 'i-lucide-mail', to: '/me?view=email', active: route.path === '/me' && route.query.view === 'email' },
-  { label: 'Set up your agent', icon: 'i-lucide-plug', to: '/developers', active: route.path === '/developers' },
+  { label: 'Set up your agent', icon: 'i-lucide-plug', to: '/developers', active: route.path === '/developers' || route.path.startsWith('/developers/') },
   { label: 'Skillgen', icon: 'i-lucide-git-pull-request-draft', to: '/me?view=skillgen', active: route.path === '/me' && route.query.view === 'skillgen' },
   { label: 'Devices and tokens', icon: 'i-lucide-terminal', to: '/me/devices', active: route.path.startsWith('/me/devices') || route.path.startsWith('/me/cli-tokens') },
   { label: 'Account', icon: 'i-lucide-settings', to: '/me?view=account', active: route.path === '/me' && route.query.view === 'account' },

layers/marketing/app/pages/developers.vue → layers/marketing/app/pages/developers/index.vue

@@ -1,21 +1,20 @@
 <script setup lang="ts">
-import { REGISTRY_MCP_URL } from '#shared/agent-setup'
-import ApiTokenSetup from '../components/_ApiTokenSetup.vue'
-import SetupSnippet from '../components/_SetupSnippet.vue'
+import { claudeConnectorUrl, REGISTRY_MCP_URL } from '#shared/agent-setup'
+import ApiTokenSetup from '../../components/_ApiTokenSetup.vue'
+import SetupSnippet from '../../components/_SetupSnippet.vue'
 import {
   API_OPENAPI_PATH,
   apiSamples,
   apiSnippets,
-  claudeConnectorUrl,
   cursorInstallUrl,
   mcpApps,
   setupModes,
   setupSnippets,
   SKILLD_SKILL_SOURCE,
   vscodeInstallUrl,
-} from '../utils/developer-setup'
-import { apiSampleSchema, mcpAppSchema, setupModeSchema } from '../utils/developer-setup-query'
-import { pageRobots } from '../utils/page-admissions'
+} from '../../utils/developer-setup'
+import { apiSampleSchema, mcpAppSchema, setupModeSchema } from '../../utils/developer-setup-query'
+import { pageRobots } from '../../utils/page-admissions'
 
 definePageMeta({ layout: 'account' })
 
@@ -178,7 +177,7 @@ const uiClass = 'font-medium text-default'
               Copy the server URL
             </h3>
             <p class="mt-2 text-sm leading-relaxed text-muted">
-              No account and no API key. Every tool is read only.
+              No account and no API key. Every tool is read only, except the one that submits a repository for indexing.
             </p>
             <SetupSnippet class="mt-3" :code="REGISTRY_MCP_URL" label="server URL" />
           </div>
@@ -210,13 +209,15 @@ const uiClass = 'font-medium text-default'
             <div class="mt-5 text-sm leading-relaxed text-muted">
               <template v-if="app === 'chatgpt'">
                 <ol class="list-decimal space-y-2 pl-5">
-                  <li>Open <strong :class="uiClass">Settings &gt; Security and login</strong>, then turn on <strong :class="uiClass">Developer mode</strong>.</li>
-                  <li>Open <strong :class="uiClass">ChatGPT Plugins</strong> and select <strong :class="uiClass">+</strong>. Name the app skilld, paste the server URL, and choose <strong :class="uiClass">No Authentication</strong>.</li>
-                  <li>In a chat, open the <strong :class="uiClass">+</strong> menu, choose <strong :class="uiClass">Developer mode</strong>, and select skilld.</li>
+                  <li>Open <a href="https://chatgpt.com/plugins" target="_blank" rel="noopener" :class="uiClass" class="underline underline-offset-2">Plugins</a> in ChatGPT on the web. Select <strong :class="uiClass">Add</strong>, then <strong :class="uiClass">Add custom MCP server</strong>.</li>
+                  <li>Name it skilld and paste the server URL.</li>
+                  <li>Change <strong :class="uiClass">Authentication</strong> from <strong :class="uiClass">OAuth</strong> to <strong :class="uiClass">No authentication</strong>, and tick <strong :class="uiClass">I understand and want to continue</strong>.</li>
+                  <li>Select <strong :class="uiClass">Create as a plugin</strong>, then <strong :class="uiClass">Connect skilld</strong>.</li>
+                  <li>In a chat, ask for skilld by name, such as "Use skilld to find a Skill for Tailwind CSS."</li>
                 </ol>
                 <p class="mt-4">
-                  Developer mode needs a Plus, Pro, Business, Enterprise, or Education plan, on the web.
-                  <a href="https://developers.openai.com/api/docs/guides/developer-mode" target="_blank" rel="noopener" class="underline underline-offset-2 hover:text-default">Read OpenAI's guide</a>.
+                  Your ChatGPT plan and workspace settings decide whether you can add a custom MCP server.
+                  <a href="https://developers.openai.com/api/docs/guides/custom-mcp-server" target="_blank" rel="noopener" class="underline underline-offset-2 hover:text-default">Read OpenAI's guide</a>.
                 </p>
               </template>
 
@@ -306,6 +307,13 @@ const uiClass = 'font-medium text-default'
               The server returns the run command and the install command for each Skill. It never runs or installs a Skill. You choose what runs.
             </p>
             <SetupSnippet class="mt-3" :code="setupSnippets.mcpPrompt" label="example prompt" />
+            <UButton
+              to="/developers/mcp"
+              label="Tool reference, limits, and support"
+              color="neutral"
+              variant="link"
+              class="mt-2 min-h-11 px-0 text-sm"
+            />
           </div>
         </li>
       </ol>

layers/marketing/app/utils/developer-setup.ts

@@ -42,15 +42,6 @@ export function cursorInstallUrl(url: string = REGISTRY_MCP_URL): string {
   return `cursor://anysphere.cursor-deeplink/mcp/install?name=${SERVER_NAME}&config=${encodeURIComponent(config)}`
 }
 
-/**
- * Claude's link opens its Add custom connector dialog with the name and URL
- * filled in. The user still confirms before Claude adds anything.
- */
-export function claudeConnectorUrl(url: string = REGISTRY_MCP_URL): string {
-  const query = new URLSearchParams({ modal: 'add-custom-connector', connectorName: SERVER_NAME, connectorUrl: url })
-  return `https://claude.ai/customize/connectors?${query}`
-}
-
 /** VS Code's install link carries the whole server entry as URI-encoded JSON. */
 export function vscodeInstallUrl(url: string = REGISTRY_MCP_URL): string {
   return `vscode:mcp/install?${encodeURIComponent(vscodeServerJson(url))}`

layers/marketing/app/utils/page-admissions.ts

@@ -43,6 +43,7 @@ export const FREEZE_AUDIT_PATHS: readonly string[] = [
   '/docs/cli',
   '/cli',
   '/developers',
+  '/developers/mcp',
   '/skillgen',
   '/privacy',
   '/terms',

layers/marketing/content/pages/privacy.md

@@ -128,14 +128,18 @@ If the client sends your operating system and processor type, such as `darwin-ar
 
 ## The MCP server
 
-ChatGPT, Claude, and other MCP apps can search skilld.dev through its MCP server at `https://skilld.dev/api/mcp`. The server needs no account and sets no cookie. Every tool is read only.
+ChatGPT, Claude, and other MCP apps can search skilld.dev through its MCP server at `https://skilld.dev/api/mcp`. The server needs no account and sets no cookie. Every tool is read only, except `submit_repository`.
 
 When your chat app calls a tool, skilld receives what that tool needs:
 
 - `search_skills` receives your search text and a result count.
 - `get_skill` receives the owner, Repository, and name of one Skill.
-- `get_collection` receives a curator login and a collection slug.
-- `install_command` receives one Skill, Repository, or collection reference.
+- `install_command` receives one Skill or Repository reference.
+- `list_tracks` receives nothing.
+- `get_track` receives a track slug, a result count, and an offset.
+- `list_trending` receives a period, a week or a month, and a result count.
+- `get_repository` receives the owner and name of one Repository and a result count.
+- `submit_repository` receives one Repository name or URL. skilld stores the index request with the Repository name and its status. It records nothing about who sent it.
 
 skilld receives no chat history, no files from the chat, and no account details from the chat app. ChatGPT and Claude call the server from OpenAI or Anthropic servers, so skilld sees their IP address, not yours. Apps on your computer, such as Claude Code or Cursor, call it from your network. Rate limits count requests per IP address, and skilld stores no IP address.