feat(skills): bundle Agent Skills + gsccli skills install for 4 CLIs (#5)

## Summary

- Ship a curated `SKILL.md` (Agent Skills standard) for **Claude Code,
Codex, Gemini CLI, Qwen Code** under `agents/`, distributed via the npm
tarball.
- Add **`gsccli skills install --agent <name> [--scope user|project]`**
subcommand that copies the right package to the right per-CLI location.
Idempotent SHA-256 content diff; `--dry-run`, `--force`, `--agent all`
(auto-detects installed CLIs).
- Per-CLI frontmatter exploits each CLI's particularities: Claude
`allowed-tools: Bash(gsccli *)` + `argument-hint`; Codex
`agents/openai.yaml` UI metadata + `default_prompt`; Gemini
`when_to_use` + `user_invocable` + `allowed_tools: [run_shell_command]`;
Qwen minimal per-spec.
- **No MCP, no plugins, no extensions, no settings-file mutations** —
each CLI auto-discovers `~/.<cli>/skills/`; we only write inside.
- Surfaces per-CLI caveats in install output: Claude `permissions.deny`
precedence, Codex project-trust requirement, Gemini sandbox +
browser-auth, Qwen issue #2343 + OAuth deprecation.
- Bumps to **v1.2.0**.

## Test plan

- [x] `pnpm verify` — lint + type-check + 156/156 tests + build, all
green.
- [x] `pnpm dev skills install --agent <X> --dry-run` for
`claude|codex|gemini|qwen|all` — confirmed correct target paths, file
sizes, and per-CLI caveats surface.
- [x] `pnpm start skills install --agent claude --dry-run` — confirms
post-build production binary resolves `agents/` source via
`import.meta.url`.
- [x] `npm pack --dry-run` — confirmed all 5 SKILL.md files + Codex
`openai.yaml` + `agents/README.md` ship in tarball.
- [x] Tests: 40 service-level (target paths, planning, install,
idempotency, force, status, uninstall) + 10 CLI-surface (via spawned
tsx).

Author: nalyk

CHANGELOG.md

@@ -9,6 +9,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 _Nothing yet. New entries land here between releases._
 
+## [1.2.0] - 2026-05-02
+
+### Added — AI agent integration
+
+- **Bundled Agent Skills (`SKILL.md`)** for the four major AI coding-agent CLIs:
+  Claude Code, Codex (with companion `agents/openai.yaml` UI metadata), Gemini
+  CLI (with `when_to_use` and `allowed_tools: [run_shell_command]`), and Qwen
+  Code. Identical 600-word body across all four; only the per-CLI frontmatter
+  differs. Ships under `agents/` in the npm tarball.
+- **`gsccli skills install|uninstall|list|status`** subcommand. Copies the
+  bundled `SKILL.md` package to the right location for the chosen agent and
+  scope (`--scope user|project`, default `user`). Idempotent (SHA-256 content
+  diff), supports `--dry-run` and `--force`. `--agent all` auto-detects which
+  CLIs are installed by probing `~/.claude/`, `~/.codex/`, `~/.gemini/`,
+  `~/.qwen/`. Refuses `--scope project` unless the CWD has a project marker
+  (`.git`, `package.json`, `pyproject.toml`, etc.). Surfaces per-CLI caveats
+  in the install output (Claude `permissions.deny` precedence, Codex
+  project-trust requirement, Gemini sandbox + browser auth, Qwen issue #2343
+  + OAuth deprecation).
+
+### Notes
+
+- No MCP wiring, plugins, extensions, custom slash commands, profile snippets,
+  or settings-file mutations. Just the right `SKILL.md` in the right place per
+  CLI. Each CLI auto-discovers its skills directory.
+
 ## [1.1.0] - 2026-05-02
 
 First public release on npm. Published as **`@nalyk/gsccli`** (npm rejected the

README.md

@@ -191,6 +191,45 @@ gsccli mcp serve
 gsccli explore
 ```
 
+## AI agent integration — make your coding agent a `gsccli` power user
+
+`gsccli` ships with a curated `SKILL.md` (Agent Skills standard) for each of the
+four major AI coding-agent CLIs. Install the right one and your agent will know
+the killer workflows (period comparison, `--all` streaming, `--cache 1h`,
+parallel batch inspection), the silent gotchas (country lowercase, device
+uppercase, 25 000-row hard cap, `searchAppearance` solo, `dataState=final`
+3-day lag), and the recovery patterns (`auth login` after `invalid_grant`, lower
+`--rps` after `quotaExceeded`, `gsccli sites list` to fix `notFound`).
+
+```bash
+# Install for one agent (default: user scope, lands in ~/.<cli>/skills/gsccli/)
+gsccli skills install --agent claude
+gsccli skills install --agent codex
+gsccli skills install --agent gemini
+gsccli skills install --agent qwen
+
+# Project scope — drops the skill into ./.<cli>/skills/gsccli/ for the current repo
+gsccli skills install --agent claude --scope project
+
+# Detect every installed CLI and install for all of them
+gsccli skills install --agent all
+
+# Dry-run, idempotency, force overwrite
+gsccli skills install --agent all --dry-run
+gsccli skills install --agent claude --force
+
+# Inventory + status
+gsccli skills list
+gsccli skills status
+gsccli skills uninstall --agent claude
+```
+
+The skill content is identical across the four CLIs; only the frontmatter
+differs. Per-CLI caveats (Claude `permissions.deny` precedence, Gemini sandbox
++ browser auth, Codex project-trust requirement, Qwen issue #2343 + OAuth
+deprecation) are surfaced in the install output and detailed in
+[`agents/README.md`](./agents/README.md).
+
 ## Command structure
 
 ```
@@ -204,6 +243,7 @@ gsccli
   config set|get|list
   explore
   mcp serve
+  skills install|uninstall|list|status
 ```
 
 ## Output formats

agents/README.md

@@ -0,0 +1,108 @@
+# gsccli agent skills
+
+This directory ships with the `@nalyk/gsccli` npm package. It contains a single
+**Agent Skills** (`SKILL.md`) per supported AI coding-agent CLI. Each skill teaches
+the agent to use `gsccli` like a senior power user — knowing the `--all` streaming
+trick, the `--cache 1h` cache, the `country=usa` lowercase / `device=MOBILE`
+uppercase rule, the `!~=` filter parser order, the period-comparison delta sort,
+the 25,000-row hard cap and 50,000 daily property pair cap, the `searchAppearance`
+solo constraint, and the rest.
+
+There is no MCP, no plugin, no extension manifest, no custom slash command, no
+profile snippet. Just one `SKILL.md` per CLI, optionally with that CLI's idiomatic
+companion (Codex's `agents/openai.yaml` UI metadata).
+
+## Install
+
+The recommended path is the bundled subcommand:
+
+```bash
+gsccli skills install --agent <claude|codex|gemini|qwen|all>
+                      [--scope <user|project>]   # default: user
+                      [--dry-run]
+                      [--force]
+```
+
+Manual install also works — copy the per-CLI directory yourself:
+
+| Agent       | `--scope user` (default)                                | `--scope project`                            |
+| ----------- | ------------------------------------------------------- | -------------------------------------------- |
+| Claude Code | `cp -r agents/claude-code/gsccli ~/.claude/skills/`     | `cp -r agents/claude-code/gsccli .claude/skills/`     |
+| Codex       | `cp -r agents/codex/gsccli ~/.codex/skills/`            | `cp -r agents/codex/gsccli .codex/skills/`            |
+| Gemini      | `cp -r agents/gemini/gsccli ~/.gemini/skills/`          | `cp -r agents/gemini/gsccli .gemini/skills/`          |
+| Qwen Code   | `cp -r agents/qwen/gsccli ~/.qwen/skills/`              | `cp -r agents/qwen/gsccli .qwen/skills/`              |
+
+After install, restart the agent or run its skill-reload command.
+
+## Per-CLI caveats
+
+### Claude Code
+- The skill uses `allowed-tools: Bash(gsccli *), Read` to pre-approve all `gsccli`
+  invocations. **Note:** if your global `~/.claude/settings.json` (or
+  `.claude/settings.json`) contains a `permissions.deny` entry that matches
+  `Bash(gsccli *)` or `Bash(*)`, deny wins; the skill cannot override it. Permission
+  precedence: deny > ask > allow.
+
+### Codex
+- The skill ships with an `agents/openai.yaml` UI metadata file (display name,
+  short description, brand color, `default_prompt` for implicit invocation,
+  dependency declarations).
+- For `--scope project`, the project must be marked
+  `[projects."<absolute-path>"] trust_level = "trusted"` in `~/.codex/config.toml`
+  for Codex to load `.codex/skills/`. Run `codex` from the project once and it will
+  prompt you, or add the entry by hand.
+- Codex profiles are stable in CLI/IDE 0.125+ but remain experimental in the Codex
+  app. Codex deprecated custom commands in 0.126 in favor of skills — this skill
+  package is the right approach.
+
+### Gemini CLI
+- The skill uses Gemini's `when_to_use`, `user_invocable`, and
+  `allowed_tools: [run_shell_command]` frontmatter fields.
+- **`gsccli auth login` opens a browser for OAuth.** Gemini's sandbox modes
+  (Docker / Podman / Seatbelt restrictive) block browser launch. Run
+  `gsccli auth login` ONCE outside the sandbox to cache tokens at
+  `~/.gsccli/oauth-tokens.json`; subsequent `gsccli` calls inside Gemini will
+  use the cached tokens.
+
+### Qwen Code
+- Qwen has open issue **#2343** where skills sometimes don't auto-discover. If
+  the skill isn't picked up, run `/skills` once to load it manually.
+- **Qwen OAuth free tier was discontinued 2026-04-15.** You must have a
+  `DASHSCOPE_API_KEY`, an Alibaba Cloud Coding Plan, or an OpenAI-compatible
+  endpoint configured. Cached free-tier tokens no longer work.
+- Recommended model for tool-use reliability: `qwen3-coder-plus` (production)
+  or `qwen3-coder-next` (local inference). `qwen3-coder-flash` works but
+  becomes unreliable with many tools loaded.
+
+## Verification
+
+After install, ask the agent these in order:
+
+1. **"List my Search Console properties."** Expect `gsccli sites list -f json`
+   (or table) with results.
+2. **"Find pages losing clicks compared to last month."** Expect a `gsccli query
+   compare -d page --vs-start-date ... --sort-by delta_clicks:asc` invocation.
+3. **"Show top queries from USA on mobile."** Expect `country=usa` (lowercase)
+   and `device=MOBILE` (uppercase). Either case wrong → the skill needs sharpening.
+4. **"Inspect 5,000 URLs."** Expect `gsccli inspect batch --concurrency 5 --rps 8`
+   AND a warning about the 2,000/day per-property quota.
+
+Skill content is identical across all four CLIs; only the frontmatter and (for
+Codex) the UI metadata file differ.
+
+## Updating
+
+When you upgrade gsccli (`npm i -g @nalyk/gsccli@latest`), re-run the install
+command with `--force` to refresh the deployed skills:
+
+```bash
+gsccli skills install --agent all --force
+```
+
+## Authoring vs deployment
+
+The files under `agents/<cli>/gsccli/` are the **canonical, version-controlled**
+skill packages. The install subcommand simply copies them to the target locations.
+If you want to customize a skill for your own use, edit the deployed copy at
+`~/.<cli>/skills/gsccli/SKILL.md` rather than this directory — your changes here
+will be overwritten on the next `gsccli skills install --force`.

agents/claude-code/gsccli/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: gsccli
+description: Use when the user wants to query Google Search Console search analytics (clicks/impressions/CTR/position by query/page/country/device), inspect URL indexing status, manage sitemaps, or send Indexing API notifications via the `gsccli` shell command. Triggers on GSC, Search Console, sitemap, indexing API, mobile usability, AMP, rich results, search analytics period comparison, queries losing clicks, top pages, top queries, optimization gold, robots.txt rendering.
+allowed-tools: Bash(gsccli *), Read
+argument-hint: "[query|sites|sitemaps|inspect|index|config|explore]"
+---
+
+# gsccli — Google Search Console + Indexing API CLI
+
+You are a senior-grade user of the `gsccli` shell command (npm: `@nalyk/gsccli`). The
+human installed it; you wield it. This skill is the playbook.
+
+## Pre-flight (do these once, then never again)
+
+- `gsccli --version` to confirm install. If missing, tell the user `npm i -g @nalyk/gsccli`.
+- `gsccli auth login` once in a real shell (browser OAuth; tokens saved to
+  `~/.gsccli/oauth-tokens.json` mode 0600). Auth priority: OAuth >
+  `GOOGLE_APPLICATION_CREDENTIALS` env > config `credentials` key.
+- `gsccli config set site <url> --local` to pin the default site for the project.
+  URL-prefix property needs trailing slash (`https://example.com/`); Domain property
+  uses `sc-domain:example.com` (no scheme, no path, no slash). They are DIFFERENT
+  properties even for the same domain.
+
+## The 9 commands at a glance
+
+`auth` (OAuth), `query` (Search Analytics), `sites` (properties), `sitemaps`,
+`inspect` (URL Inspection), `index` (Indexing API for job postings + livestream),
+`config` (CLI config layers), `explore` (interactive reference), `mcp` (MCP server
+mode — out of scope for this skill).
+
+## The 10 killer workflows
+
+```bash
+# Top movers, period over period — the optimization-finding workhorse.
+gsccli query compare -d query --row-limit 25000 --sort-by delta_clicks:desc | head -20
+
+# Optimization gold — high impressions, low CTR (compose, don't mega-call).
+gsccli query run -d query --all --sort-by impressions:desc --max-rows 5000 -f ndjson > a.ndjson
+# then re-sort by CTR ascending in the next step.
+
+# Stream all rows OOM-free — only when --all + -f ndjson + no -o (uses generator).
+gsccli query run -d page --all -f ndjson > pages.ndjson
+
+# Client-side sort on any of the 4 metrics (GSC API only sorts by clicks desc).
+gsccli query top-queries --sort-by ctr:asc
+
+# Cache repeated queries while iterating — never on writes.
+gsccli query top-pages --row-limit 1000 --cache 1h
+
+# Parallel batch URL inspection with quota-aware rate pacing.
+gsccli inspect batch --urls-file urls.txt --concurrency 5 --rps 8 -f ndjson
+
+# Year-over-year comparison.
+gsccli query compare -d page --vs-start-date 393daysAgo --vs-end-date 365daysAgo \
+  --sort-by delta_position:asc
+
+# Multi-account / multi-agent isolation (separate OAuth tokens, no contention).
+GSCCLI_CONFIG_DIR=~/.gsccli-account-x gsccli query top-queries
+
+# Filter chain (AND). Operators: == != ~= !~= =~ !~. Don't hand-edit filter strings.
+gsccli query top-pages --filter 'page=~/blog/.*' 'country!=usa' 'device==MOBILE'
+
+# Index publish (job postings + livestream ONLY per Google policy; 200/day default).
+gsccli index publish https://example.com/jobs/123 --type URL_UPDATED
+gsccli index batch --urls-file jobs.txt --concurrency 3 --rps 3
+```
+
+## The 7 silent gotchas (the things that look right and break silently)
+
+1. URL-prefix vs Domain are DIFFERENT properties for the same domain.
+2. 4 fixed metrics only: `clicks`, `impressions`, `ctr`, `position`. No custom metrics.
+3. Default `--data-state final` excludes the last ~3 days. Use `--data-state all` for fresh.
+4. Country = ISO-3166-1 alpha-3 LOWERCASE (`usa`, `gbr`, `fra`). Device = UPPERCASE (`MOBILE`, `DESKTOP`, `TABLET`).
+5. 25,000-row hard cap per request. Use `--all` for more; the daily 50,000 page+keyword pair cap self-limits.
+6. `searchAppearance` cannot combine with other dimensions.
+7. `discover` search type cannot use the `query` dimension.
+
+## Output discipline
+
+stdout = data only; stderr = status. Pipes:
+- `-f json | jq '...'` for structured queries
+- `-f ndjson > file` for streaming large pulls
+- `-f csv` for spreadsheets
+- `-f chart` for terminal viz
+- `-f table` (default) for human reading
+
+Never pipe `-f table` to `jq` — use `-f json`.
+
+## Validation gates (run BEFORE the operation, not after a failure)
+
+- If site URL is unknown: `gsccli sites list -f json` then pick from `rows[].keys[0]`.
+- If freshness matters: pass `--data-state all` explicitly (default `final` excludes ~3 days).
+- If row count >25,000 expected: `--all -f ndjson` and stream.
+- If batch >2000 URLs: chunk across days; the inspect-batch quota is 2,000/day per property.
+
+## Common errors → recovery (self-heal, don't blind-retry)
+
+- `unauthorized` / `invalid_grant` → tell the user to run `gsccli auth login` once in a shell, then re-run.
+- `quotaExceeded` (429) on `query` → built-in retry handles transient; if persistent, propose `--cache 1h` to reduce calls.
+- `quotaExceeded` on `inspect batch` → reduce `--rps` to 4, or split URLs across days (2,000/day per property).
+- `notFound` on a property → run `gsccli sites list -f json` to surface exact strings; trailing slash and `sc-domain:` mismatches are 90% of these.
+- `searchAppearance` + another dimension → split into two queries.
+- `discover` + `query` dimension → use `-d page` or `-d country` instead.
+
+## Anti-patterns (don't do these)
+
+- Don't hand-loop `--row-limit`. Use `--all`.
+- Don't try to add custom metrics. There are only 4.
+- Don't bake credentials into scripts. Use `gsccli auth login` once.
+- Don't pipe `-f table` to `jq`. Use `-f json`.
+- Don't `index batch` non-job-posting/livestream content (Google policy ignores the notification).
+- Don't compose a single mega-invocation when 2 small steps (query → re-sort, or query → filter) is clearer and faster to debug.
+
+## Verification
+
+Check `rowCount` in JSON envelopes; check exit code (0 = success, 16 = auth, 8 = rate limit, 7 = permission). For writes (`sites add`, `sitemaps submit`, `index publish`), read the response message before claiming success.