go165/agent-skill-groups

# GitHub Repository: go165/agent-skill-groups

**URL:** https://github.com/go165/agent-skill-groups
**Author:** go165
**Description:** agent-skill-groups: GitHub agent-skill-group manager and GitHub skill-group manager for Codex, Claude Code, OpenCode, and Agent Skills
**Homepage:** https://go165.github.io/agent-skill-groups/
**Language:** Python

## Stats
- Stars: 2
- Forks: 0
- Open Issues: 1
- Commits: 115
- Created: 2026-06-21T06:02:25Z
- Updated: 2026-06-22T01:05:20Z
- Pushed: 2026-06-22T01:05:16Z

## README
# agent-skill-groups

[![CI](https://github.com/go165/agent-skill-groups/actions/workflows/ci.yml/badge.svg)](https://github.com/go165/agent-skill-groups/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/go165/agent-skill-groups)](https://github.com/go165/agent-skill-groups/releases)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

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

`agent-skill-groups` is a GitHub agent-skill-group manager, agent skill groups
organizer, and cross-runtime profile layer for Agent Skills-style `SKILL.md`
directories. 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 scenario-profile layer 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.

## Documentation

- English: [README.md](README.md)
- Simplified Chinese: [docs/README.zh-CN.md](docs/README.zh-CN.md)
- Japanese: [docs/README.ja.md](docs/README.ja.md)
- Spanish: [docs/README.es.md](docs/README.es.md)
- Install: [docs/INSTALL.md](docs/INSTALL.md)
- Quickstart demo: [docs/quickstart.html](docs/quickstart.html)
- FAQ: [FAQ](docs/FAQ.md) and [Pages FAQ](https://go165.github.io/agent-skill-groups/faq.html)
- Concepts: [Concepts](docs/CONCEPTS.md) and [Pages concepts](https://go165.github.io/agent-skill-groups/concepts.html)
- Comparison: [docs/COMPARISON.md](docs/COMPARISON.md) and [Pages comparison](https://go165.github.io/agent-skill-groups/comparison.html)
- Ecosystem map: [docs/ECOSYSTEM.md](docs/ECOSYSTEM.md) and [Pages ecosystem](https://go165.github.io/agent-skill-groups/ecosystem.html)
- Root Pages index: [https://go165.github.io/](https://go165.github.io/)
- Runtime layouts: [docs/RUNTIMES.md](docs/RUNTIMES.md)
- Real-world test plan: [docs/REAL_WORLD_TEST.md](docs/REAL_WORLD_TEST.md)
- Search/discovery notes: [docs/SEO.md](docs/SEO.md)
- Search indexing: [Search indexing](docs/SEARCH_INDEXING.md)
- Search phrases page: [docs/search-phrases.html](docs/search-phrases.html)
- Organic search landing page: [docs/github-skill-group-manager.html](docs/github-skill-group-manager.html)
- GitHub search ranking notes: [docs/GITHUB_SEARCH_RANKING.md](docs/GITHUB_SEARCH_RANKING.md)
- GitHub topic metadata: [docs/GITHUB_TOPICS.md](docs/GITHUB_TOPICS.md)
- Search diagnostics page: [Pages diagnostics](https://go165.github.io/agent-skill-groups/search-diagnostics.html)
- Cross-platform discovery command: `agent-skill-groups discovery --json`
- Canonical GitHub rank gate: `agent-skill-groups discovery --json --canonical-required-rank 5`
- Cross-platform web search sample: `agent-skill-groups web-search --json`
- External ecosystem status: `agent-skill-groups ecosystem --json`
- External ecosystem status report: `agent-skill-groups ecosystem-report --input ecosystem-status.json`
- Web search report generator: `agent-skill-groups web-search-report --input web-search-report.json`
- Aggregated visibility status: `agent-skill-groups visibility-status --json`
- Cross-platform IndexNow submission: `agent-skill-groups indexnow --dry-run --json`
- IndexNow status report generator: `agent-skill-groups indexnow-report --input indexnow.json`
- Discovery report generator: `agent-skill-groups discovery-report --input discovery-report.json`
- Current discovery report: [docs/DISCOVERY_REPORT.md](docs/DISCOVERY_REPORT.md)
- Current ecosystem status report: [docs/ECOSYSTEM_STATUS.md](docs/ECOSYSTEM_STATUS.md)
- Current web search report: [docs/WEB_SEARCH_REPORT.md](docs/WEB_SEARCH_REPORT.md)
- Current IndexNow status: [docs/INDEXNOW_STATUS.md](docs/INDEXNOW_STATUS.md) and [Pages IndexNow status](https://go165.github.io/agent-skill-groups/indexnow-status.html)
- Current visibility status: [docs/VISIBILITY_STATUS.md](docs/VISIBILITY_STATUS.md) and [Pages visibility status](https://go165.github.io/agent-skill-groups/visibility-status.html)
- Visibility tracking issue: [go165/agent-skill-groups#1](https://github.com/go165/agent-skill-groups/issues/1)
- Discovery check script: [scripts/check-discovery.ps1](scripts/check-discovery.ps1)
- Discovery workflow: [.github/workflows/discovery.yml](.github/workflows/discovery.yml)
- Live Agent Skills index: [agent-skills.md entry](https://agent-skills.md/skills/go165/agent-skill-groups/agent-skill-groups)
- Root GitHub Pages sitemap: [https://go165.github.io/sitemap.xml](https://go165.github.io/sitemap.xml)
- External directory submissions: [docs/ECOSYSTEM.md](docs/ECOSYSTEM.md#external-directory-submissions) and [dmgrok issue #90](https://github.com/dmgrok/agent_skills_directory/issues/90)
- Contributing: [CONTRIBUTING.md](CONTRIBUTING.md)
- Machine-readable summary for agents: [llms.txt](llms.txt)

## Search Keywords

GitHub agent skill group, GitHub agent-skill-group, GitHub skill-group, GitHub
skills group, 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, 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:

- [go165/github-skill-group](https://github.com/go165/github-skill-group)
- [go165/github-agent-skill-group](https://github.com/go165/github-agent-skill-group)
- [go165/agent-skill-group](https://github.com/go165/agent-skill-group)
- [go165/github-skills-group](https://github.com/go165/github-skills-group)
- [go165/skill-group](https://github.com/go165/skill-group)
- [go165/skill-groups](https://github.com/go165/skill-groups)

If the same GitHub search text still shows unrelated repositories first, see
the [search diagnostics page](https://go165.github.io/agent-skill-groups/search-diagnostics.html).
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](docs/ECOSYSTEM.md#external-directory-submissions).

For users comparing Agent Skills managers, see the
[comparison page](https://go165.github.io/agent-skill-groups/comparison.html).
`agent-skill-groups` focuses on scriptable 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 profiles:

- `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

One command switches the local filesystem state. Your agent runtime then sees
the right skills the next time it starts or reloads skills.

## Supported Runtimes

The Python CLI supports runtime presets:

```bash
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](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:

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

See [docs/INSTALL.md](docs/INSTALL.md) for `pip`, release wheel, source, and
PowerShell options.

For source checkout:

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

Use the cross-platform Python CLI directly:

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

You can override the default config path with:

```bash
export AGENT_SKILL_GROUPS_CONFIG=/path/to/groups.json
```

Or install the PowerShell compatibility script:

```powershell
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:

```bash
agent-skill-groups demo --json
```

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

```bash
# 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

# 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

```powershell
# 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

# 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. |
| `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`. |
| `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`; broad observation queries can be marked with `--optional-query`. |
| `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:

```bash
agent-skill-groups list --config groups.json --json
agent-skill-groups status --config groups.json --json --details
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 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:

```json
{
  "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:

```json
{
  "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 switch
profiles:

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

Or paste the generated block manually:

```markdown
# Persistent Agent Skill Group Manager
- Group table: `$HOME\.codex\skill-groups\groups.json`.
- Manager script: `$HOME\.codex\scripts\agent-skill-groups.ps1`.
- Before a task clearly matches a disabled scenario group, load the smallest
  suitable group with `-Action profile -Group <group>`.
- After scenario work, return to `core` unless asked to keep the group active.
```

## Recommended Operating Model

Use `core` as the default. Switch to a scenario profile only when the task needs
it, then return to `core` when the task is finished.

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.