The Agent Skills .well-known Proposal

Overview

A markdown file with YAML frontmatter is becoming the standard way to extend AI agents. SKILL.md defines what a skill does, when it should activate, and what instructions the agent should follow.

Anthropic published the spec in December 2025, and within months it was adopted by 30+ agent products including Claude Code, OpenAI Codex, GitHub Copilot, Gemini CLI, Cursor, and VS Code. Whatever happens with registries and discovery, SKILL.md is the de facto format.

The format is settled. The open questions are about distribution and discovery: how do skills get packaged, installed, and found?

One distribution system and one discovery proposal stand out:

1. Claude Code Plugin Marketplace: a federated system for distributing multi-component extensions (skills, hooks, agents, and tool servers). It is Claude Code-specific, but other coding agents (Codex, Cursor, Copilot, Gemini CLI) consume the same SKILL.md files with minor folder-name variations.
2. Agent Skills Discovery: Cloudflare’s RFC proposing decentralized skill publishing via .well-known URIs.

In this post I walk through the SKILL.md format, the Plugin Marketplace, the .well-known proposal, and hands-on installation with concrete examples, then lay out when you should reach for which tool.

The Three Layers of Agent Skills

The ecosystem is settling into three distinct layers:

The SKILL.md Format

Understanding the SKILL.md open standard is key to working with any part of this ecosystem. Every distribution and discovery system builds on it.

A skill is a directory containing a SKILL.md file with YAML frontmatter and markdown instructions:

my-skill/
├── SKILL.md           # Main instructions (required)
├── scripts/           # Optional executables
├── references/        # Optional documentation
└── assets/            # Optional templates/resources

The frontmatter is minimal. Only name and description are required; the spec also defines optional license, compatibility, metadata, and allowed-tools fields:

---
name: deploy-to-production
description: Deploy the application to production following the team's release checklist.
  Use when the user asks to "deploy", "ship", "release", or "push to prod".
---

## Pre-flight checks
1. Run the full test suite
2. Check that the changelog is updated
3. Verify no breaking API changes

## Deployment steps
1. Build the production bundle
2. Run database migrations
3. Deploy to staging first, verify
4. Promote to production
5. Run smoke tests against production

## Rollback procedure
If smoke tests fail, immediately run the rollback script...

The progressive disclosure model keeps context costs low. At startup, agents load only name + description (roughly 100 tokens per skill). The full SKILL.md body loads only when a task matches, and supporting files load only when referenced. This means you can have dozens of skills installed without bloating the context window.

Claude Code extends the standard with additional frontmatter fields, grouped into three themes:

• Invocation control (disable-model-invocation, user-invocable, when_to_use): decide who can trigger the skill and how Claude matches it to requests
• Execution control (context: fork, agent, model, effort): run the skill in an isolated subagent with a specific model and reasoning effort level
• Activation & lifecycle (paths, hooks, argument-hint): glob-scoped auto-activation, lifecycle hooks, and argument autocomplete hints

Claude Code Plugin Marketplace

Claude Code’s plugin system solves the distribution problem for complete, multi-component extensions that bundle skills, agents, hooks, tool servers, and LSP servers into a single installable package. The plugin packaging is Claude Code-specific, but the skills inside each plugin are portable: other coding agents read the same SKILL.md format with only minor folder-name differences. Claude Code looks in .claude/skills/, Codex looks in .agents/skills/, and Cursor, Copilot, and Gemini CLI follow similar conventions.

Architecture

A plugin marketplace is a Git repository containing a marketplace.json file that lists available plugins. Each plugin entry points to a source (GitHub repo, Git URL, local path, or npm package) and can pin to a specific commit SHA for reproducibility. The official Anthropic marketplace ships built into Claude Code.

A marketplace.json looks like this:

{
  "name": "team-tools",
  "owner": {
    "name": "DevTools Team"
  },
  "plugins": [
    {
      "name": "cloudflare",
      "description": "Skills for building on Cloudflare Workers, Agents SDK, and more",
      "source": {
        "source": "github",
        "repo": "cloudflare/skills"
      }
    },
    {
      "name": "local-conventions",
      "description": "Team coding conventions and deployment checklist",
      "source": "./plugins/local-conventions"
    }
  ]
}

What Makes Plugins Different

Plugins are the most vertically integrated approach. A single plugin can contain:

