docs: clarify how the repo's resource types differ in README - #2517
Open
horner wants to merge 2 commits into
Open
docs: clarify how the repo's resource types differ in README#2517horner wants to merge 2 commits into
horner wants to merge 2 commits into
Conversation
The "What's in this repo" table described every resource type as a generic piece of configuration, which gave newcomers no way to tell them apart or decide which one to reach for. - Add a "When it loads" column. Load timing is the axis that actually separates these: agents/instructions/skills are context, hooks and workflows are execution, plugins are packaging. - Add the missing hooks and workflows rows. The tagline promises six resource types; the table only listed four. - Describe skills as loading in two stages, since only the frontmatter description is resident until the agent opens the file. - Correct the agents row: model is optional, not pinned. - Correct the plugins row: install time is when the package arrives, not when its contents reach the model.
Contributor
|
🟡 Contributor Reputation Check: MEDIUM risk
Maintainers: please review this contributor before merging. |
github-actions
Bot
added
the
needs-review:MEDIUM
| |----------|-------------|---------------|--------| | ||
| | 🤖 [Agents](docs/README.agents.md) | A specialist persona: system prompt + allowed tools/MCP servers + an optional pinned model | When **you** pick it for a conversation | [All agents →](https://awesome-copilot.github.com/agents) | | ||
| | 📋 [Instructions](docs/README.instructions.md) | Coding standards and repo conventions — prose only, no tools | **Automatically**, when a file matches its `applyTo` pattern | [All instructions →](https://awesome-copilot.github.com/instructions) | | ||
| | 🎯 [Skills](docs/README.skills.md) | Task procedures plus bundled scripts, templates, and reference data | **In two stages** — only the frontmatter `description` sits in context; the body and assets load when the agent opens the file | [All skills →](https://awesome-copilot.github.com/skills) | |
| | 🤖 [Agents](docs/README.agents.md) | A specialist persona: system prompt + allowed tools/MCP servers + an optional pinned model | When **you** pick it for a conversation | [All agents →](https://awesome-copilot.github.com/agents) | | ||
| | 📋 [Instructions](docs/README.instructions.md) | Coding standards and repo conventions — prose only, no tools | **Automatically**, when a file matches its `applyTo` pattern | [All instructions →](https://awesome-copilot.github.com/instructions) | | ||
| | 🎯 [Skills](docs/README.skills.md) | Task procedures plus bundled scripts, templates, and reference data | **In two stages** — only the frontmatter `description` sits in context; the body and assets load when the agent opens the file | [All skills →](https://awesome-copilot.github.com/skills) | | ||
| | 🪝 [Hooks](docs/README.hooks.md) | Shell commands wired to coding-agent lifecycle events like `sessionStart` or `preToolUse` | Never — hooks *run*, they don't enter the context window | [Browse hooks →](hooks/) | |
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.
Suppressed comments (2)
README.md:25
- This collapses the skill specification's three disclosure levels into two. Discovery metadata includes both
nameanddescription; theSKILL.mdbody loads when the skill is activated, while bundled resources are loaded separately only as needed—not all when the agent opensSKILL.md. Since this row is intended to explain routing and context cost, please describe those stages separately.
| 🎯 [Skills](docs/README.skills.md) | Task procedures plus bundled scripts, templates, and reference data | **In two stages** — only the frontmatter `description` sits in context; the body and assets load when the agent opens the file | [All skills →](https://awesome-copilot.github.com/skills) |
README.md:28
- The repository's plugin contract is broader than agents and skills:
AGENTS.md:12,126explicitly includes commands, and existing manifests can also register integrations such asmcpServers(plugins/awesome-copilot/.github/plugin/plugin.json:17-25). Restricting both cells to agents/skills leaves these bundled components out of the taxonomy and gives them no activation rule.
| 🔌 [Plugins](docs/README.plugins.md) | Installable bundles of related agents and skills — packaging, not a new capability | **At install time only** — the bundled agents and skills then load by their own rules above | [All plugins →](https://awesome-copilot.github.com/plugins) |
aaronpowell
reviewed
Aug 4, 2026
| | 🎯 [Skills](docs/README.skills.md) | Task procedures plus bundled scripts, templates, and reference data | **In two stages** — only the frontmatter `description` sits in context; the body and assets load when the agent opens the file | [All skills →](https://awesome-copilot.github.com/skills) | | ||
| | 🪝 [Hooks](docs/README.hooks.md) | Shell commands wired to coding-agent lifecycle events like `sessionStart` or `preToolUse` | Never — hooks *run*, they don't enter the context window | [Browse hooks →](hooks/) | | ||
| | ⚙️ [Workflows](docs/README.workflows.md) | Agentic workflows that run Copilot in GitHub Actions on a schedule or repo event | Not in your editor — these execute in CI | [Browse workflows →](workflows/) | | ||
| | 🔌 [Plugins](docs/README.plugins.md) | Installable bundles of related agents and skills — packaging, not a new capability | **At install time only** — the bundled agents and skills then load by their own rules above | [All plugins →](https://awesome-copilot.github.com/plugins) | |
Contributor
There was a problem hiding this comment.
The "When it loads" here isn't accurate as a plugin itself isn't "loaded", it's the items within the plugin, the agents/skills/etc. that are loaded using the rules outlined above.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
The What's in this repo table is the first thing a newcomer reads, but it described all five listed resource types as interchangeable-sounding bits of configuration. Nothing in it answered the question people actually arrive with: which of these do I want, and why?
Two concrete gaps:
What changed
Added a "When it loads" column. Load timing turns out to be the axis that genuinely separates these, and once it's visible the categories fall out on their own:
That grouping was implicit before. It's now readable straight off the table.
Added the missing hooks and workflows rows, closing the gap with the tagline.
Fixed three accuracy problems in the existing rows:
descriptionstays resident, and the body and bundled assets load when the agent opens the file. This matters practically: thedescriptionis doing all the routing work, which is whyAGENTS.mdrequires it to be 10–1024 characters.modelis optional perAGENTS.md(strongly recommended, not required), and many agents in the collection omit it.Notes
awesome-copilot.github.com/hooksor/workflowspages referenced anywhere in the repo or underwebsite/, so I didn't want to invent URLs. Happy to swap them in if those pages exist.README.mdis hand-authored.eng/update-readme.mjsonly splices between the## 🌟 Featured Pluginsand## MCP Servermarkers, neither of which is present here — so the build doesn't manage this table.npm run build; it produced no changes beyond this edit.eng/fix-line-endings.sherrors on macOS (sed: invalid command code) because it uses GNUsed -isyntax. It made no changes. VerifiedREADME.mdis LF-only independently. Flagging as a possible separate issue.