Proposal: Standardize interoperability between sub-agents and skills (plus hooks/rules) and explore plugin-like packaging across ecosystems

[yu-iskw]

Summary

Hi AgentSkills maintainers and community — thank you for building AgentSkills and publishing a clear specification. I’m opening this issue as a constructive request to discuss cross-community alignment, particularly with AGENTS.md, because I think we need industry-level standards that go beyond any single tool or repository.

Right now, the ecosystem momentum is strong but somewhat isolated: skills standards are advancing, while other core primitives (sub-agents, hooks, rules/policies, repo-level agent instructions) are evolving in parallel in different communities and products.

The most important point

Today, sub-agents, skills, hooks, and rules should be seamlessly linked.
For instance, a sub-agent should be able to use agent skills. And to keep things maintainable at scale, we should clearly separate roles and responsibilities:

• Sub-agent definition: responsibilities, delegation boundaries, persona/intent, default behavior
• Skill definition: reusable capability contract (inputs/outputs), tool integration, constraints
• Hooks / rules: audit + guardrails + policy enforcement

If we treat these as independent, we risk fragmentation; if we define clear contracts, we get composability.

What I’m proposing for AgentSkills discussions

1) Define a standard linking model: sub-agent → skills

Could AgentSkills either:

• define a lightweight, tool-agnostic reference mechanism (IDs, namespaces, version constraints), or
• provide guidance on how external “agent definitions” can declare skill dependencies in a compatible way?

This doesn’t require AgentSkills to own sub-agent specs — but a small contract for referencing skills from sub-agents would unlock interoperability.

2) Expand the conversation to include hooks and rules as first-class companions

Many real deployments require:

• audit hooks (for logging, approvals, policy checks)
• rules/policies (repo/org defaults, restrictions)

It would be useful to agree on:

• where these live (repo-local vs org-managed)
• how they’re distributed and versioned
• how they compose with skills (e.g., a skill may declare policy requirements)

3) Explore industry-level “plugin-like” packaging (similar in spirit to Claude Code plugins)

We may need a packaging/distribution story that bundles:

• skills
• sub-agents
• hooks
• rules/policies (including repo instruction files like AGENT.md)
• metadata (publisher, version, signatures)

This would address lifecycle pain:

• isolation (avoid messy global config sprawl)
• install/update/rollback deterministically
• governance (trusted publishers, audit trails)

Not asking AgentSkills to solve everything — but asking whether the community is open to collaborating on a shared direction with AGENTS.md and others.

Concrete questions

1. Would AgentSkills maintainers be open to specifying a standard identifier / namespacing / versioning approach that sub-agents can reference?
2. Is there appetite to publish a short “Best Practices” doc on separation of concerns: sub-agents vs skills vs policies?
3. Would you be open to a joint cross-repo discussion (AgentSkills + AGENTS.md) to align on interoperability and packaging?

References / context

• AgentSkills repo: https://github.com/agentskills/agentskills
• AgentSkills spec/resources:
  • https://agentskills.io/home
  • https://agentskills.io/specification
  • https://agentskills.io/integrate-skills
• AGENTS.md: https://github.com/agentsmd/agents.md
• Claude Code plugins (packaging inspiration): https://code.claude.com/docs/en/plugins
• Cursor concepts (real-world primitives in use today):
  • https://cursor.com/docs/context/skills
  • https://cursor.com/docs/context/subagents
  • https://cursor.com/docs/context/rules
  • https://cursor.com/docs/agent/hooks

Thanks — happy to help draft a concrete interoperability proposal (IDs + references + minimal manifest) if the community is interested.

Links

• Proposal: Expand AGENT.md scope to cover sub-agents + enable interoperable linking with skills, hooks, and rules agentsmd/agents.md#149
• https://forum.cursor.com/t/agent-plugins-isolated-packaging-lifecycle-management-for-sub-agents-skills-hooks-rules-incl-agent-md-across-cursor-ide-cli/151250

[MaxKless]

Big +1 on exploring plugin-like packaging across ecosystems. Though having a single .agents/skills folder will already help: #15

[yu-iskw]

Cursor supports something like that.

https://cursor.com/blog/marketplace

[pjt222]

Implementation perspective: 284 skills, 60 agents, 11 teams

We maintain development-guides, a library with 284 skills across 50 domains, 60 agent definitions, and 11 team compositions built on the agentskills standard. We shared this in discussion #177. After running this at scale for several months, we have concrete experience with the linking and composition problems this discussion raises.

