[FEATURE] Support `/.well-known/agent-skills` discovery as a remote skill source

[FEATURE] Support /.well-known/agent-skills discovery as a remote skill source

Preflight

• [x] I've searched existing feature requests and found no duplicate
• [x] This is a single feature request (not multiple combined)

Problem

Teams that deliver skills via MCP servers or internal HTTP endpoints have no way to make those skills discoverable as slash commands in Claude Code. The only path today is creating static wrapper files locally (.claude/skills/ or plugin skills/), one per remote skill, each containing a pointer back to the MCP resource. This doesn't scale, requires per-user setup, and breaks when skills are added or removed upstream.

The Cloudflare Agent Skills Discovery RFC (v0.2.0) defines /.well-known/agent-skills/index.json as a standard endpoint for advertising available skills. The Agent Skills spec — which Anthropic co-maintains — defines the SKILL.md format, which is already the same format Claude Code uses for local skills. The discovery layer and the skill format are both standardized and aligned with Claude Code's existing implementation.

No current workaround solves the problem

1. Static wrapper files in .claude/skills/ — One file per remote skill, each just saying "read the MCP resource and follow it." Manual maintenance, no autocomplete for new skills until files are created.
2. Plugin with per-skill stubs — Same problem packaged as a plugin. Still one-to-one mapping, still breaks when upstream adds skills.
3. Single dispatcher skill — e.g. /run brag with an argument. Works but loses autocomplete for individual skill names and requires users to know what's available.
4. Natural language — "run the brag skill." No discoverability, no autocomplete, inconsistent invocation.

Proposed solution

Add /.well-known/agent-skills URLs as a supported source type in skills.sources, alongside the existing gh skill / GitHub repo approach tracked in #50148.

Configuration

{
  "skills": {
    "sources": [
      {
        "type": "well-known",
        "url": "https://tools.acme.internal",
        "namespace": "acme-tools",
        "refresh": "session-start"
      }
    ]
  }
}

Or, for MCP servers that already expose skills as skill:// resources:

{
  "skills": {
    "sources": [
      {
        "type": "mcp",
        "server": "developer-assistant",
        "resourcePattern": "skill://*/SKILL.md",
        "namespace": "acme-tools"
      }
    ]
  }
}

This lets Claude Code discover skills directly from a connected MCP server by enumerating resources matching the pattern, without requiring a separate HTTP endpoint.

Lifecycle

1. Session start: Claude Code fetches {url}/.well-known/agent-skills/index.json
2. Validation: Verify $schema field, validate digests per the RFC
3. Registration: Each skill entry becomes /{namespace}:{skill-name} with autocomplete
4. Invocation: When invoked, fetch the SKILL.md from the entry's url, verify digest, and load as skill instructions — same as a local skill
5. Caching: Use digests for change detection; cache aggressively between sessions

Result

/acme-tools:deploy-checklist
/acme-tools:incident-runbook
/acme-tools:schema-migrate
/acme-tools:onboard-service

All populated dynamically from the discovery endpoint. No local files. Autocomplete works. New skills appear automatically on next session.

How this fits with existing work

• #50148 (remote skill sources via gh skill) — This proposal adds a complementary source type. GitHub repos work for public/open-source skill distribution; /.well-known/agent-skills works for MCP servers, internal services, and enterprise tooling that doesn't live in GitHub.
• #50154 (desktop remote source connection) — The well-known source type could surface in the desktop customize panel alongside GitHub sources.
• Agent Skills spec alignment — The SKILL.md format from the discovery endpoint is identical to what Claude Code already parses. No new format handling needed.
• Cloudflare RFC alignment — The discovery mechanism, digest verification, and progressive loading model are all specified. Claude Code would be implementing a client per an existing standard, not inventing a new one.

Use case

Enterprise teams that maintain internal developer tooling as MCP servers (code review workflows, brag doc capture, service documentation, etc.) need those capabilities to be first-class slash commands without requiring every developer to maintain local skill files. The MCP server already has the skill definitions — it just needs a standard way to advertise them.

Security considerations

The RFC specifies digest verification, origin allowlisting, and archive safety constraints. Claude Code should:

• Verify SHA-256 digests before loading skill content
• Respect the existing permission model for allowed-tools in fetched skills
• Only fetch from configured/allowlisted URLs (no auto-discovery from arbitrary domains)
• Apply the same trust model as locally-installed skills: user must explicitly add the source

Environment

• Claude Code CLI, Desktop, and Cowork (all surfaces that support skills)
• Any MCP server or HTTP endpoint that can host /.well-known/agent-skills/index.json

References

• Cloudflare Agent Skills Discovery RFC v0.2.0
• Agent Skills Specification
• Anthropic Skills Repo
• #50148 — First-class remote skill source integration
• #50154 — Desktop remote source connection
• gh skill CLI announcement