[FEATURE] Skills from `.well-known` URIs

[jonathanhefner]

Cloudflare has made an RFC for distributing skills via .well-known URIs: https://github.com/cloudflare/agent-skills-discovery-rfc

Currently, the format is supported by npx skills add (as of v1.4.6), and the Agent Skills org is planning to adopt the proposal: agentskills/agentskills#254

Would it be reasonable for APM to also support installing skills from .well-known URIs (via apm.yml)?

As an additional point of consideration, MCP is also planning to standardize a .well-known URI. Once that is in place, a URL like example.com could resolve to some combination of skills and MCP server, similar to a plugin.

[sergio-sisternes-epam]

Hi @jonathanhefner -- thanks for opening this request. It kicked off an important conversation.

#676 has since been filed as a detailed design proposal that covers URL-based marketplace registration for .well-known Agent Skills discovery indexes (including the Cloudflare RFC and MCP standardization you referenced). It proposes treating well-known discovery as a new marketplace backend, preserving the existing name@marketplace install UX.

We believe #676 supersedes this issue. Would you be okay with us closing #554 in favor of #676? Your input there would be very welcome as the original requester.

[sergio-sisternes-epam]

Cross-reference: This issue is part of a related set of URL-based dependency features being discussed together:

• [FEATURE] Skills from .well-known URIs #554 -- Direct URL dependencies in apm.yml (this issue)
• Marketplace add source parity with the Anthropic spec #676 -- URL-based marketplace registration via .well-known
• [FEATURE] URL-based marketplace work Extension #692 -- apm install URL for full packages

Design discussion is being coordinated in #676, which has been moved to needs-design to address the HTTPS authentication gap before implementation. See the comment there for context and open questions.

[jonathanhefner]

Would you be okay with us closing #554 in favor of #676? Your input there would be very welcome as the original requester.

That's fine with me if it helps to focus discussion! 👍 Note, though, that I mostly see /.well-known/agent-skills/index.json as a plugin-like thing rather than a marketplace-like thing. (At the moment, I think the story for the marketplace-like thing is still evolving.)

I've left a comment in #676 to that effect: #676 (comment).

[danielmeppiel]

Hey @jonathanhefner — circling back here. After looking at the broader marketplace landscape, we've reframed #676 to focus on parity with Anthropic's marketplace add source matrix (git URLs, local paths, remote marketplace.json URLs) rather than building against the Cloudflare .well-known/agent-skills/ RFC directly.