• Skills (SKILL.md files with instructions for the agent)
• Agents (subagent definitions for specialized tasks)
• Hooks (shell commands that execute automatically on events)
• MCP servers (external tool and data source connections via .mcp.json)
• LSP servers (language intelligence for 11+ languages via .lsp.json)
• Monitors (background processes that tail logs or watch files and stream events to Claude as notifications)
• Executables (a bin/ directory added to the Bash tool’s PATH while the plugin is enabled)
• Default settings (a settings.json that can, for example, activate one of the plugin’s custom agents as the main thread)

This bundling is powerful. Cloudflare’s plugin, for example, ships 8 specialized skills alongside tool servers for live documentation access, API exploration, observability queries, and build management. Installing it gives Claude Code deep Cloudflare expertise in a single command.

The tradeoff is portability: plugin packaging, hooks, and marketplace metadata work mainly with Coding Agents. While it’s convenient to leverage GitHub and NPM registries for hosting the plugins/skills, it might not be the best fit for other agents.

Agent Skills Discovery: The .well-known Proposal

The Cloudflare Agent Skills Discovery RFC takes a fundamentally different approach to the distribution question. Instead of a Git-hosted catalog or package manager, it proposes that any domain can publish discoverable skills at a predictable URL, following RFC 8615 (the same standard behind /.well-known/openid-configuration and ACME certificate challenges).

The AI ecosystem is already using this pattern elsewhere: the A2A protocol publishes agent cards at /.well-known/agent-card.json to advertise an agent’s identity, capabilities, skills, and auth requirements, and agent-skills-discovery is the skill-level analog.

How It Works

An organization publishes an index.json at:

https://example.com/.well-known/agent-skills/index.json

The index lists available skills with names, descriptions, types, URLs, and SHA-256 digests for integrity verification:

{
  "$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
  "skills": [
    {
      "name": "deploy-to-workers",
      "description": "Deploy applications to Cloudflare Workers with best practices for routing, bindings, and environment configuration",
      "type": "skill-md",
      "url": "./skills/deploy-to-workers/SKILL.md",
      "digest": "sha256:a1b2c3d4e5f6..."
    },
    {
      "name": "durable-objects",
      "description": "Build stateful coordination with Durable Objects including RPC methods, SQL storage, and WebSocket hibernation",
      "type": "archive",
      "url": "./skills/durable-objects.tar.gz",
      "digest": "sha256:f6e5d4c3b2a1..."
    }
  ]
}

Each entry’s type tells the agent how to fetch the skill. skill-md points at a single SKILL.md file, which is good for instruction-only skills. archive points at a .tar.gz or .zip bundle containing SKILL.md plus supporting scripts/, references/, and assets; the agent verifies the SHA-256 digest, unpacks it locally, and loads resources on demand.

The spec uses progressive disclosure across three levels:

1. Level 1 (Index): Agent fetches index.json to see available skills. Each entry uses roughly 100 tokens of context.
2. Level 2 (Instructions): When a skill matches a task, the agent fetches the full SKILL.md (recommended under 5K tokens).
3. Level 3 (Resources): Supporting files (scripts, references, assets) load on-demand from unpacked archives.

Why Developers Like It

The appeal is simplicity.

The RFC builds entirely on existing web infrastructure: HTTP, JSON, SHA-256 digests, RFC 3986 URL resolution. No new protocol, no new runtime, no new authentication scheme. If you can serve static files, you can publish agent skills.

Current State

The RFC is at v0.2.0 (draft, updated March 12, 2026). Version 0.2.0 introduced breaking changes from v0.1.0: the URI was renamed from /.well-known/skills/ to /.well-known/agent-skills/, the version field was replaced with a $schema URI, and SHA-256 digest verification was added. The repo tracks issues and schema updates.

The community is in the process of adopting the Cloudflare RFC into the Agent Skills specification. There is an open PR tracking it.

The Vercel Skills CLI is the easiest way to install skills. It auto-detects which agents you have installed and writes each skill into the right folder for each one: .claude/skills/ for Claude Code, .agents/skills/ for Codex, and equivalents for 45+ supported agents. Installing skills from a .well-known location is supported, though not yet documented [NEEDS VERIFICATION].

Testing: Installing Skills from /.well-known/agent-skills/

To make this concrete, I published two tiny validation skills for my2cents.ai at the spec-compliant path. The discovery index lives at https://www.my2cents.ai/.well-known/agent-skills/index.json and advertises:

• my2cents-hello: prints a fixed signature line so I can confirm discovery and install worked end-to-end.
• my2cents-about: returns a canned one-paragraph description of the blog.

My whole setup is three static files served at the well-known path:

/.well-known/
└── agent-skills/
    ├── index.json                      # Discovery index with SHA-256 digests
    └── skills/
        ├── my2cents-hello/SKILL.md
        └── my2cents-about/SKILL.md

The index.json itself is just a few lines, following the RFC v0.2.0 schema:

{
  "$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
  "skills": [
    {
      "name": "my2cents-hello",
      "description": "A tiny validation skill that prints a fixed signature line so you can confirm skill discovery and installation worked end-to-end.",
      "type": "skill-md",
      "url": ".well-known/agent-skills/skills/my2cents-hello/SKILL.md",
      "digest": "sha256:f53e6e60c2ead..."
    },
    {
      "name": "my2cents-about",
      "description": "Returns a canned one-paragraph description of my2cents.ai verbatim.",
      "type": "skill-md",
      "url": ".well-known/agent-skills/skills/my2cents-about/SKILL.md",
      "digest": "sha256:3fecbcc253f14..."
    }
  ]
}

I installed them with the Vercel Skills CLI. Install the CLI once, then one command to pull the skills:

npm install -g skills
skills add https://www.my2cents.ai

(If you would rather not install globally, npx skills add https://www.my2cents.ai works too.)

Under the hood, skills add does four things:

1. Resolves the discovery path. Given a bare domain, the CLI appends /.well-known/agent-skills/index.json and fetches it. I did not have to pass the full path.
2. Reads the index. It parses the skills array and shows me each skill’s name and description so I can pick which ones to install (or install all).
3. Verifies integrity. For every skill entry with a digest, it downloads the SKILL.md (or archive), computes the SHA-256, and aborts if the digest does not match the index.
4. Writes to the right folder per agent. The CLI scans the current project for agent markers (.claude/, .agents/, .cursor/, etc.) and copies each skill into the matching directory. Because I run Claude Code, my skills landed in .claude/skills/my2cents-hello/SKILL.md and .claude/skills/my2cents-about/SKILL.md.

A few other skills subcommands worth knowing:

skills list                    # show installed skills
skills find <query>            # search the skills.sh directory
skills update                  # re-fetch and re-verify all installed skills
skills rm my2cents-hello       # uninstall a skill

Then I validated in Claude Code:

/my2cents-hello
# → 👋 Hello from my2cents.ai — my2cents-hello skill v1 is loaded.

/my2cents-about
# → my2cents.ai is an AI-focused technical blog with daily AI news roundups...

That was the whole publishing story for me: a static JSON file at a predictable path, SHA-256 digests for integrity, and any agent on the other side can find and install the skills. No registry account, no package publish step, no auth.

Verdict

From what I have seen, the agent skills landscape is converging on a shared set of primitives. SKILL.md is the format. Progressive disclosure is the loading pattern. The open questions are about distribution and discovery.

Claude Code Plugin Marketplace is, in my view, the most capable distribution system available today. The ability to bundle skills, hooks, agents, tool servers, and LSP servers into one installable package is genuinely useful. The tradeoff is Claude Code lock-in: the skills themselves are portable to Codex, Cursor, Copilot, and Gemini CLI via the shared SKILL.md format, but the plugin packaging is not. If you work primarily in Claude Code and want the deepest integration, this is the way.

Agent Skills Discovery (.well-known) is the most architecturally sound proposal I have looked at. Building on RFC 8615 means no new infrastructure, no central point of failure, and any domain can participate. It is still a draft, and adoption beyond Mintlify is limited, but the design is right. If you are a platform vendor or documentation provider, publishing at /.well-known/agent-skills/ is a low-cost investment with potential for broad reach. Publishing my own was three static files, as I showed above.

The biggest gap I see is cross-platform search. No tool searches across all skill directories simultaneously. The Agentic AI Foundation may consolidate these efforts eventually, though I would not count on a timeline.

For now, my practical move is to use SKILL.md as the format, Claude Code plugins (or the equivalent skills folder in your agent of choice) when you need deep integration, npx skills to install across agents, and keep an eye on .well-known/agent-skills/ as the discovery layer matures. The pieces are all on the table. Connecting them is the work ahead.