Skip to content

FAQ.md

Latest commit

 

History

History
125 lines (96 loc) · 5.92 KB

FAQ.md

File metadata and controls

125 lines (96 loc) · 5.92 KB
Raw

GitHub skill-group FAQ

This FAQ mirrors the public FAQ page for repository search, GitHub code search, and agents that read Markdown files directly.

What is a GitHub skill-group?

In this project, a GitHub skill-group is a scenario profile for local SKILL.md Agent Skills, including skills installed from GitHub repositories. The point is to keep a small core profile active and load specialized skill groups only when a task needs them.

What is a GitHub agent-skill-group manager?

agent-skill-groups scans local Agent Skills, suggests groups, writes managed AGENTS.md or CLAUDE.md snippets, backs up state, switches profiles, and restores skill directories without editing skill contents. Its current-session path renders session-load and session-unload packs so an already-running conversation can use or stop a group without waiting for native skill rediscovery.

Is agent-skill-groups a skill, an MCP server, or a plugin?

The core project is a Python CLI. It also includes a lightweight Agent Skill entry and a Copilot-compatible plugin package so agent runtimes and directories can discover the workflow. It is not an MCP server because it does not expose MCP tools or resources.

How do I test it safely?

Install the latest release wheel and run the one-command demo. The demo uses a sample directory, not your real skill roots.

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 expected public JSON shape is documented in examples/demo-output.json.

Which runtimes are supported?

The CLI includes presets for OpenAI Codex, Claude Code, OpenCode, and generic Agent Skills layouts. Custom runtime roots can also be defined in groups.json.

What should an agent do before switching a profile?

Run agent-skill-groups status --details, preview the requested group with agent-skill-groups plan, write or update memory with agent-skill-groups memory --write, create a backup, and only then run agent-skill-groups profile.

Can it load a group in the current conversation?

Yes. Run agent-skill-groups session-load --config groups.json <group> and feed the generated context pack to the current agent. This reads SKILL.md files from both active roots and the disabled pool, so it works without moving directories.

If the host already supports native progressive disclosure, use --context-mode summary to emit only group and skill metadata, or --context-mode native-only with Codex direct activation to emit no skill bodies at all. Use the default full mode only when the current conversation needs the complete skill instructions pasted in.

To stop applying that group later in the same conversation, run agent-skill-groups session-unload --config groups.json <group> and feed the generated stop pack to the current agent. Current-session unload cannot erase prior model context; it changes behavior from that point forward.

profile is still useful for native skill discovery after a runtime reload, rescan, or new session.

Can it rewrite Codex's native skill list in an already-running CLI conversation?

No user-space manager can erase or replace the native skills block after Codex has already sent that block to the model in the current running CLI conversation. agent-skill-groups separates this from immediate current-conversation behavior: use session-load and session-unload when the current conversation needs a group right now.

For Codex-specific diagnostics, run:

agent-skill-groups codex-native --json
agent-skill-groups codex-native --probe-app-server --json

These probes report whether the installed Codex exposes native skill discovery signals such as codex debug prompt-input or app-server skills/list with forceReload. Those signals can prove fresh native metadata scans; they do not retroactively rewrite model-visible history in the current CLI conversation.

When the host supports app-server skill metadata, agent-skill-groups codex-refresh --config groups.json --runtime codex <group> --json applies the requested filesystem profile and immediately verifies it through app-server skills/list forceReload. The JSON response lists matchedSkills and missingSkills from the refreshed native scan, plus native errors when Codex rejects a skill file.

For one command that covers both layers without moving skill directories, run agent-skill-groups codex-activate --config groups.json --runtime codex --direct --context-mode native-only <group> --json. It updates Codex skills/extraRoots, refreshes native metadata, and emits no skill bodies so Codex can use native progressive disclosure. Use --context-mode summary if the current conversation needs a lightweight group summary, or --context-mode full if it needs complete SKILL.md bodies.

If you want the native app-server scan list to change without moving skill directories, use agent-skill-groups codex-direct --config groups.json --runtime codex <group> --json. It creates a direct extra root for the group and sends it through Codex skills/extraRoots/set before skills/list forceReload. Direct roots are isolated per config and group set, stale managed entries are removed before reuse, and nativeNameAliases reports skills whose declared native name: differs from their directory name. Run direct activation probes sequentially because Codex app-server skills/extraRoots is shared live state.

To unload that direct scan list live, run agent-skill-groups codex-clear --config groups.json --runtime codex <group> --json. It sends an empty skills/extraRoots list, forces another native metadata refresh, and can return a current-session unload pack for the named group. If another native Codex skill root still exposes a requested group skill after the direct roots are cleared, the JSON response lists it in remainingManagedGroupSkills instead of treating it as a failed clear.