Proposal: Expand AGENT.md scope to cover sub-agents + enable interoperable linking with skills, hooks, and rules #149
Description
Summary
Hi AGENTS.md maintainers and community — thank you for the work on AGENT.md. I’m opening this issue as an open invitation to discuss evolving AGENT.md toward a broader, industry-aligned standard.
My motivation: agent ecosystems are rapidly adding more “configuration surface area” beyond a single instruction file — e.g., sub-agents, skills, hooks, and rules/policies (Cursor and others already expose these concepts). Right now, these efforts across communities look somewhat independent, and I think we’ll get better outcomes by coordinating.
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. At the same time, we should clearly separate roles and responsibilities between:
- what belongs in a sub-agent definition (persona, scope, delegation boundaries, defaults), and
- what belongs in a skill (a reusable capability / tool contract),
so the system stays maintainable as it grows.
What I believe AGENT.md could enable next
As far as I understand, AGENTS.md currently focuses on standardizing the AGENT.md file so different AI agents can load it consistently. That’s already valuable. I’d like to discuss whether we can extend the scope in two directions:
1) Broaden scope to include sub-agents
A natural extension is describing how a repository can declare:
- sub-agent definitions (names, responsibilities, allowed actions, default prompts)
- how sub-agents are discovered and loaded
- how sub-agents reference skills/rules/hook policies
This could be done in a backward-compatible way (e.g., optional sections in AGENT.md, or a companion file like AGENTS/, or a simple directory convention).
2) Move toward an industry-level “plugin-like” packaging model
We may need something similar in spirit to custom Claude Code plugins, but at an industry level:
- a way to bundle related resources (sub-agents + skills + rules + hooks + metadata)
- versioning, isolation, reproducible installs, and governance controls (signing/verification, publisher identity)
- interoperable across IDE/CLI tooling (Cursor, Claude Code, etc.)
Not prescriptive on the mechanism — but I think the outcome matters: reliable distribution and lifecycle management without config sprawl.
Concrete discussion questions
- What is in-scope for AGENTS.md long-term: only
AGENT.md, or a broader “agent configuration contract”? - If we include sub-agents, what is the minimal additional schema that provides value without overreaching?
- How should
AGENT.md(or related conventions) express dependencies/links (sub-agent → skills; repo policies → hooks/rules)? - Would maintainers be open to a joint working group / cross-repo discussion with AgentSkills (and others) to avoid diverging standards?
Why I’m raising this now
In practice, I’m seeing configuration fragmentation emerge quickly:
- global folders like
~/.toolname/...become messy and hard to audit - resources drift out of sync across teams and machines
- governance teams want consistent policy guardrails, but distribution is ad-hoc
A small amount of coordination now could prevent a lot of painful incompatibilities later.
References / context
- AGENTS.md repo: https://github.com/agentsmd/agents.md
- Claude Code plugins: https://code.claude.com/docs/en/plugins
- Cursor concepts: skills / subagents / rules / hooks
- AgentSkills ecosystem: https://github.com/agentskills/agentskills
Thanks for considering — happy to draft a concrete proposal (minimal schema / conventions) if there’s interest.
Links
- Proposal: Standardize interoperability between sub-agents and skills (plus hooks/rules) and explore plugin-like packaging across ecosystems agentskills/agentskills#129
- 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