|
| 1 | +# Agent Beta — The Skeptic: Against Wholesale Adoption of Claude Code Skill Patterns |
| 2 | + |
| 3 | +## 1. What's Already Good — The Evidence Is 246 Skills Strong |
| 4 | + |
| 5 | +Before we start grafting Claude Code's patterns onto this repo, let's acknowledge an inconvenient fact for the Advocate: **the current system is demonstrably working**. There are 246 skills in `skills/`, contributed by a diverse community, covering everything from `game-engine` to `azure-cost-optimize` to `creating-oracle-to-postgres-master-migration-plan`. The system grew from zero to 246 with exactly two required frontmatter fields: `name` and `description`. |
| 6 | + |
| 7 | +That's not a limitation. That's a *design choice*, and it's the right one. |
| 8 | + |
| 9 | +The frontmatter for `web-coder` — a skill with 17 bundled files including HTML templates, CSS, and JavaScript — is four lines: |
| 10 | + |
| 11 | +```yaml |
| 12 | +name: web-coder |
| 13 | +description: '...' |
| 14 | +``` |
| 15 | +
|
| 16 | +The frontmatter for `agent-governance` — a completely different kind of skill with no assets — is the same shape. This uniformity is a strength. A contributor who writes a 200-line `SKILL.md` with detailed instructions and one who writes a 20-line quick reference both face the same onboarding cost: two fields, match your folder name, write a description between 10 and 1024 characters. Done. |
| 17 | + |
| 18 | +The validation in `eng/validate-skills.mjs` reflects this philosophy. It checks name format, description bounds, duplicate names, asset existence, and the 5MB file limit. No field type taxonomies, no category enums, no mode declarations. It does exactly what's needed to maintain quality in an open-source collection and nothing more. The scaffolding script (`eng/create-skill.mjs`) generates a working skill in seconds. The `make-skill-template` skill teaches the AI itself how to create skills. The `repo-architect` agent can validate and scaffold skill structures. These three tools form a complete workflow already. |
| 19 | + |
| 20 | +Adding complexity to this schema doesn't add value proportional to its cost. It adds *friction*. |
| 21 | + |
| 22 | +## 2. Platform Mismatch — Cargo-Culting Claude's Runtime |
| 23 | + |
| 24 | +Let me be blunt about which Claude Code features are cargo-cult candidates: |
| 25 | + |
| 26 | +**`context: fork`** — This is a Claude Code runtime feature that creates a sub-agent with a forked context window. GitHub Copilot doesn't have this execution model. There is no equivalent. Adding a `context` field to SKILL.md frontmatter would be a dead annotation that no runtime reads. |
| 27 | + |
| 28 | +**`disable-model-invocation: true`** — Claude Code uses this to prevent recursive model calls inside a skill. Copilot's skill execution model doesn't expose this toggle. Adopting it would be decorative YAML. |
| 29 | + |
| 30 | +**`user-invocable` / `agent`** — These control whether a Claude Code skill can be triggered by the user vs. only by the agent, and whether it spawns a sub-agent. Copilot skills don't have this invocation taxonomy. A SKILL.md is instructions that the model uses — there's no "agent-only" gating mechanism. |
| 31 | + |
| 32 | +**`${CLAUDE_PLUGIN_DATA}`** — Persistent storage path for Claude Code plugins. Copilot skills are stateless instruction documents. There is no persistent storage API to reference. |
| 33 | + |
| 34 | +**`hooks` (on-demand hooks in skills)** — Claude Code's hooks system lets skills trigger pre/post actions. Our repo already has a separate `hooks/` directory following GitHub Copilot's own hooks specification. Conflating the two systems would be confusing. |
| 35 | + |
| 36 | +**`mode: plan`** — Claude Code's plan mode is a specific operational mode. Copilot has its own planning behaviors that aren't controlled via skill frontmatter. |
| 37 | + |
| 38 | +The Advocate may argue these could be adopted "for future-proofing." But future-proofing against a *different platform's* feature set is just premature abstraction. We follow the Agent Skills open standard at agentskills.io — our future-proofing obligation is to *that* spec, not to Claude's proprietary fields. |
| 39 | + |
| 40 | +## 3. Contribution Barrier Risk — The Cost Nobody Calculates |
| 41 | + |
| 42 | +Here's what the Advocate's proposals look like to a first-time contributor: |
| 43 | + |
| 44 | +**Current experience:** Fork repo → create folder → write SKILL.md with name + description → write instructions → PR. Two required fields. One validation command. Time from idea to PR: 15 minutes. |
| 45 | + |
| 46 | +**Post-"improvement" experience:** Fork repo → create folder → write SKILL.md with name + description + category (pick from 9 options) + model (which one?) + tools (which are valid?) → decide if you need a gotchas section → consider progressive disclosure folder structure → wonder if you need `allowed-tools` → read the expanded contribution guide → PR. Twelve decisions instead of two. |
| 47 | + |
| 48 | +The 78.5% of skills that are just a `SKILL.md` with no assets — 193 out of 246 — tell us something important: **most contributors want to share instructions, not build frameworks**. They're writing a prompt that helps with Spring Boot testing or PostgreSQL optimization. They don't want to categorize it into one of nine buckets or declare its invocation mode. |
| 49 | + |
| 50 | +Every optional-but-encouraged field is a subtle tax on contributors. "Optional" fields that appear in templates, documentation, and linting warnings become *effectively required* through social pressure. I've seen this pattern kill contribution velocity in open-source projects repeatedly. The contributor sees a template with 8 fields, fills in 2, feels like they did it wrong, and either over-engineers their submission or abandons it. |
| 51 | + |
| 52 | +## 4. What We Should NOT Do |
| 53 | + |
| 54 | +**Do not add a category taxonomy.** Nine categories (from Claude Code's system) would immediately trigger debates about where skills belong. Is `azure-cost-optimize` a "cloud" skill or a "devops" skill? Is `playwright-generate-test` a "testing" skill or an "automation" skill? Taxonomies in community repos become governance nightmares. The current system lets the `name` and `description` be the discovery mechanism, and `docs/README.skills.md` auto-generates a searchable catalog. That's sufficient. |
| 55 | + |
| 56 | +**Do not add `allowed-tools` as encouraged.** Most contributors don't know which Copilot tools exist, and the tool surface changes across VS Code, CLI, and JetBrains. Making people declare tools is asking them to understand the platform's internal API surface before they can contribute a skill. |
| 57 | + |
| 58 | +**Do not mandate progressive disclosure folder structures.** Claude Code's pattern of splitting skills into subfolders with increasing detail is an optimization for *their* context window management. It adds structural complexity that makes skills harder to read, harder to review, and harder to maintain. A well-written single SKILL.md with clear headings accomplishes the same goal without the folder overhead. |
| 59 | + |
| 60 | +**Do not add gotchas sections as a structural requirement.** If someone wants to include caveats in their skill instructions, they can write a "## Gotchas" heading. Making it a formal section in the spec is the kind of micro-management that makes contributors feel surveilled rather than empowered. |
| 61 | + |
| 62 | +**Do not introduce sub-agent execution semantics.** This is Claude Code's runtime, not ours. Adding `agent: true` or `context: fork` fields would be literally meaningless in GitHub Copilot's execution model. |
| 63 | + |
| 64 | +## 5. What We SHOULD Consider — Honest Concessions |
| 65 | + |
| 66 | +The Advocate isn't wrong about everything. Three ideas genuinely translate: |
| 67 | + |
| 68 | +**Description-as-trigger is worth documenting.** The principle that a skill's `description` field should clearly signal *when* the AI should invoke it is genuinely good advice. Our current description validation only checks length (10-1024 chars), not quality. We shouldn't add programmatic quality checks — that's subjective — but we *should* update `make-skill-template` and our CONTRIBUTING.md to explicitly coach contributors: "Write your description as a trigger. Don't say 'A skill for X.' Say 'Use when the user needs to X, especially when Y.'" This is a documentation improvement, not a schema change. Zero friction added. |
| 69 | + |
| 70 | +**Context budget awareness deserves a best-practices note.** Claude Code's insight that long skills waste context window space is real for Copilot too. Skills like `web-coder` (17 files) should be thoughtful about what goes into the main SKILL.md vs. reference files. Again, this is guidance, not enforcement. A "Tips for Effective Skills" section in CONTRIBUTING.md costs nothing and helps everyone. |
| 71 | + |
| 72 | +**A lightweight `model` suggestion (optional, not required).** Some skills are genuinely optimized for specific models. The `repo-architect` agent already declares `model: GPT-4.1`. Suggesting (not requiring, not validating) that skill authors *may* note a recommended model in their frontmatter is reasonable — as long as we're clear it's informational, not functional, since Copilot's skill system doesn't gate on this field. One skill (`winmd-api-search`) already uses an optional `license` field, proving the schema tolerates optional additions gracefully. |
| 73 | + |
| 74 | +## 6. The Skill-Building Agent — Probably Overkill, But Let's Be Precise |
| 75 | + |
| 76 | +We already have three tools for creating skills: |
| 77 | + |
| 78 | +1. **`npm run skill:create`** (`eng/create-skill.mjs`) — scaffolds the folder and SKILL.md with proper frontmatter. |
| 79 | +2. **`make-skill-template`** skill — teaches the AI how to create skills, with full template, validation checklist, and troubleshooting. |
| 80 | +3. **`repo-architect`** agent — validates agentic project structures including skills, with explicit SKILL.md validation rules. |
| 81 | + |
| 82 | +A dedicated "skill builder" agent would need to justify its existence against this stack. What would it do that `make-skill-template` doesn't? If the answer is "it would interactively guide the user through filling in 12 frontmatter fields and choosing a category" — then we've just proved my point about over-engineering. |
| 83 | + |
| 84 | +The *only* scenario where a dedicated agent makes sense is if we identify a specific, repeated failure mode in skill contributions that the existing tools don't address. For example: if PR reviews consistently reject skills for poor descriptions, and the `make-skill-template` guidance isn't fixing that, then a focused agent that coaches description writing could help. But that's a scalpel, not a Swiss Army knife. Build the smallest tool that solves the observed problem. |
| 85 | + |
| 86 | +--- |
| 87 | + |
| 88 | +**Bottom line:** Our system attracted 246 community contributions with two required fields and minimal ceremony. That's not a system that needs Claude Code's complexity — it's a system that proves simplicity scales. Adopt the *insights* (better descriptions, context awareness), reject the *infrastructure* (categories, invocation modes, sub-agent semantics, mandatory structure), and protect the low barrier that made this repo successful in the first place. |
0 commit comments