Skip to content

go165/agent-skill-groups

BranchesTags

Repository files navigation

agent-skill-groups

CI Release License: MIT

Stop loading every agent skill for every task. Switch skills by runtime and scenario.

agent-skill-groups is an agent skill groups manager, GitHub agent-skill-group manager, GitHub skill-group manager, and cross-runtime current-session loader for Agent Skills-style SKILL.md directories. It also provides a filesystem profile layer for runtimes that rescan native skill roots. It supports OpenAI Codex, Claude Code, OpenCode, and generic local skill roots.

If you searched for a GitHub skill-group tool, GitHub agent skill group manager, or local Agent Skills profile manager, this project focuses on that exact operations problem.

If you use coding agents with many local skills, the obvious failure mode is not installation. It is long-term operations:

  • too many skills compete for attention in every session
  • startup context gets noisier as your skill library grows
  • specialized CTF, Figma, paper, or media workflows stay loaded when you are not using them
  • manually moving skill folders works once, then becomes hard to remember and hard to repeat

agent-skill-groups gives you a lightweight current-session skill group loader for local skills. Keep a small always-on core, park everything else in a managed disabled pool, and load only the group you need for the current job. When native runtime discovery also needs to change, use the separate filesystem profile path.

Documentation

For a deeper Codex install check on a machine with Codex app-server support, run the live direct loader probe against the temporary self-test roots:

agent-skill-groups self-test --include-codex-live --json

This adds codex-activate --direct and codex-clear checks to the normal self-test. It still uses a generated demo layout rather than your real skill roots.

Search Keywords

GitHub agent skill group, GitHub agent-skill-group, GitHub skill-group, GitHub skills group, agent-skill-groups manager, agent skill groups manager, agent-skill-group, Agent Skills manager, AI agent skill manager, skill manager, skills manager, OpenAI Codex skills manager, Claude Code skills manager, OpenCode skills manager, SKILL.md organizer, SKILL.md manager, Agent Skills profile manager, runtime-aware skill profiles, scenario-based skills loader, current-session skill loader, current conversation skill loader, local AI agent skills repository organizer, Codex skill groups, Claude Code skill groups, OpenCode skill groups, skill-group, skill groups, agent skill groups.

Search alias repositories for users who do not know the canonical package name:

If the same GitHub search text still shows unrelated repositories first, see the search diagnostics page. GitHub can tokenize agent-skill-group as separate agent, skill, and group terms, then rank older or more active repositories ahead of a newer exact-name repository. The discovery JSON includes rankingDiagnostics so you can see how many non-target repositories and transparent aliases are ahead of the canonical repository for a given query. Reports show both Project family rank and Canonical rank: project family is the best rank across the main repository and transparent alias repositories, while canonical rank is only go165/agent-skill-groups.

The project is also being submitted to relevant Agent Skills directories rather than relying only on alias repositories. Current external submissions and live index entries are tracked in the ecosystem map.

For users comparing Agent Skills managers, see the comparison page. agent-skill-groups focuses on scriptable current-session skill loading, scenario profiles, JSON output, backups, and agent memory snippets; GUI skills managers, MCP servers, and plugins solve adjacent but different problems.

The Pitch

Agent skills are powerful, but a large always-on skill set becomes an operations problem. You do not need Figma implementation skills during a crypto CTF. You do not need twenty web security playbooks while polishing a paper. You do not need your whole skill library in every prompt budget.

This project turns a pile of skills into on-demand groups:

  • core for daily work
  • figma-design for Figma-to-code work
  • ctf-web, ctf-crypto, ctf-pwn-reverse, ctf-forensics-osint, or ctf-all for challenge work
  • academic-optics for literature, paper review, and optics workflows
  • desktop-media for WinUI and local video production

There are two load paths, and current-conversation loading is the default operating path:

  • session-load prints a current-conversation context pack from the selected group, including skills parked in the disabled pool. Paste or feed that output back to the running agent and it can use the group immediately.
  • session-unload prints a current-conversation stop pack for a group. It tells the running agent to stop applying that group from that point forward.
  • profile switches the local filesystem state for native runtime discovery. Use it when you also want the runtime's built-in skill list to change after a reload, rescan, or new session.