What we do today

Our linking model uses three layers, all with bare string IDs and no version constraints:

1. Agent → Skills: Each agent declares a skills: list in YAML frontmatter. Bare slugs (commit-changes, write-testthat-tests) that resolve to skills/<slug>/SKILL.md by convention.
2. Team → Agents: Each team declares members[] with agent IDs, roles, responsibilities, and a coordination pattern (hub-and-spoke, sequential, parallel, timeboxed, adaptive, reciprocal).
3. Skill → Skills: A "Related Skills" prose section at the bottom of each SKILL.md. Informational only, not machine-parseable.

We also have a default_skills mechanism in our agent registry — two skills (meditate, heal) that are automatically inherited by all 60 agents without being listed in their frontmatter. This is effectively skill inheritance.

Where bare-slug linking breaks down

At 284 skills and 60 agents, we hit real friction:

• No validation of references. Nothing verifies that a skill ID in an agent's skills: list corresponds to an actual skills/<id>/SKILL.md. Broken references are silent until an agent tries to follow a skill that doesn't exist.
• Rename cascading. When we renamed a skill, we had to update every agent and team that referenced it, plus the registry, plus symlinks. Four or more files per rename.
• No required vs. optional distinction. An r-developer agent listing 27 skills doesn't distinguish "this agent cannot function without write-roxygen-docs" from "this agent can optionally use format-apa-report if the context calls for it."
• Cross-repo sharing is copy-paste. No import mechanism means skills cannot be shared across projects without duplication.

What we'd want from a standard interoperability contract

1. Namespaced identifiers. Something like org/skill-name or repo/skill-name so that two libraries can each have a code-review skill without collision. The current spec's name field is locally unique but not globally unique.

2. Version constraints in references. Agents should be able to express requires: commit-changes >= 1.0 rather than just listing a bare slug. This makes skill updates safe — you know which agents might break.

3. Dependency types. At minimum: required (agent cannot function without this skill), optional (agent can use this skill when relevant), and default (inherited by all agents of a certain scope). Our default_skills pattern works well and should be expressible in the standard.

4. Machine-readable cross-references in skills. Our "Related Skills" section is prose. It should be frontmatter (e.g., related-skills: with typed relationships: prerequisite, complementary, alternative). This would enable tooling to build dependency graphs, detect orphans, and suggest skill chains.

5. A validation command. The skills-ref validate tool currently checks frontmatter. It should also validate that all skill references from agents (and agent references from teams) resolve to actual files. Reference integrity checking.

What packaging/distribution should look like

We think the plugin-like bundle proposal is the right direction, but with some nuance from our experience:

• A bundle should be: skills + agents + a manifest. Not just skills. Our agent definitions (persona, tools, skill bindings) are essential for multi-agent workflows. A skill without an agent that knows how to use it is less useful.
• Teams are a higher-order composition. They probably shouldn't be in the bundle — they're deployment-time configuration, not distribution-time artifacts. But the standard should acknowledge that agents compose into teams.
• The manifest should be a lockfile, not just metadata. It should record the exact versions of all skills and agents, their hashes, and the resolution of all references. Like package-lock.json or renv.lock.
• Discovery should work both locally and remotely. Our current filesystem-based discovery (scan skills/ directories) works locally. A registry URL in the manifest would enable remote resolution without requiring a marketplace.

How AGENTS.md relates

AGENTS.md and agentskills serve different purposes and are complementary:

• AGENTS.md = project-level guidance ("here's how to work on this codebase")
• SKILL.md = capability procedure ("here's how to do this task anywhere")
• Agent definitions = persona binding ("here's who does what with which skills")

A standard interoperability contract should acknowledge all three layers. The linking mechanism this discussion proposes sits between agents and skills — it's the dependency contract layer.

Summary of our recommendations:

Feature	Priority	Rationale
Namespaced identifiers	High	Required for cross-repo sharing without collisions
Version constraints in references	High	Required for safe skill updates and distribution
Dependency types (required/optional/default)	Medium	Distinguishes critical bindings from contextual ones
Machine-readable skill cross-references	Medium	Enables tooling, graph visualization, orphan detection
Reference validation in skills-ref	Medium	Catches broken links before runtime
Bundle manifest with lockfile semantics	Medium	Enables reproducible distribution
Agent definition as part of the standard	Lower	Useful but may be scope creep for agentskills v1

