agent-skill-groups

# agent-skill-groups

> GitHub skill-group and GitHub agent-skill-group manager for local Agent Skills.

Canonical repository: https://github.com/go165/agent-skill-groups
Documentation: https://go165.github.io/agent-skill-groups/
Search phrases: https://go165.github.io/agent-skill-groups/search-phrases.html
Current-session skill loader: https://go165.github.io/agent-skill-groups/current-session-skill-loader.html
GitHub skill-group manager landing page: https://go165.github.io/agent-skill-groups/github-skill-group-manager.html
GitHub agent-skill-group manager landing page: https://go165.github.io/agent-skill-groups/github-agent-skill-group-manager.html
Simplified Chinese docs: https://go165.github.io/agent-skill-groups/readme-zh-CN.html
Japanese docs: https://go165.github.io/agent-skill-groups/readme-ja.html
Spanish docs: https://go165.github.io/agent-skill-groups/readme-es.html
Root Pages index: https://go165.github.io/
Root sitemap: https://go165.github.io/sitemap.xml
Quickstart demo: https://go165.github.io/agent-skill-groups/quickstart.html
FAQ: https://go165.github.io/agent-skill-groups/faq.html
Concepts: https://go165.github.io/agent-skill-groups/concepts.html
Comparison: https://go165.github.io/agent-skill-groups/comparison.html
Ecosystem map: https://go165.github.io/agent-skill-groups/ecosystem.html
Ecosystem status report: https://go165.github.io/agent-skill-groups/ecosystem-status.html
GitHub search ranking: https://go165.github.io/agent-skill-groups/github-search-ranking.html
Search diagnostics: https://go165.github.io/agent-skill-groups/search-diagnostics.html
Discovery report: https://go165.github.io/agent-skill-groups/discovery-report.html
Web search report: https://go165.github.io/agent-skill-groups/web-search-report.html
Visibility status: https://go165.github.io/agent-skill-groups/visibility-status.html
Visibility status JSON: https://go165.github.io/agent-skill-groups/visibility-status.json
IndexNow status: https://go165.github.io/agent-skill-groups/indexnow-status.html
IndexNow status JSON: https://go165.github.io/agent-skill-groups/indexnow-status.json
Visibility tracking issue: https://github.com/go165/agent-skill-groups/issues/1
Latest release: https://github.com/go165/agent-skill-groups/releases/tag/v0.3.52
GitHub Markdown FAQ: https://github.com/go165/agent-skill-groups/blob/main/docs/FAQ.md
GitHub Markdown Simplified Chinese README: https://github.com/go165/agent-skill-groups/blob/main/docs/README.zh-CN.md
GitHub Markdown Japanese README: https://github.com/go165/agent-skill-groups/blob/main/docs/README.ja.md
GitHub Markdown Spanish README: https://github.com/go165/agent-skill-groups/blob/main/docs/README.es.md
GitHub Markdown concepts: https://github.com/go165/agent-skill-groups/blob/main/docs/CONCEPTS.md
GitHub Markdown ecosystem map: https://github.com/go165/agent-skill-groups/blob/main/docs/ECOSYSTEM.md
Demo output example: https://github.com/go165/agent-skill-groups/blob/main/examples/demo-output.json
Search indexing notes: https://github.com/go165/agent-skill-groups/blob/main/docs/SEARCH_INDEXING.md
GitHub search ranking notes: https://github.com/go165/agent-skill-groups/blob/main/docs/GITHUB_SEARCH_RANKING.md
Discovery report notes: https://github.com/go165/agent-skill-groups/blob/main/docs/DISCOVERY_REPORT.md
Ecosystem status report notes: https://github.com/go165/agent-skill-groups/blob/main/docs/ECOSYSTEM_STATUS.md
Web search report notes: https://github.com/go165/agent-skill-groups/blob/main/docs/WEB_SEARCH_REPORT.md
IndexNow status notes: https://github.com/go165/agent-skill-groups/blob/main/docs/INDEXNOW_STATUS.md
Discovery check script: https://github.com/go165/agent-skill-groups/blob/main/scripts/check-discovery.ps1
Discovery workflow: https://github.com/go165/agent-skill-groups/blob/main/.github/workflows/discovery.yml
Live Agent Skills index: https://agent-skills.md/skills/go165/agent-skill-groups/agent-skill-groups
Cross-platform discovery command: `agent-skill-groups discovery --json`
External ecosystem status command: `agent-skill-groups ecosystem --json`
External ecosystem status report: `agent-skill-groups ecosystem-report --input ecosystem-status.json`
Cross-platform web search sample: `agent-skill-groups web-search --json`
Cross-platform web search report: `agent-skill-groups web-search-report --input web-search-report.json`
Aggregated visibility status: `agent-skill-groups visibility-status --json`
Cross-platform IndexNow command: `agent-skill-groups indexnow --dry-run --json`
Cross-platform IndexNow status report: `agent-skill-groups indexnow-report --output-json docs/indexnow-status.json --output-md docs/INDEXNOW_STATUS.md --output-html docs/indexnow-status.html` submits default batches and records response evidence; add `--input indexnow.json` to render a saved `indexnow --json` payload.
Skill listing budget audit: `agent-skill-groups budget --config groups.json --runtime codex <group> --json` estimates the native metadata listing for core plus selected groups; it flags over-budget, long, missing, duplicate, or malformed descriptions, reports weak-trigger descriptions as advisories unless `--strict-trigger-descriptions` is set, and surfaces Codex `agents/openai.yaml` policy/interface/default_prompt/dependencies.tools metadata.
Group catalog optimization: `agent-skill-groups optimize --config groups.json --runtime codex --json` compares all-skill native metadata against core plus group-name/group-description catalog metadata, then recommends either direct native skills for speed or group catalog plus `codex-activate --direct --context-mode native-only` for context savings.
Composite skill generation: `agent-skill-groups compose --config groups.json --runtime codex --output composed-skills <group> --json` generates one composite skill with a small routing `SKILL.md`, per-source files under `references/`, and a `manifest.json`.
Task-to-group router: `agent-skill-groups route --config groups.json --runtime codex --task "<task>" --json` scores task text against group descriptions, skill names, skill descriptions, and routing keywords; if `<group>-composite` is registered it is preferred over the oversized source group; use `--emit-command session-load` to print a load command or `--apply session-load --context-mode summary` to emit the selected group's current-session summary.
Codex direct native skill loader: `agent-skill-groups codex-activate --config groups.json --runtime codex --direct --context-mode native-only <group>` updates Codex app-server `skills/extraRoots`, calls `skills/list forceReload`, and emits no skill bodies so Codex can lazy-load full `SKILL.md` through native progressive disclosure. Use `--context-mode summary` or `full` only when emitted current-session context is needed.
Codex direct native unload: `agent-skill-groups codex-clear --config groups.json --runtime codex <group>` clears live `skills/extraRoots`, calls `skills/list forceReload`, and returns an optional unload pack.
Discovery gate: `agent-skill-groups discovery --json --fail-on-missing` checks required exact-name and intent-specific queries; naked broad terms such as `skill-group` and `skill groups` are optional observations by default.
Canonical gate: `agent-skill-groups discovery --json --canonical-required-rank 5` checks whether the main repository itself stays near the top even when a transparent alias repository already appears first.