Codex native skill discovery is a separate runtime capability. On Codex CLI 0.140.0, codex debug prompt-input can regenerate the model-visible native skills block from the current filesystem, and the experimental app-server schema contains skills/list with forceReload. A user-space tool still cannot erase or replace a native skills block that has already been sent to the model in the current running CLI conversation. Use codex-native --json to detect what your installed Codex exposes, then use session-load/session-unload for immediate current-conversation behavior.

For Codex hosts that consume app-server skill metadata, codex-refresh performs the strongest native path this tool can drive today: it applies the selected filesystem profile and immediately calls app-server skills/list with forceReload, then reports which requested skills appeared in the refreshed native scan. If Codex rejected a skill file during that scan, the JSON output includes the app-server errors entries so the profile can be fixed without guessing.

For the closest single-command Codex workflow, use codex-activate --direct: it updates Codex app-server skills/extraRoots live, calls skills/list forceReload, and prints a current-session context pack so the same conversation can use the group immediately.

codex-direct exposes the lower-level native path by itself. It builds a temporary extra root for the requested group and updates Codex app-server skills/extraRoots before calling skills/list forceReload, without printing a session pack.

Direct extra roots are isolated by config and group set, and each root carries a small manifest so stale links from a previous group are removed before the next native scan. JSON output also includes nativeNameAliases when Codex loaded a skill through its declared name: instead of the directory name. This matters for multilingual or renamed skills such as a directory called brainstorming whose native skill name is localized.

codex-clear is the matching live unload path for Codex direct mode. It sends an empty skills/extraRoots list, calls skills/list forceReload, and can also print a current-session unload pack for the group you are done using. If the refreshed native scan still sees requested group skills from another Codex skill root, JSON output reports them under remainingManagedGroupSkills with a source such as other-native-root.

Because Codex app-server skills/extraRoots is live process state, do not run two direct activation probes in parallel against the same Codex instance. Run codex-activate --direct, inspect the result, then run the next activation or codex-clear.

Supported Runtimes

The Python CLI supports runtime presets:

python -m agent_skill_groups runtimes
python -m agent_skill_groups status --runtime codex
python -m agent_skill_groups status --runtime claude-code
python -m agent_skill_groups status --runtime opencode
python -m agent_skill_groups status --runtime generic

See docs/RUNTIMES.md for root layouts and customization.

How It Works

The manager moves skill directories between active roots and a disabled pool:

  • Codex preset: $HOME/.codex/skills, $HOME/.agents/skills
  • Claude Code preset: $HOME/.claude/skills
  • OpenCode preset: $HOME/.config/opencode/skills, $HOME/.claude/skills
  • Generic preset: $HOME/.agents/skills

The grouping model lives in JSON:

  • one skill can belong to multiple groups
  • groups can include other groups
  • protected skills, such as .system, stay active
  • profiles can enable one scenario and disable other managed skills

No skill contents are modified.

Install

Install from the latest release or GitHub:

pipx install git+https://github.com/go165/agent-skill-groups.git
agent-skill-groups runtimes

See docs/INSTALL.md for pip, release wheel, source, and PowerShell options.

For source checkout:

git clone https://github.com/go165/agent-skill-groups.git
cd agent-skill-groups

Use the cross-platform Python CLI directly:

python -m agent_skill_groups --help
python -m agent_skill_groups init --runtime codex --dry-run

You can override the default config path with:

export AGENT_SKILL_GROUPS_CONFIG=/path/to/groups.json

Or install the PowerShell compatibility script:

New-Item -ItemType Directory -Force "$HOME\.codex\scripts" | Out-Null
New-Item -ItemType Directory -Force "$HOME\.codex\skill-groups" | Out-Null

Copy-Item ".\scripts\agent-skill-groups.ps1" "$HOME\.codex\scripts\agent-skill-groups.ps1"
Copy-Item ".\examples\groups.example.json" "$HOME\.codex\skill-groups\groups.json"

