cloudflare / cloudflare/skills

Improve Codex portability: frontmatter, router overlap, and pinned web-perf setup

Open
#85 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

## 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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.