cloudflare / cloudflare/skills

Feature request: add coordinator.domains: frontmatter to cloudflare:* SKILL.md files (for spec-coordinator tag-routing)

Open
#49 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Shell
Stars
2.8k
Forks
272
Avg merge
8h 48m
Merged PRs (30d)
60

Description

## Context

A separate skills framework — [Agent Upskill's spec-coordinator](https://github.com/agentupskill/skills-core/tree/main/spec-coordinator) — uses an SME registry to route cross-domain spec requests to relevant skills. The registry consists of two routing layers:

1. **Tag-match (deterministic)** — picks skills whose `coordinator.domains: [...]` frontmatter overlaps the user query's tokens (confidence 1.0).
2. **Sonnet classifier (fallback)** — scores skills against the query via prompted classification (confidence 0.0–1.0; threshold 0.6 for picks).

In-house skills (e.g., `pwa-architect`, `hitl-learning-architect`) ship a `coordinator.domains: [...]` overlay so they're picked deterministically when the query matches their domain. Plugin skills like `cloudflare:*` currently ship without this overlay, which means they're picked classifier-only.

This works correctly today (the classifier picks `cloudflare:agents-sdk`, `cloudflare:workers-best-practices`, `cloudflare:durable-objects`, etc. when relevant — see [agentupskill/skills-core#56](https://github.com/agentupskill/skills-core/pull/56) for the algorithmic clarification that ensures classifier coverage). But adding a tag-match overlay would:

- Reduce ~5 Sonnet classifier calls per spec query when a `cloudflare:*` skill is clearly relevant (token-overlap sufficient).
- Eliminate classifier-confidence variance (currently ±0.1 per `_threshold-calibration.md` F4.5) on queries where domain match is unambiguous.
- Make routing more auditable — tag-picked skills emit `method: tag` with a domain-list in the routing trace.

## Specific request

For each `cloudflare:*` skill's `SKILL.md` frontmatter, add a `coordinator.domains: [...]` field listing 3–8 representative domain tokens. Suggested domains per skill (calibrated against Agent Upskill's [_routing-priors.md](https://github.com/agentupskill/skills-core/blob/main/spec-coordinator/references/_routing-priors.md) Z2/Z3/Z5/Z6/Z14/Z17 ambiguity zones):

| Skill | Suggested `coordinator.domains` |
|---|---|
| `cloudflare:cloudflare` | (umbrella — leave classifier-only; Z6 specific-over-umbrella rule prefers specific skills when both match) |
| `cloudflare:durable-objects` | `durable-object`, `do`, `stateful-coordination`, `multiplayer`, `chat-room`, `websocket`, `alarm`, `sqlite-storage` |
| `cloudflare:agents-sdk` | `agent`, `agents-sdk`, `mcp-server`, `workflow`, `durable-execution`, `voice-agent`, `browser-automation` |
| `cloudflare:workers-best-practices` | `workers`, `worker-code`, `floating-promise`, `streaming`, `global-state`, `wrangler`, `worker-anti-patterns` |
| `cloudflare:wrangler` | `wrangler`, `wrangler-cli`, `worker-deploy`, `kv-namespace`, `r2-bucket`, `d1-database` |
| `cloudflare:sandbox-sdk` | `sandbox`, `sandbox-sdk`, `code-execution`, `code-interpreter`, `untrusted-code`, `ci-cd` |
| `cloudflare:cloudflare-email-service` | `email-routing`, `email-sending`, `transactional-email`, `spf`, `dkim`, `dmarc` |
| `cloudflare:web-perf` | `web-performance`, `core-web-vitals`, `lcp`, `inp`, `cls`, `lighthouse`, `chrome-devtools` |

The `coordinator:` block is namespaced under a custom-coordinator key so it doesn't conflict with existing Anthropic-defined frontmatter fields. Schema (per [`_routing-algorithm.md` §Inputs](https://github.com/agentupskill/skills-core/blob/main/spec-coordinator/references/_routing-algorithm.md)):

```yaml
---
name: cloudflare:durable-objects
description: ...
coordinator:
domains: [durable-object, stateful-coordination, websocket, alarm, sqlite-storage]
pickable: true # default; only set false for product-owner / invoker skills
---
```

## Why upstream rather than a downstream patch

Plugin frontmatter ships with the plugin distribution and is not editable downstream. Without the overlay shipped in the source, every Agent Upskill installation that consults `cloudflare:*` SMEs falls back to classifier-only routing.

## Empirical context

PR-#320 ([Boogles-Playhouse/claude-skills#320](https://github.com/Boogles-Playhouse/claude-skills/pull/320)) drafted an 8-PR substrate-epic spec that needed a 6-SME panel including 3 `cloudflare:*` skills. The classifier sweep correctly picked them post-fix (see [agentupskill/skills-core#56](https://github.com/agentupskill/skills-core/pull/56)), but tag-match would have been faster + more deterministic. F-CAL-6 in [_threshold-calibration.md](https://github.com/agentupskill/skills-core/blob/main/spec-coordinator/references/_threshold-calibration.md) records the calibration trace.

## Acceptance

- Each `cloudflare:*` SKILL.md gets a `coordinator.domains: [...]` block (or the umbrella one explicitly opts out).
- A short note added to the marketplace README explaining the field's consumer (Agent Upskill spec-coordinator) so future skill authors know to populate it.
- No breaking changes to Cloudflare's existing skill consumption — the field is additive.

Happy to send a PR if Cloudflare prefers that route over a maintainer-driven change.

## Cross-references

- Routing algorithm: [agentupskill/skills-core/spec-coordinator/references/_routing-algorithm.md](https://github.com/agentupskill/skills-core/blob/main/spec-coordinator/references/_routing-algorithm.md)
- Ambiguity zones (cloudflare-touching: Z2 PWA × Workers, Z3 system-design × DO, Z5 PWA × HITL × CF AI, Z6 umbrella × specific, Z14 mcp-builder × agents-sdk, Z17 substrate-epic): [_routing-priors.md](https://github.com/agentupskill/skills-core/blob/main/spec-coordinator/references/_routing-priors.md)
- PR-#320 calibration: [_threshold-calibration.md F-CAL-6](https://github.com/agentupskill/skills-core/blob/main/spec-coordinator/references/_threshold-calibration.md)

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.