This project uses "skill group" in a narrow operational sense. It is not trying to replace Agent Skills, MCP, or plugins.
A skill group is an operating profile for local SKILL.md directories.
Use agent-skill-groups when an agent workstation already has many skills and
you need a repeatable way to keep only the right scenario profile active. Use
MCP when the agent needs to call a tool or read an external resource through the
Model Context Protocol. Use a plugin when a runtime supports installing a bundle
that may contain skills, MCP servers, apps, or metadata.
| Concept | What it is | Typical files | Runtime effect |
|---|---|---|---|
| Agent Skill | Instructions and optional assets for one capability. | SKILL.md, references, scripts, assets. |
Teaches the agent when and how to use a capability. |
| Skill group | A named scenario profile made from multiple skills. | groups.json. |
Emits current-session load/unload packs and can move selected skill directories active or disabled. |
| MCP server | A protocol server that exposes callable tools or resources. | Server code and MCP config. | Gives the agent live tool/resource calls. |
| Plugin | A runtime-specific bundle. | Manifest plus skills, MCP config, or app files. | Installs or exposes capabilities according to that runtime. |
Large skill libraries become noisy when every skill is always active. A normal work session may need research and browser skills, while a CTF session may need web exploitation or reverse engineering skills. A design task may need Figma and frontend skills. Loading all of them all the time makes instruction selection harder to reason about.
agent-skill-groups keeps a small core profile active and parks specialized
skills in a managed disabled pool. A task can then load ctf-web,
figma-design, research, or another scenario profile, and later return to
core.
Loading has two layers. session-load reads a group from active roots or the
disabled pool and prints a context pack for the already-running conversation.
session-unload prints a stop pack for the same conversation. profile
changes filesystem placement only when native runtime discovery should change
after a reload, rescan, or new session.
agent-skill-groups does not edit skill contents, run MCP servers, or replace a
runtime's plugin installer. It manages filesystem placement for skills, can
render current-session load/unload packs, and writes an AGENTS.md or
CLAUDE.md memory block so future agent sessions know which groups exist and
how to load or stop them.
Run the reversible demo before touching a real skill library:
agent-skill-groups demo --jsonThe demo creates sample active and disabled skill roots, writes groups.json
and an agent memory block, switches a profile, restores the backup, and reports
ok: true when the workflow succeeds.
Use a skill group when the problem is "which local skills should be visible for this task?"
Use MCP when the problem is "the agent needs to call this external tool or data source."
Use a plugin when the problem is "this runtime needs an installable bundle of capabilities."
Use a plain Agent Skill when the problem is "the agent needs reusable instructions for one capability."