Edit $HOME\.codex\skill-groups\groups.json to match your installed skill directory names.

Universal Workflow

Fastest proof that the CLI can run a reversible local Agent Skills workflow:

agent-skill-groups demo --json

This creates a small sample repository, runs init, backup, plan, session-load, session-unload, memory --write, profile, and restore, then reports the final checks. See examples/demo-output.json for the expected scriptable output shape.

# 1. Inspect a complex skill repository
python -m agent_skill_groups analyze --runtime codex --json

# 2. Ask for suggested groups from SKILL.md names/descriptions
python -m agent_skill_groups suggest --runtime codex

# 3. Generate an initial groups.json from the current repository
python -m agent_skill_groups init --runtime codex --output groups.json

# 4. Diagnose missing, ungrouped, malformed, and duplicate-description skills
python -m agent_skill_groups doctor --config groups.json --runtime codex

# 5. Preview a profile switch
python -m agent_skill_groups plan --config groups.json --runtime codex ctf-web

# 5a. Load a group into the current conversation without moving directories
python -m agent_skill_groups session-load --config groups.json --runtime codex ctf-web

# 5b. Stop applying that group later in the same conversation
python -m agent_skill_groups session-unload --config groups.json --runtime codex ctf-web

# 5c. Codex-only: update extraRoots live, force native metadata, and print the session pack
python -m agent_skill_groups codex-activate --config groups.json --runtime codex --direct ctf-web

# 5d. Codex-only: lower-level direct native refresh without a session pack
python -m agent_skill_groups codex-direct --config groups.json --runtime codex ctf-web

# 5e. Codex-only: clear direct extraRoots live and print an optional unload pack
python -m agent_skill_groups codex-clear --config groups.json --runtime codex ctf-web

# Optional: generate persistent agent instructions
python -m agent_skill_groups memory --config groups.json --runtime codex
python -m agent_skill_groups memory --config groups.json --runtime codex --write AGENTS.md

# Optional: inspect exact skill state by group
python -m agent_skill_groups status --config groups.json --runtime codex --details

# Optional: check GitHub search and Pages discovery from any OS
python -m agent_skill_groups discovery --json

# 6. Back up state before moving directories
python -m agent_skill_groups backup --config groups.json --runtime codex

# 7. Switch profile
python -m agent_skill_groups profile --config groups.json --runtime codex ctf-web

PowerShell Usage

# List scenario groups
powershell -ExecutionPolicy Bypass -File "$HOME\.codex\scripts\agent-skill-groups.ps1" -Action list

# Show active/disabled counts per group
powershell -ExecutionPolicy Bypass -File "$HOME\.codex\scripts\agent-skill-groups.ps1" -Action status

# Load a group into the current Codex conversation without moving directories
powershell -ExecutionPolicy Bypass -File "$HOME\.codex\scripts\agent-skill-groups.ps1" -Action session-load -Group ctf-web

# Stop applying a group later in the current Codex conversation
powershell -ExecutionPolicy Bypass -File "$HOME\.codex\scripts\agent-skill-groups.ps1" -Action session-unload -Group ctf-web

# Codex-only: live direct load without moving directories
powershell -ExecutionPolicy Bypass -File "$HOME\.codex\scripts\agent-skill-groups.ps1" -Action codex-activate -Direct -Group ctf-web

# Codex-only: live clear direct extraRoots and emit an unload pack
powershell -ExecutionPolicy Bypass -File "$HOME\.codex\scripts\agent-skill-groups.ps1" -Action codex-clear -Group ctf-web

# Enable a group without disabling others
powershell -ExecutionPolicy Bypass -File "$HOME\.codex\scripts\agent-skill-groups.ps1" -Action enable -Group figma-design

# Switch to a scenario profile and disable other managed skills
powershell -ExecutionPolicy Bypass -File "$HOME\.codex\scripts\agent-skill-groups.ps1" -Action profile -Group ctf-web

# Return to the lean baseline
powershell -ExecutionPolicy Bypass -File "$HOME\.codex\scripts\agent-skill-groups.ps1" -Action profile -Group core