Happy to share more detail on any of these from our implementation experience.

[ianscrivener]

@yu-iskw & @pjt222
Both of you have excellent ideas, very solid. I see where you are coming from. While I align with you from a technical point of view, I feel I differ from you philosophically.

Metcalfe's law; "the _ value or influence of a _ network is proportional to the square of the number of connected users of the system...". IMO this spec should not be so tight that it presents a barrier for everybody to use and adopt it universally. Quantity of spec adopters beats quality of spec hands down.

Essential, work around available, nice-to-have, bonus points, v2...

IMO dependencies are essential for the spec - you cannot run a skill that requires python unless you have python installed.

Maybe a ratcheted approach;

1. Mandatory: software dependencies in the front matter - eg sw_required: ["3.11>=python=<4","python:torch>=2.0","curl"]
2. Optional: requirements.txt, pyproject.yaml, uv.lock in scripts

Namespaces: github.io/fred_smith/foo_skill:51a8d5e - would that work?

[jingchang0623-crypto]

Great proposal on cross-ecosystem interoperability!

I've been working on cost optimization for Agent sessions — a different angle but equally important for production deployments. When agents run skills at scale, token costs can balloon quickly (I've seen 3x waste from duplicate tool calls alone).

We just open-sourced openclaw-agent-cost-optimizer which:

• Detects duplicate tool calls and suggests caching
• Analyzes context efficiency (input vs output token ratio)
• Estimates costs across Claude/GPT-4/DeepSeek/Gemini
• Generates actionable optimization reports

The tool fits naturally into the "audit + observability" layer you mentioned for hooks/rules. Would love to collaborate on standardizing cost/efficiency metrics as part of the skills spec.

Related to your point on "plugin-like packaging" — having a standard cost_profile or resource_limits field in skill manifests would help platforms optimize execution budgets.

🦞 By 妙趣AI (miaoquai.com)

[oliviacraft]

Really important discussion. The interoperability gap is real — most teams working with AI coding agents today have rules and context defined in one format that does not travel to other tools.

From practical experience building and testing rules across Claude Code, Cursor, Windsurf, Gemini CLI, and GitHub Copilot:

The content is almost always portable; the container is not.

A rule like "never use session.query() in SQLAlchemy 2.0, use select()" works identically in CLAUDE.md, .cursorrules, .windsurfrules, GEMINI.md, and .github/copilot-instructions.md. The semantics are the same. The only barrier is that teams write it once for their primary tool and never port it.

A practical step toward the standard you are proposing:

• Core rules (anti-patterns, architectural constraints, test conventions) should live in a tool-neutral format and get compiled to each container format
• YAML or structured markdown frontmatter could mark a rule as applies_to: [claude, cursor, gemini, copilot]
• A CLI tool (rules compile or similar) generates the per-tool files

We have been publishing multi-format rule packs (same rules, all five formats) as a stopgap while the ecosystem figures this out: https://oliviacraftlat.gumroad.com/l/skdgt — the friction of maintaining five files is real and is exactly the problem a standard would solve.

Would be glad to contribute to a draft spec if this moves forward.

[stbenjam]

Today, a team that wants to distribute reusable agent context across repositories or organizations has to deal with multiple content types beyond skills:

• Commands (commands/*.md) - slash commands that define agent workflows, on par with skills in terms of behavioral impact
• Rules/Instructions - project or user-level constraints that shape agent behavior (e.g., "always run tests before committing", "never use any in TypeScript")
• Hooks - shell commands triggered by agent lifecycle events (tool calls, model responses, etc.). These execute code on the user's machine, making them arguably the highest-risk content type
• MCP server configurations - server definitions that extend agent capabilities with external tools and data sources
• Instruction files (CLAUDE.md, AGENTS.md, GEMINI.md) — project-wide context that plugins and packages often need to ship

Some are moving away from commands, and to a certain extent it makes sense that you could just turn skills into deterministically invoked / commands themselves. The rest though don't have a clear replacement in skills.

I am really happy with how apm is dealing with managing shipping all the context around between various tools, but it would be great to have AgentSkills expanded to include the use cases above so there was some kind of standard (TBH, like AgentSkills.io, Claude's structure for these things makes a lot of sense and could just be adopted).

All of these end up in an agent's context window or execute on the user's machine. But only skills have a spec. Everything else is ad hoc and vendor-specific.