# Install agent-skill-groups

`agent-skill-groups` is a Python CLI for organizing local `SKILL.md` folders
into runtime and scenario profiles. It does not modify skill files; it moves
whole skill directories between active roots and a managed disabled pool.

## pipx

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

## pip

```bash
python -m pip install git+https://github.com/go165/agent-skill-groups.git
python -m agent_skill_groups runtimes
```

## Release wheel

```bash
python -m pip install https://github.com/go165/agent-skill-groups/releases/download/v0.3.34/agent_skill_groups-0.3.34-py3-none-any.whl
agent-skill-groups runtimes
```

## Verify the active CLI

After install, verify that the console script and the module entry point report
the same runtime metadata:

```bash
agent-skill-groups version --json
python -m agent_skill_groups version --json
```

Both commands should report the same version and list commands such as
`ecosystem`, `web-search`, and `visibility-status`.

Run the local end-to-end self-test to prove the installed command can create a
demo skill layout, generate a profile config, validate it, report status, and
write the managed memory snippet without touching your real skill roots:

```bash
agent-skill-groups self-test --json
```

If the global console script is stale, reinstall the package so PATH picks up
the current entry point:

```bash
python -m pip install --upgrade --force-reinstall git+https://github.com/go165/agent-skill-groups.git
```

## From source

```bash
git clone https://github.com/go165/agent-skill-groups.git
cd agent-skill-groups
python -m pip install -e .
python -m pytest
```

## First run

Generate a config from the skills already installed for one runtime:

```bash
agent-skill-groups init --runtime codex --output groups.json
agent-skill-groups status --config groups.json --runtime codex --details
agent-skill-groups plan --config groups.json --runtime codex research
```

Generate or update the persistent instruction block for your agent runtime:

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

Use a stable config path for scripts:

```bash
export AGENT_SKILL_GROUPS_CONFIG="$HOME/.agents/skill-groups/groups.json"
agent-skill-groups status --json --details
```

Windows PowerShell:

```powershell
$env:AGENT_SKILL_GROUPS_CONFIG = "$HOME\.agents\skill-groups\groups.json"
agent-skill-groups status --json --details
```

## Runtime presets

- `codex`: `$HOME/.codex/skills`, `$HOME/.agents/skills`
- `claude-code`: `$HOME/.claude/skills`
- `opencode`: `$HOME/.config/opencode/skills`, `$HOME/.claude/skills`
- `generic`: `$HOME/.agents/skills`

Custom runtimes can be added under the `runtimes` object in `groups.json`.

## Machine-readable output

Automation and other coding agents should prefer JSON output:

```bash
agent-skill-groups analyze --json
agent-skill-groups suggest --json
agent-skill-groups list --json
agent-skill-groups status --json --details
agent-skill-groups where agent-reach --json
agent-skill-groups validate --json
agent-skill-groups doctor --json
agent-skill-groups runtimes --json
agent-skill-groups memory --json
agent-skill-groups discovery --json
agent-skill-groups ecosystem --json
agent-skill-groups indexnow --dry-run --json
```

## Discovery check

The installed CLI can also check public discoverability without PowerShell:

```bash
agent-skill-groups discovery --json
agent-skill-groups discovery --json --fail-on-missing
agent-skill-groups discovery --json --required-rank 10
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
```

It queries GitHub repository search for the configured target phrases and checks
that the public GitHub Pages URLs are reachable. Set `GH_TOKEN` or
`GITHUB_TOKEN`, or log in with GitHub CLI so `gh auth token` works, to avoid low
anonymous GitHub API rate limits.

The default report treats exact-name and intent-specific queries such as
`github skill-group` and `github agent-skill-group` as required for
`--fail-on-missing`. Very broad observation queries such as `skill-group` and
`skill groups` are still recorded but do not fail the gate by default.