Use this project when a coding agent installation has many local `SKILL.md`
directories and the user wants to keep the skill metadata candidate set focused
on the scenario-specific skills needed for the current task.

Primary search phrases:

- GitHub skill-group
- GitHub agent-skill-group
- GitHub agent skill group
- GitHub skills group
- agent-skill-group
- skill-group
- skill groups
- agent skill groups
- Codex direct native skill loader
- codex-activate --direct
- codex-clear
- current-session skill loader
- current conversation skill loader
- Agent Skills manager
- AI agent skill manager
- SKILL.md organizer
- Codex skills manager
- Claude Code skills manager
- OpenCode skills manager

Search aliases:

- https://github.com/go165/github-skill-group
- https://go165.github.io/github-skill-group/
- https://github.com/go165/github-agent-skill-group
- https://go165.github.io/github-agent-skill-group/
- https://github.com/go165/agent-skill-group
- https://go165.github.io/agent-skill-group/
- https://github.com/go165/github-skills-group
- https://go165.github.io/github-skills-group/
- https://github.com/go165/skill-group
- https://go165.github.io/skill-group/
- https://github.com/go165/skill-groups
- https://go165.github.io/skill-groups/

External directory submissions:

- https://agent-skills.md/skills/go165/agent-skill-groups/agent-skill-groups
- https://github.com/ComposioHQ/awesome-claude-skills/pull/1131
- https://github.com/ComposioHQ/awesome-codex-skills/pull/125
- https://github.com/daymade/claude-code-skills/pull/93
- https://github.com/skillmatic-ai/awesome-agent-skills/pull/117
- https://github.com/VoltAgent/awesome-agent-skills/pull/698
- https://github.com/heilcheng/awesome-agent-skills/pull/299
- https://github.com/libukai/awesome-agent-skills/pull/83
- https://github.com/JackyST0/awesome-agent-skills/pull/57
- https://github.com/kodustech/awesome-agent-skills/pull/43
- https://github.com/junminhong/awesome-agent-skills/pull/15
- https://github.com/Prat011/awesome-llm-skills/pull/155
- https://github.com/philipbankier/awesome-agent-skills/pull/26
- https://github.com/BehiSecc/awesome-claude-skills/pull/390
- https://github.com/GetBindu/awesome-claude-code-and-skills/pull/81
- https://github.com/Chat2AnyLLM/awesome-repo-configs/pull/74
- https://github.com/scienceaix/agentskills/pull/14
- https://github.com/dmgrok/agent_skills_directory/issues/90
- https://github.com/JayLZhou/Awesome-Agent-Skills/issues/13