# Validate config/filesystem consistency
powershell -ExecutionPolicy Bypass -File "$HOME\.codex\scripts\agent-skill-groups.ps1" -Action validate

Actions

Action Purpose
runtimes Show built-in runtime presets.
analyze Scan active roots and disabled pool, then emit inventory.
suggest Suggest scenario groups from skill metadata.
init Generate an initial groups.json from existing skills.
list Print group names and descriptions. Supports --json.
status Show active/disabled/missing counts per group. Supports --json --details.
enable <name> Move that group's skills into the active root.
disable <name> Move that group's non-protected skills into the disabled pool.
profile <name> Enable core plus requested groups, then disable other managed skills.
session-load <name> Print a current-conversation context pack for the requested group without moving directories. Alias: context. Supports --json --max-chars --write.
session-unload <name> Print a current-conversation stop pack for the requested group without moving directories. Alias: context-off. Supports --json --write.
where <skill> Show a skill's current state and group membership. Supports --json.
validate Report missing and ungrouped skills.
doctor Report malformed skills and likely duplicate descriptions.
version Report the active CLI version, module path, Python executable, and available commands.
plan Preview profile changes without moving directories.
memory Print or write an AGENTS.md / CLAUDE.md managed block so agent sessions know how to use skill groups. Supports --json.
codex-native Probe Codex native skill discovery support, including debug prompt-input and optional app-server skills/list forceReload. Supports --json --probe-app-server.
codex-refresh <name> Apply a Codex filesystem profile and immediately verify it with app-server skills/list forceReload. Supports --json --dry-run --cwd.
codex-activate <name> Apply a Codex profile or --direct extraRoot refresh, force native metadata refresh, and return a current-session context pack. Supports --json --dry-run --cwd --max-chars --write --direct --extra-root.
codex-direct <name> Build a direct extraRoot for a Codex group and refresh native metadata without moving skill directories. Supports --json --dry-run --cwd --extra-root.
codex-clear [name] Clear Codex app-server skills/extraRoots, force native metadata refresh, and optionally return a current-session unload pack. Supports --json --dry-run --cwd.
backup Write a restorable state manifest.
restore Restore active/disabled state from a backup manifest.
demo Create a temporary sample skill repository and run the reversible quickstart workflow end to end. Supports --json.
discovery Check GitHub repository search ranks and public Pages URLs from any OS. Supports --json --fail-on-missing --required-rank 10; add --include-broad-sweep for broad observation terms such as skill manager.
web-search Sample ordinary Google/Bing/DuckDuckGo result pages from any OS. Outputs observation-only JSON and is not a stable gate.
web-search-report Generate Markdown and HTML reports from ordinary web-search JSON or a live web-search sample.
discovery-report Generate Markdown and HTML reports from discovery JSON or a live discovery run.
ecosystem-report Generate Markdown and HTML reports from ecosystem JSON or a live ecosystem status run.
visibility-status Aggregate discovery, ecosystem, and ordinary web-search payloads into JSON, Markdown, and HTML status reports.
indexnow Submit public Pages URLs to IndexNow from any OS. Use --dry-run --json to inspect the payload before sending.
indexnow-report Generate JSON, Markdown, and HTML status reports from IndexNow submission JSON.
migrate Move skills from configured legacy archives into the managed disabled pool.

Agent and Script Integration

Use JSON output for hooks, CI checks, MCP tools, and other coding agents:

agent-skill-groups list --config groups.json --json
agent-skill-groups status --config groups.json --json --details
agent-skill-groups session-load --config groups.json ctf-web --json
agent-skill-groups codex-native --json
agent-skill-groups codex-native --probe-app-server --json
agent-skill-groups codex-refresh --config groups.json --runtime codex ctf-web --json
agent-skill-groups codex-activate --config groups.json --runtime codex --direct ctf-web --json
agent-skill-groups codex-direct --config groups.json --runtime codex ctf-web --json
agent-skill-groups codex-clear --config groups.json --runtime codex ctf-web --json
agent-skill-groups where agent-reach --config groups.json --json
agent-skill-groups runtimes --config groups.json --json
agent-skill-groups discovery --json
agent-skill-groups web-search --json
agent-skill-groups discovery --json --required-rank 10
agent-skill-groups discovery --json --canonical-required-rank 5
agent-skill-groups discovery --json --include-broad-sweep
agent-skill-groups web-search-report --input web-search-report.json --output-md docs/WEB_SEARCH_REPORT.md --output-html docs/web-search-report.html
agent-skill-groups discovery-report --input discovery-report.json --output-md docs/DISCOVERY_REPORT.md --output-html docs/discovery-report.html
agent-skill-groups ecosystem-report --input ecosystem-status.json --output-md docs/ECOSYSTEM_STATUS.md --output-html docs/ecosystem-status.html
agent-skill-groups visibility-status --canonical-required-rank 10 --output-json docs/visibility-status.json --output-md docs/VISIBILITY_STATUS.md --output-html docs/visibility-status.html
agent-skill-groups indexnow --dry-run --json

The repository also includes a lightweight Copilot-compatible plugin at .github/plugins/agent-skill-groups/ with a bundled skill entry that explains the safe grouping workflow.

For generic Agent Skills indexers, the same skill entry is also exposed at skills/agent-skill-groups/SKILL.md.

Configuration

groups.json has this shape:

{
  "activeRoot": "$HOME\\.codex\\skills",
  "disabledRoot": "$HOME\\.codex\\skills.disabled\\managed",
  "protectedSkills": [".system"],
  "groups": {
    "core": {
      "description": "Small always-on baseline.",
      "protected": true,
      "skills": [".system", "agent-reach"]
    },
    "figma-design": {
      "description": "Figma design implementation.",
      "skills": ["figma", "figma-use"]
    }
  }
}

Groups may include other groups:

{
  "groups": {
    "ctf-web": {
      "includes": ["ctf-core", "strix-web"],
      "skills": ["ctf-web"]
    }
  }
}

Codex Memory Snippet

Add a short note to your AGENTS.md so future Codex sessions know how to load and stop skill groups in the current conversation:

agent-skill-groups memory --config groups.json --runtime codex --write AGENTS.md

Or paste the generated block manually:

# Persistent Agent Skill Group Manager
- Group table: `$HOME\.codex\skill-groups\groups.json`.
- Manager script: `$HOME\.codex\scripts\agent-skill-groups.ps1`.
- Current conversation load: run `-Action session-load -Group <group>` and use
  the emitted context pack immediately.
- Current conversation unload: run `-Action session-unload -Group <group>` and
  apply the stop instructions immediately.
- Use `-Action profile -Group <group>` only when native filesystem discovery
  after a runtime reload, rescan, or new session is useful.

Recommended Operating Model

Use core as the default. For the current conversation, run session-load only when the task needs a scenario group, then run session-unload or explicitly return to core behavior when that task is finished. Use profile only for filesystem state that should be visible to the runtime's native skill discovery.

This keeps your Codex setup understandable months later: the group table is the source of truth, the disabled pool is reversible, and your skill library can grow without turning every session into a full-library session.

Notes

  • The script moves directories; it does not modify skill contents.
  • Protected skills are never disabled.
  • Plugin enablement is intentionally separate from local skill directory management.
  • Review groups.json before running migrate or profile on an existing setup.

About

agent-skill-groups: agent skill groups manager, GitHub agent-skill-group manager, GitHub skill-group manager for Codex, Claude Code, OpenCode

go165.github.io/agent-skill-groups/

Topics

python opencode codex profile-manager skill-manager openai-codex skill-group agent-skills claude-code skills-manager skill-profiles agent-skills-manager agent-skill-groups agent-skill-group skill-groups skill-organizer github-agent-skill-group github-skill-group github-skills-group agent-skill-groups-manager

Resources

Readme

License

MIT license

Contributing

Contributing
Activity

Stars

3 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 45

v0.3.43 Latest
Jun 22, 2026
+ 44 releases

Packages

 
 
 

Contributors

Languages