The reasoning: the Cloudflare RFC is still v0.2.0 draft, the upstream agentskills.io PR (#254) hasn't merged since March, and we don't yet see production adoption. Anthropic's spec is settled and serves the same enterprise / non-GitHub use cases.

That makes this issue effectively superseded by #676 Phase 1. The .well-known/agent-skills/ parser is parked behind a clear external trigger: Cloudflare RFC reaches v1.0, OR agentskills.io PR #254 merges, OR production adoption shows up. Then we revisit.

OK to close this as dup of #676? The work isn't dead — it's gated on upstream stability. Happy to re-open or spin a fresh issue when any of the triggers fire.

[jonathanhefner]

@danielmeppiel Thank you for clarifying! The .well-known URI is currently supported by Mintlify and supported by Vercel's skills.sh.

For example, MCP's site (hosted on Mintlify) has https://modelcontextprotocol.io/.well-known/agent-skills/index.json (generated by Mintlify), and so you can run npx skills add https://modelcontextprotocol.io/ to install those skills.

However, if you prefer to wait until agentskills/agentskills#254 is merged, I understand. We can revisit again in the future.

[github-actions]

Triage decision

needs-design

Proposed labels

theme/security
area/marketplace
area/mcp-trust
type/feature
status/needs-design

Milestone

null

Suggested next action

Open a GitHub discussion linking to the Cloudflare RFC and the AgentSkills.io proposal, define what trust model APM would apply to domain-scoped skill discovery (pinning, signature, policy controls), and propose the apm.yml syntax extension -- then link it back here.

Suggested issue comment

Thanks for flagging this! The Cloudflare agent-skills-discovery RFC and the AgentSkills.io `.well-known` adoption are real and worth tracking. The MCP `.well-known` standardization adds another dimension -- a single URL resolving to both skills and an MCP server would be a compelling packaging primitive for APM.

Before we can accept implementation PRs, a design document needs to settle the trust model:

1. **Identity and pinning**: GitHub-repo-based skills have a clear identity (owner/repo + git SHA). Domain-based skills do not. How does APM pin a `.well-known` skill? SHA of the manifest at install time? A version field in the manifest? Without pinning, re-installs could silently pull updated content.
2. **DNS and MITM risk**: `.well-known` URIs are HTTP-fetched. APM must decide whether to require HTTPS and whether to validate any additional integrity signal (e.g., a manifest signature).
3. **Policy controls**: `agent-policy.yml` currently restricts by package source (GitHub). Domain-scoped sources need a policy primitive -- e.g., an `allowed_domains` list.
4. **apm.yml syntax**: What does the dependency entry look like? `well-known: example.com`? A full URL?

This is promising territory. If you are interested in contributing the design, please open a discussion linking the RFC and proposing the trust model. We will track the AgentSkills.io and MCP standardization progress to time the implementation.

RFC: https://github.com/cloudflare/agent-skills-discovery-rfc
AgentSkills.io proposal: https://github.com/agentskills/agentskills/pull/254

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

The request is forward-looking and well-anchored in emerging standards (Cloudflare RFC, AgentSkills.io, MCP .well-known). The user task -- install a skill from a domain URL rather than a GitHub repo -- is a natural extension of the package manager model. The timing is relevant: npx skills add already supports it as of v1.4.6. APM should track this space and design for it when the standard stabilizes. The UX implication (domain-scoped identity, URL-based dependency in apm.yml) is manageable but needs design.

Supply Chain Security Expert -- Risk-Surface Reviewer

.well-known URI resolution is a significant trust surface. Any domain can serve a manifest -- APM would be fetching and installing skills from arbitrary HTTP endpoints, which is a fundamentally different trust model from GitHub-repo-scoped packages. Specific risks: DNS poisoning / MITM substituting malicious manifests; no inherent identity binding (a domain can change hands); no pinning mechanism in the current RFC draft. theme/security is mandatory. area/mcp-trust and area/marketplace apply. This needs a formal trust model design before any code lands.

OSS Growth Hacker -- Contributor-Tone Reviewer

Activated -- author has 1 prior interaction on microsoft/apm (first-time contributor). The reply validates the RFC research explicitly, names the specific RFCs referenced, acknowledges the MCP convergence angle as interesting, and gives a concrete contribution path (open a discussion with the trust model proposal). Tone is warm and encourages standards-tracking engagement.

Python Architect -- Architecture Reviewer

.well-known URI resolution requires: a new dependency source type, an HTTP fetcher for the discovery manifest, a manifest parser/validator, a pinning mechanism (manifest SHA or version field), and policy hooks for domain allow-listing. The MCP convergence (one URL resolving to skills + MCP server) adds a second resolution path. Cross-cutting impact is significant: deps layer, install layer, policy layer, lockfile schema. status/needs-design is correct -- the trust model must be settled before architecture can be defined.

Doc Writer -- Documentation Reviewer

Activated -- a new dependency source type (domain-scoped) and new apm.yml syntax would require documentation. Deferred until design is accepted. When it lands, the dependency reference page and a new guide for .well-known-based skills will be needed. area/docs-site is not added now (premature until design is accepted).

APM CEO -- Triage Arbiter

Legitimate forward-looking request tracking emerging standards. The direction is interesting and worth pursuing -- APM should not ignore the convergence of skills discovery and MCP .well-known standardization. However, the trust model is non-trivial and the standards are not yet stable. status/needs-design with no milestone is the right call: track the RFC progress, design the trust model, then implement. The reply should encourage the author to lead the discussion rather than leaving it to maintainers.

{
  "decision": "needs-design",
  "decision_detail": "Trust model (identity, pinning, DNS/MITM risk, policy controls) and apm.yml syntax must be designed before implementation; standard is also not yet stable.",
  "theme": "theme/security",
  "areas": ["area/marketplace", "area/mcp-trust"],
  "type": "type/feature",
  "status": "status/needs-design",
  "priority": null,
  "preserved_labels": [],
  "milestone": null,
  "next_action": "Open a GitHub discussion proposing the trust model (pinning, domain policy, apm.yml syntax) and linking the Cloudflare RFC and AgentSkills.io proposal.",
  "comment_markdown": "Thanks for flagging this! The Cloudflare RFC and AgentSkills.io adoption are worth tracking. Before implementation, a design must settle: (1) identity and pinning for domain-scoped skills, (2) HTTPS and integrity signal requirements, (3) domain policy controls in agent-policy.yml, (4) apm.yml syntax. Please open a discussion with the trust model proposal."
}

---

Triage status: agentic proposal pending human ratification.
Silence is approval. Maintainers can:

• Override any label or milestone above by editing it directly --
  human edits are authoritative and will not be reverted on
  subsequent runs.
• Re-trigger triage by applying the status/needs-triage label, or
  by removing status/triaged to enroll the issue in the next
  daily sweep.

Posted by the Triage Panel workflow. See .apm/skills/apm-triage-panel for the panel skill.

Generated by Triage Panel · ● 1.6M · ◷