cloudflare / cloudflare/skills
Improve Codex portability: frontmatter, router overlap, and pinned web-perf setup
- Dominant language
- Shell
- Stars
- 2.8k
- Forks
- 272
- Avg merge
- 8h 48m
- Merged PRs (30d)
- 60
Description
## Summary
The current Cloudflare skill bundle has a few Codex portability and context-efficiency problems that are individually small but compound when the bundle is surfaced as a plugin.
## Findings
1. `skills/cloudflare/SKILL.md` uses a top-level `references:` frontmatter field. Codex's current skill validator rejects that field, so the umbrella skill fails validation even though its referenced directories exist.
2. The umbrella description says "Use for any Cloudflare development task" while focused skills such as `workers-best-practices`, `wrangler`, `durable-objects`, and `agents-sdk` claim the same common requests. This makes the broad router and one or more specialists trigger together. Making the umbrella an explicit/cross-product router would reduce ambiguity and loaded context.
3. `skills/wrangler/SKILL.md` is currently about 897 lines. Moving command/reference tables into on-demand references would keep the always-loaded core closer to the recommended sub-500-line budget without removing coverage.
4. `skills/web-perf/SKILL.md` tells the agent to configure `npx -y chrome-devtools-mcp@latest` when tools are missing. That executes an unpinned registry package and mutates setup from inside a task. Please prefer capability discovery plus a documented, version-pinned installation step that the user explicitly approves.
## Suggested direction
- Move the umbrella's reference index into its Markdown body or another Codex-compatible metadata form.
- Narrow the umbrella trigger to cross-product selection/explicit invocation; let specialists own common implicit triggers.
- Split Wrangler's detailed command corpus into references loaded on demand.
- Replace the unpinned web-perf setup snippet with a pinned, approval-aware installation guide and a no-mutation fallback.
I searched existing open and closed issues for these frontmatter/router/Wrangler/web-perf terms and did not find a matching report.
Contributor guide
Research direction
Start by reviewing skills/cloudflare/SKILL.md, skills/wrangler/SKILL.md, and skills/web-perf/SKILL.md alongside the Codex skill validator behavior described in the issue. Check that the umbrella routing and metadata are Codex-compatible, Wrangler details are on demand, and web-perf setup is pinned, explicitly approved, and has a no-mutation fallback. Done means all four findings are addressed without removing coverage.
Written by the indexing model from the issue text.
Assessment
- Domain
- developer-experience, documentation, tooling
- Issue type
- Refactor
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100