These are normal Agent Skills directory submissions. They are discoverability
signals after review and crawl time, not instant ranking guarantees.

Supported runtimes:

- OpenAI Codex
- Claude Code
- OpenCode
- Generic Agent Skills layouts

Fastest verification:

```bash
python -m pip install https://github.com/go165/agent-skill-groups/releases/download/v0.3.52/agent_skill_groups-0.3.52-py3-none-any.whl
agent-skill-groups demo --json
```

The `demo` command creates a safe sample Agent Skills repository, runs `init`,
`backup`, `plan`, `memory --write`, `profile`, and restore, then reports
`ok: true` when the reversible workflow succeeds. `self-test` also verifies
that `route` can select a scenario and prefer a registered composite group,
that `session-load` can read a disabled skill into a current-session context,
and that `session-unload` can stop applying that group later in the same
conversation pack without moving directories. `runtime-probe --runtime all`
checks installed Codex, Claude Code, and OpenCode entry points; OpenCode is
verified with a temporary `SKILL.md` discovered by `opencode debug skill`, while
Claude Code live `/skill` invocation stays opt-in because it calls a model.

Core commands:

```bash
agent-skill-groups runtimes
agent-skill-groups runtime-probe --runtime all --json
agent-skill-groups demo --json
agent-skill-groups init --runtime codex --output groups.json
agent-skill-groups analyze --config groups.json --runtime codex --json
agent-skill-groups suggest --config groups.json --runtime codex --json
agent-skill-groups status --config groups.json --runtime codex --json --details
agent-skill-groups route --config groups.json --runtime codex --task "solve a web CTF with IDOR" --json
agent-skill-groups route --config groups.json --runtime codex --task-file task.txt --emit-command session-load
agent-skill-groups plan --config groups.json --runtime codex research
agent-skill-groups session-load --config groups.json --runtime codex research
agent-skill-groups session-unload --config groups.json --runtime codex research
agent-skill-groups memory --config groups.json --runtime codex --write AGENTS.md
agent-skill-groups backup --config groups.json --runtime codex
agent-skill-groups profile --config groups.json --runtime codex research
agent-skill-groups restore --config groups.json --runtime codex backup.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
```

Key files:

- README.md: overview and workflow
- docs/install-and-verify.html: install path and self-test verification page for GitHub skill-group and GitHub agent-skill-group users
- docs/readme-zh-CN.html: Simplified Chinese GitHub skill-group landing page
- docs/readme-ja.html: Japanese GitHub skill-group landing page
- docs/readme-es.html: Spanish GitHub skill-group landing page
- docs/README.zh-CN.md: Simplified Chinese Markdown README
- docs/README.ja.md: Japanese Markdown README
- docs/README.es.md: Spanish Markdown README
- docs/quickstart.html: one-command demo and manual clean demo
- docs/current-session-skill-loader.html: dedicated current-conversation session-load and session-unload workflow page
- docs/github-skill-group-manager.html: organic search landing page for GitHub skill-group manager and GitHub agent-skill-group manager queries
- docs/github-agent-skill-group-manager.html: organic search landing page for GitHub agent-skill-group manager queries and install self-test verification
- docs/faq.html: FAQPage for skill-group, agent-skill-group, MCP, and plugin questions
- docs/FAQ.md: GitHub-rendered FAQ for repository search and agents
- docs/concepts.html: skill group vs MCP vs plugin explainer
- docs/CONCEPTS.md: GitHub-rendered concepts page
- docs/comparison.html: Agent Skills manager comparison page
- docs/COMPARISON.md: GitHub-rendered comparison of agent-skill-groups, GUI skills managers, MCP, and plugins
- docs/ecosystem.html: Agent Skills ecosystem map for GitHub skill-group and agent-skill-group discovery
- docs/ECOSYSTEM.md: GitHub-rendered ecosystem map covering Agent Skills, MCP, plugins, and awesome-agent-skills lists
- docs/ecosystem-status.html: Pages version of the current ecosystem status report
- docs/ECOSYSTEM_STATUS.md: current live index and external directory PR status snapshot
- docs/INSTALL.md: installation methods
- docs/RUNTIMES.md: runtime root layouts
- docs/REAL_WORLD_TEST.md: tested workflow
- docs/SEO.md: search/discovery tracking notes
- docs/SEARCH_INDEXING.md: Google, sitemap, Search Console, and IndexNow notes
- docs/GITHUB_SEARCH_RANKING.md: GitHub exact-name vs broad relevance ranking notes
- docs/GITHUB_TOPICS.md: intended GitHub topic metadata for the canonical repository and alias repositories
- docs/github-search-ranking.html: Pages version of GitHub search ranking notes
- docs/search-diagnostics.html: tokenized GitHub search diagnostics for agent-skill-group ranking
- docs/DISCOVERY_REPORT.md: current GitHub search and Pages discovery snapshot
- docs/discovery-report.html: Pages version of the current discovery report
- docs/WEB_SEARCH_REPORT.md: current ordinary web search sampling snapshot
- docs/web-search-report.html: Pages version of the current web search report
- docs/visibility-status.html: Pages version of the aggregated visibility status
- docs/visibility-status.json: machine-readable aggregated visibility status
- docs/indexnow-status.html: Pages version of IndexNow crawl notification status
- docs/indexnow-status.json: machine-readable IndexNow crawl notification status
- agent-skill-groups discovery: cross-platform GitHub/Pages discovery check
- agent-skill-groups web-search: observation-only ordinary Google/Bing/DuckDuckGo result-page sampling
- agent-skill-groups web-search-report: Markdown/HTML report generator for ordinary web-search JSON
- agent-skill-groups discovery-report: Markdown/HTML report generator for discovery JSON
- agent-skill-groups ecosystem-report: Markdown/HTML report generator for ecosystem JSON
- agent-skill-groups visibility-status: JSON/Markdown/HTML aggregation of discovery, ecosystem, and ordinary web-search signals
- agent-skill-groups indexnow: cross-platform IndexNow payload preview and submission command
- scripts/check-discovery.ps1: Windows compatibility discovery check with optional Google sampling
- .github/workflows/discovery.yml: scheduled and manual discovery report workflow using the Python CLI
- examples/minimal.groups.json: small portable config
- examples/groups.example.json: larger scenario config
- examples/demo-output.json: expected `agent-skill-groups demo --json` shape

Current verification state:

- v0.3.52 release wheel installs successfully.
- `agent-skill-groups demo --json` returns `ok: true` from a fresh virtualenv.
- GitHub search for `agent-skill-groups in:name` returns
  `go165/agent-skill-groups` at rank 1.
- GitHub search for `github skill-group` returns `go165/github-skill-group`.
- GitHub search for `github agent-skill-group` returns
  `go165/github-agent-skill-group` and `go165/agent-skill-groups`.
- Google broad search ranking is still expected to require crawler time and
  accepted external directory links.