Optional plugin-level agent orientation file (PLUGIN.md / plugin-root AGENTS.md)

[MinTALI]

Optional plugin-level agent orientation file (PLUGIN.md / plugin-root AGENTS.md)

Problem

Agent Plugins v1 packages skills (skills/*/SKILL.md) and MCP (mcp.json) well, but there is no portable, plugin-scoped surface for:

• what the plugin as a whole is for
• when to use it
• how its skills and MCP tools relate
• how an agent should interact with the package without reading every file

Today that story is split awkwardly:

• plugin.json description — too short for workflows; closed schema
• SKILL.md — per-skill only; no cross-cutting plugin narrative
• mcp.json — startup/config, not purpose or orchestration
• README.md — human-facing; not discovered by clients
• Repo AGENTS.md in this project — contributor guidance for the spec, not a plugin convention

There is no shared convention for plugin-level agent orientation, so authors may invent ad-hoc root docs with conflicting names and purposes. Install/enable UX remains client-managed and is intentionally outside the v1 portable core.

Who hits this

• Plugin authors shipping multi-skill + MCP packages who need one orientation entrypoint for agents
• Client implementers that want a predictable optional file to load into catalogs / on enable
• Agents that otherwise guess from filenames and a one-line description

Why discuss in the portable spec (vs client-only)

Without a shared convention, every client invents a different path (INSTALL.md, AGENTS.md, docs/usage.md, and so on). A single optional informative convention (even before anything normative) improves authoring and eventual discovery without expanding install/permission semantics.

This is not proposing install scripts, registry URLs, trust, or secrets. Those stay client-managed / future considerations.

Proposal (preferred framing)

Add an optional, informative plugin-root orientation file, with one recommended name:

1. PLUGIN.md (preferred — clear, no clash with this repo’s contributor AGENTS.md), or
2. Plugin-root AGENTS.md (familiar to agents; needs clear disambiguation from contributor docs)

Suggested sections (non-normative authoring guide first):

1. Purpose / when this plugin applies
2. Component map (skills ↔ MCP; preferred order)
3. Interaction rules (pointers into SKILL.md / MCP tools — don’t duplicate bodies)
4. Prerequisites / env (pointers only)
5. Non-goals / out of scope

Zero-spec alternative to try first: a meta-skill at skills/overview/SKILL.md (already discoverable). This discussion should weigh that vs a dedicated root file.

Normative vs informative

Start as authoring guidance on agent-plugins.org (similar to marketplace docs in #41 / Discussion #42).

Consider a normative fixed path only if:

• at least two clients commit to load it, and
• load/failure isolation rules are clear (optional file; missing = OK)

Open questions

1. Is the real need plugin-level orientation, or better skill-authoring guidance?
2. Why isn’t a root meta-skill enough?
3. Load semantics: never (docs-only) / on enable / always into agent context?
4. Best filename: PLUGIN.md vs AGENTS.md vs OVERVIEW.md?
5. Relationship to Agent Skills progressive disclosure and context budgets?
6. Any client implementers ready to adopt an optional load path?

Ask

Maintainers / implementers: is an optional plugin-level orientation file worth an informative convention now? If yes, which filename and load expectations are acceptable without growing the v1 floor?