Proposal: Optional requires field for runtime-agnostic skill content portability

[YuhaoLin2005]

Proposal: Optional requires field for LLM-agnostic skill portability

The real problem (not theoretical)

I maintain the same skill — adversarial code review — in two versions:

• Claude Code: uses Agent(subagent_type: "code-reviewer") to spawn reviewers
• Hermes Agent: uses delegate_task() with adversarial prompts

Same process. Same intent. Two completely different tool-invocation syntaxes. Every time I fix a step or improve the prompt, I have to edit two files. Every new runtime adds a third version.

This isn't a future problem. It's a right-now problem with 5+ major AI coding agent runtimes, each with different tool names for the same operations.

What I'm proposing

A lightweight requires field in the SKILL.md frontmatter. That's it. One optional field. The semantics live in a separate companion spec.

---
name: adversarial-review
description: Spawn adversarial subagents to find bugs self-review misses.
requires: [read, review, verify]
version: 2.0.0
---

requires lists which semantic verbs (abstract operations) the skill depends on. It does not name runtime-specific tools. It does not change how agentskills.io works today.

Why requires and not something heavier

• Optional — skills without it work exactly as before
• Backward compatible — YAML parsers ignore unknown fields
• Informational — a runtime that doesn't understand it ignores it. A runtime that does can pre-filter: "this skill needs subagent spawning, which I support."
• One field, no spec bloat — the 10 semantic verb definitions live in a separate companion spec (checkgrow/skill-runtime), not in agentskills.io

The semantic verb standard lives elsewhere

I built a companion specification at checkgrow/skill-runtime with 10 semantic verbs + a mapping table for Claude Code/Hermes/Codex. This is deliberately separate from agentskills.io — agentskills owns the packaging standard. skill-runtime is an optional portability layer.

The requires field is the bridge between them.

What this looks like in practice

A SKILL.md uses {review} instead of Agent(subagent_type: "code-reviewer"):

## Procedure
### 1. Spawn adversarial reviewer
{review} with prompt: "You did NOT write this. Find every bug."

Before loading into the LLM context, a thin adapter (60-line Python script) replaces {review} with the current runtime's native tool call. Claude Code → Agent(subagent_type: "code-reviewer"). Hermes → delegate_task(). Codex → its equivalent.

Relationship to existing fields

• name / description: No change. requires is an additional optional field.
• allowed-tools (Claude Code ecosystem): Complementary. requires declares what the skill needs. allowed-tools constrains what it may use. If both exist, the runtime reconciles them.

Why I think this belongs in agentskills.io

agentskills.io already solves the "write once, use everywhere" problem for skill packaging (directory structure, metadata). But skills that reference runtime-specific tools are only portable on paper — they break when you switch runtimes. The requires field makes the existing portability promise real for skills that need to invoke tools.

Disclosure

This proposal was developed with Claude Code assistance. The semantic verb standard and adapter implementation are in checkgrow/skill-runtime. The real-world problem (two versions of the same skill for different runtimes) is documented in that repo's SPEC.md.

[YuhaoLin2005]

Realized the original proposal didn't explain the "why this helps agentskills.io" clearly enough. Adding that here.

Why requires serves agentskills.io's interests

1. More skills written = larger ecosystem. A skill author writing for Claude Code only reaches Claude Code users. A skill author writing with semantic verbs reaches every runtime. The larger the addressable audience, the more skills get written. agentskills.io is the standard those skills are packaged in — more skills = more adoption of the format you maintain.

2. Standard ownership prevents fragmentation. If cross-runtime portability happens without agentskills.io, someone else will define the convention. Better to own the bridge — a single requires field — than let competing portability standards emerge.

3. Claude Code still wins. The competitive moat isn't a file format. It's model quality. Claude's reasoning advantage is real regardless of whether a skill uses {review} or Agent(subagent_type:"code-reviewer"). A portable skill standard doesn't diminish Claude — it means more developers encounter Claude Code through skills they can actually use.

4. One field, zero risk. requires is optional, backward-compatible, and ignorable. If adoption never materializes, it's harmless metadata. If it does, agentskills.io defined the standard — not a competitor.

5. This is additive to the spec, not a rewrite. The semantic verb definitions and adapter logic live in a separate companion project. requires is just the bridge — the minimum viable connection between the packaging standard you own and the portability layer anyone can implement.

[jonathanhefner]

requires lists which semantic verbs (abstract operations) the skill depends on. It does not name runtime-specific tools. It does not change how agentskills.io works today.

That sounds a lot like the existing compatibility field! 😃

I think it's very useful in cases like yours where tool names aren't reliable (e.g., due to client-side name mangling).

By the way, if you're interested, there are some other discussion threads where semantic tool match has come up. For example, #392 (comment).