@witchpot/gmc 0.1.6 → 0.1.8

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 All notable changes to the Game Market Copilot CLI will be recorded here.
 
+## 0.1.8 - 2026-06-12
+
+- Updated the bundled `gmc-analysis` skill to v0.2.0 with the learnings from
+  the first price-band field test: camelCase-query to kebab-case-flag
+  mapping note, zero-review rating artifact pitfall, discounted snapshot
+  price pitfall, price-question routing to explicit-bucket aggregates, and
+  the evidence-pack quota location exception.
+
+## 0.1.7 - 2026-06-12
+
+- Bundled the `gmc-analysis` Agent Skill (v0.1.0): analysis recipes, pivot
+  heuristics, quota etiquette, and honesty rules for Claude Code / Codex
+  agents, seeded from the 2026-06-12 field test.
+- Added `gmc skill install` (project `.claude/skills/` or `--global`),
+  `gmc skill print --format agents-md` (self-contained AGENTS.md section
+  with references inlined), and `gmc skill status` (packaged vs installed
+  version check with stale warnings).
+
 ## 0.1.6 - 2026-06-12
 
 - Added `gmcp` and `game-market-copilot` binary aliases. Oh My Zsh's git

package/README.md

@@ -61,6 +61,27 @@ gmc auth status --json
 The CLI never prints the raw key or credential after login. Status and config output show only
 a non-secret prefix.
 
+## Agent Skill
+
+The package bundles the `gmc-analysis` Agent Skill — analysis recipes, pivot
+heuristics, quota etiquette, and honesty rules for coding agents. Install it
+so Claude Code (and similar tools) load it automatically:
+
+```bash
+gmc skill install            # writes .claude/skills/gmc-analysis (project)
+gmc skill install --global   # or ~/.claude/skills/gmc-analysis
+gmc skill status --json      # packaged vs installed versions
+```
+
+For Codex and other AGENTS.md-based agents, append the self-contained
+edition (references inlined) to your project brief:
+
+```bash
+gmc skill print --format agents-md >> AGENTS.md
+```
+
+Re-run install/print after `npm update` to pick up newer skill versions.
+
 ## First Queries
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@witchpot/gmc",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "private": false,
   "description": "Command line tools for Game Market Copilot market research.",
   "license": "UNLICENSED",
@@ -31,6 +31,7 @@
     "bin",
     "src",
     "scripts",
+    "skill",
     "README.md",
     "CHANGELOG.md"
   ],

package/scripts/check-release-readiness.mjs

@@ -13,11 +13,16 @@ const requiredFiles = [
   "src/main.js",
   "src/requests.js",
   "src/workflows.js",
+  "skill/gmc-analysis/SKILL.md",
+  "skill/gmc-analysis/references/recipes.md",
+  "skill/gmc-analysis/references/pitfalls.md",
+  "skill/gmc-analysis/references/quota.md",
+  "skill/gmc-analysis/CHANGELOG.md",
   "README.md",
   "CHANGELOG.md"
 ];
 
-const requiredFileGlobs = ["bin", "src", "scripts", "README.md", "CHANGELOG.md"];
+const requiredFileGlobs = ["bin", "src", "scripts", "skill", "README.md", "CHANGELOG.md"];
 const forbiddenPatterns = [
   { pattern: /@supabase\//, message: "CLI package must not import Supabase SDKs." },
   { pattern: /@clerk\//, message: "CLI package must not import Clerk SDKs." },
@@ -94,6 +99,17 @@ if (!changelog.includes(`## ${packageJson.version} -`)) {
   failures.push(`CHANGELOG.md must include a section for ${packageJson.version}.`);
 }
 
+const skillSource = readFileSync(path.join(packageDir, "skill/gmc-analysis/SKILL.md"), "utf8");
+const skillVersionMatch = skillSource.match(/^\s*version:\s*"?([0-9][0-9A-Za-z.\-]*)"?\s*$/m);
+if (!skillVersionMatch) {
+  failures.push("skill/gmc-analysis/SKILL.md must declare metadata.version in its frontmatter.");
+} else {
+  const skillChangelog = readFileSync(path.join(packageDir, "skill/gmc-analysis/CHANGELOG.md"), "utf8");
+  if (!skillChangelog.includes(`## ${skillVersionMatch[1]} -`)) {
+    failures.push(`skill CHANGELOG.md must include a section for skill version ${skillVersionMatch[1]}.`);
+  }
+}
+
 for (const file of sourceFiles) {
   const source = readFileSync(path.join(packageDir, file), "utf8");
   for (const forbidden of forbiddenPatterns) {

package/scripts/smoke-pack.mjs

@@ -65,6 +65,23 @@ try {
     throw new Error("Packed gmc config get --json did not print the expected config payload");
   }
 
+  const skillStatusResult = run(gmcBin, ["skill", "status", "--json"], {
+    env: { GMC_CONFIG_PATH: configPath },
+    capture: true
+  });
+  const skillStatus = JSON.parse(skillStatusResult.stdout);
+  if (!skillStatus?.data?.packaged?.version) {
+    throw new Error("Packed gmc skill status did not report a packaged skill version");
+  }
+
+  const skillPrintResult = run(gmcBin, ["skill", "print", "--format", "agents-md"], {
+    env: { GMC_CONFIG_PATH: configPath },
+    capture: true
+  });
+  if (!skillPrintResult.stdout.includes("GMC Analysis") || !skillPrintResult.stdout.includes("Pitfalls")) {
+    throw new Error("Packed gmc skill print did not emit the inlined agents-md section");
+  }
+
   // gmc is shadowed by Oh My Zsh's `git merge --continue` alias, so the
   // package ships alias binaries; make sure npm actually installed them.
   for (const aliasName of ["gmcp", "game-market-copilot"]) {

package/skill/gmc-analysis/CHANGELOG.md

@@ -0,0 +1,29 @@
+# gmc-analysis skill changelog
+
+## 0.2.0 - 2026-06-12
+
+- Folded in the five learnings from the first field test (2025 city
+  builders, price-band vs rating/review analysis; 7/7 rubric pass):
+  - setup: documented the camelCase-query -> kebab-case-flag mapping and
+    that per-command `--help` is currently generic;
+  - new pitfall P5: zero-review games aggregate as rating 0 — pair rating
+    metrics with `--reviews-min`, derive per-bucket hit rates from counts;
+  - new pitfall P6: snapshot prices include active discounts — check the
+    `discount` field before price-band conclusions;
+  - recipe R4: price/distribution questions route to aggregate with
+    explicit buckets first; `cohort pricing` is page-bounded texture only;
+  - quota: composed evidence packs carry quota under
+    `meta.upstreamRequests[].entitlements`, not at the top level.
+
+## 0.1.0 - 2026-06-12
+
+- Initial release, seeded from the 2026-06-12 field test (roguelike cohort
+  complaint analysis over 114 games):
+  - core workflow: coverage pre-estimation -> bounded workflow -> pivot ->
+    exemplar drill-down;
+  - pitfalls P1-P5 including the cross-game pattern aggregation pivot and
+    the coverage-vs-topics distinction;
+  - full-cohort map-reduce recipe with `--fields` projection and subagent
+    chunking;
+  - quota etiquette and honesty rules (skippedReasons, locked/preview,
+    bounded-evidence caveats).

package/skill/gmc-analysis/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: gmc-analysis
+description: >-
+  Use when analyzing Steam game market data with the gmc CLI (Game Market
+  Copilot) — cross-game cohort analysis (common complaints, marketing
+  patterns, pricing), single-title deep dives, market sizing, or any question
+  about Steam games, reviews, creators, showcases, or campaigns that gmc can
+  answer.
+metadata:
+  version: 0.2.0
+---
+
+# GMC Analysis
+
+The gmc CLI is a JSON-first client for the Game Market Copilot API (Steam
+market analytics). The division of labor: the server owns data and access
+gates, the CLI owns mechanical collection and bounded aggregation, and YOU
+(the agent) own semantic interpretation. The CLI will not cluster meanings
+across games — that is your job.
+
+## Setup check (run once per session)
+
+```bash
+gmc --version                 # gmcp / game-market-copilot are the same CLI
+gmc auth status --json        # anonymous => redacted previews + tiny quota
+gmc schema --json             # the authoritative command/endpoint reference
+```
+
+Never guess flags: `gmc schema --json` is the source of truth for commands
+and parameters. Endpoint query params are camelCase and the matching CLI
+flag is the kebab-case equivalent (`priceMin` -> `--price-min`,
+`reviewsGt` -> `--reviews-gt`). Per-command `--help` currently prints one
+generic usage list, so trust the schema. Always pass `--json`.
+
+## Core workflow for cohort questions
+
+1. **Size the cohort and its research coverage first** (1-2 requests):
+   `gmc games count --source steam <filters> --json`, then again with
+   `--coverage full,partial`. Deep analysis exists only for researched
+   titles; most of the catalog is `basic` (catalog + snapshot only). This
+   tells you the denominator and the fan-out cost before you spend quota.
+2. **Try the bounded cross-game workflow** that matches the question
+   (`gmc reviews patterns`, `gmc marketing patterns`, `gmc cohort ...`) with
+   `--coverage full,partial` in the filters.
+3. **Pivot when the workflow under-delivers** — see the pitfalls reference.
+   The most common pivot: per-game `gmc games analysis --sections reviews`
+   over the cohort, then cluster the named theme labels yourself.
+4. **Drill into exemplars**: `gmc games detail`, `gmc games analysis`,
+   `gmc games success-report`, `gmc campaigns signals` on 2-5 representative
+   titles to add texture to the synthesis.
+
+For cohorts beyond one page, and for the full-cohort map-reduce procedure
+(pagination, bounded concurrency, `--fields` projection, subagent chunking),
+follow the recipes reference.
+
+## Hard rules
+
+- **Missing data is not absent sentiment.** Report `cohort.usableGames`,
+  `cohort.skippedGames`, and `cohort.skippedReasons`. "No review topics
+  collected" must never be presented as "players have no complaints".
+- **Locked is locked.** When `meta.entitlements.locked` or `preview: true`
+  appears, present what you got as a preview, name the lock key (e.g.
+  `success_report.full`), and never imply you read the full content.
+- **Bounded evidence, not market truth.** Carry the CLI's own caveats:
+  evidence packs are sampled/returned-page evidence. Always state
+  denominators ("87 of 107 analyzed titles") and preserve `warnings`.
+- **Separate API facts from your synthesis.** Quote theme labels and player
+  counts as data; label your clustering and conclusions as your analysis.
+- **Pace your quota.** Read `meta.entitlements.quota` (`used`/`limit`)
+  before fanning out and keep headroom; on HTTP 429 respect `Retry-After`.
+  Details in the quota reference.
+- Preserve `meta.requestId` values for anything you may need to report.
+
+## References
+
+- `references/recipes.md` — step-by-step playbooks (cohort complaints,
+  full-cohort map-reduce, single-title deep dive, market sizing).
+- `references/pitfalls.md` — known failure modes and the correct pivots.
+- `references/quota.md` — quota model and cost estimation.
+
+(In the AGENTS.md edition of this skill the references are inlined below.)
+
+## When recipes fail
+
+If a documented recipe fails or you discover a better workaround, record a
+learning entry so the skill can be improved:
+
+```markdown
+- Source: field usage
+- Task: <the analysis question>
+- What happened: <observed behavior, requestIds>
+- Gap or win: <missing knowledge / what worked>
+- Proposed rule: <one-sentence candidate rule>
+```
+
+Suggest the user submits it through the GMC feedback channel (template in
+the gmc user guide).

package/skill/gmc-analysis/references/pitfalls.md

@@ -0,0 +1,72 @@
+# Pitfalls and pivots
+
+Known failure modes observed in real field tests, with the correct response.
+Entries carry an observation date; behavior may improve in later releases.
+
+## P1. `reviews patterns` may aggregate nothing across games (2026-06)
+
+Cross-game pattern keys are derived from per-game topic labels and cluster
+IDs, which rarely match between games. A run where `data.patterns` has zero
+entries with `appearsInGames >= 2` is an EXPECTED outcome on many cohorts —
+it does not mean the service is broken and it does not mean the games share
+no complaints.
+
+**Pivot**: per-game `gmc games analysis --sections reviews`, then cluster
+the `negativeThemes`/`positiveThemes` labels yourself (recipe R1/R2).
+
+## P2. Research coverage does not guarantee review topics (2026-06)
+
+A game with `coverage: full` can still return no review topics;
+`cohort.skippedReasons.no_matching_review_topics` is common (observed 10 of
+15 on one researched cohort). Theme-level analysis
+(`analysis --sections reviews`) has broader coverage than topic explorer
+data.
+
+**Pivot**: prefer themes over topics for cohort work; report skipped games
+as "topics not collected", never as "no complaints found".
+
+## P3. Preview and locked payloads
+
+Anonymous and Free callers receive redacted previews. Markers:
+`meta.entitlements.locked` (lock keys like `success_report.full`,
+`reviews.topics.full`), `preview: true` fields, truncated summaries.
+
+**Rule**: present previews as previews, name the lock, and suggest the plan
+that unlocks it if the user asks. Never extrapolate locked content.
+
+## P4. Anonymous sessions look broken but are just unauthenticated
+
+Without `gmc login` / `GMC_API_KEY`, deep sections come back redacted and
+the quota is tiny, which can read as "the API has no data".
+
+**Rule**: run `gmc auth status --json` first; if `authMode` is `anonymous`,
+say so in your answer and scope expectations to public preview data.
+
+## P5. Zero-review games carry rating 0 in aggregates (2026-06)
+
+Unconditional `avg_rating` / `median_rating` in low-traction segments (cheap
+or free price buckets) is crushed by zero-review games aggregating as
+rating 0 (observed: a free bucket with avg_rating 11.1). This misreads as
+"cheap games are hated" when it actually means "most cheap games have no
+reviews".
+
+**Pivot**: pair rating metrics with `--reviews-min` (e.g. 10). For "share of
+well-rated games per bucket", run `--metric count` twice over the same
+bucket spec — once unconditional, once with `--reviews-min 10
+--rating-min 80` — and divide.
+
+## P6. Snapshot prices include active discounts (2026-06)
+
+`price` is the current store price, not the launch/list price; a discounted
+title lands in a lower price bucket (observed: a $34.99 list price counted
+as $23.44 at -33%). Game rows carry a `discount` field.
+
+**Rule**: when price-band conclusions matter, check `discount` on the
+exemplar rows and caveat bucket assignments, especially during sale seasons.
+
+## P7. Don't paginate by brute force
+
+List endpoints cap at `limit=100`. For "how many" questions use
+`gmc games count`; for distributions use `gmc games aggregate` — both are
+single-request server aggregates. Reserve pagination loops for when you
+actually need the rows (recipe R2).

package/skill/gmc-analysis/references/quota.md

@@ -0,0 +1,27 @@
+# Quota etiquette
+
+Quotas are per workspace, per UTC day, enforced for bearer credentials
+(API keys / CLI credentials). As of 2026-06: starter 1,000/day, pro
+10,000/day; anonymous public preview is far smaller. Treat these numbers as
+indicative — the response metadata is the source of truth.
+
+## Rules
+
+1. **Read before you spend.** Every bearer response carries
+   `meta.entitlements.quota` = `{ used, limit }`. Check it at the start of a
+   session and after each fan-out. Exception: CLI-composed evidence packs
+   (`cohort ...`, `reviews patterns`, `games benchmark`, ...) expose quota
+   per upstream call instead — read the last entry of
+   `meta.upstreamRequests[].entitlements.quota`.
+2. **Estimate fan-out cost first.** A cohort sweep costs roughly
+   `search pages + (1 per game per section call)`. A 114-game cohort with one
+   analysis call each ~= 120 requests. Compare against remaining quota and
+   keep at least ~20% headroom for drill-downs and retries.
+3. **Shrink the cohort before shrinking the question.** Use
+   `--coverage full,partial` and tighter filters so requests are not spent on
+   titles that would be skipped anyway.
+4. **On HTTP 429 (`QUOTA_EXCEEDED`)**: stop fanning out, respect the
+   `Retry-After` header / `error.retryAfterSeconds` (the window resets at UTC
+   midnight), and tell the user how much of the analysis completed.
+5. **Prefer server aggregates** (`count`, `aggregate`) over row pagination —
+   they answer sizing questions in one request.

package/skill/gmc-analysis/references/recipes.md

@@ -0,0 +1,101 @@
+# Recipes
+
+Placeholders use `<...>`. Always add `--json`. Commands and parameters are
+authoritative in `gmc schema --json`; these recipes encode strategy, not
+syntax.
+
+## R1. Cohort complaints / praises ("what do players dislike about <cohort>?")
+
+```bash
+# 1. Denominators (2 requests)
+gmc games count --source steam <filters> --json
+gmc games count --source steam <filters> --coverage full,partial --json
+
+# 2. Bounded cross-game attempt (1 + N requests)
+gmc reviews patterns --source steam <filters> --coverage full,partial \
+  --limit 15 --max-topics-per-game 8 --preset summary --json
+```
+
+Read `data.patterns[].appearsInGames`. If no pattern appears in 2+ games
+(common — see pitfalls P1), pivot to per-game themes:
+
+```bash
+# 3. Per-game named themes (N requests; theme labels are written text)
+gmc games analysis --source steam <appid> --sections reviews --json
+# extract sections.reviews.negativeThemes[]: {label, frequency, playerCount}
+```
+
+Cluster the theme labels yourself (semantic grouping is your job), then
+report: cluster -> games count / usable games, with 2-3 quoted example
+labels per cluster and the skipped/missing counts.
+
+## R2. Full-cohort map-reduce (cohort larger than one page)
+
+Cost: ~(pages + N) requests. Check quota headroom first (see quota.md).
+
+1. **Collect the cohort**: page `gmc games search <filters> --coverage
+   full,partial --sort reviews_desc --limit 100 --offset <0,100,...>
+   --fields appid,title,reviews --json` until `pagination.nextOffset` is
+   null.
+2. **Fan out** `gmc games analysis --source steam <appid> --sections
+   reviews --json` per game with bounded concurrency (<= 8 parallel
+   processes). Write each response to a temp file; tolerate individual
+   failures and count them.
+3. **Project before reading**: extract only what you need (e.g.
+   `negativeThemes` label/frequency/playerCount) into one compact JSON/NDJSON
+   file. A 100+ game cohort fits in a few tens of KB after projection.
+4. **Cluster semantically** over the projected labels. Crude keyword
+   bucketing is acceptable as a first pass, but review the "other" bucket
+   and misclassifications yourself before reporting.
+5. **Report with denominators**: cohort size, games with analysis, games
+   skipped (by reason), cluster -> game counts, examples, and the caveat
+   that this is researched-cohort evidence, not full-market measurement.
+
+When the cohort exceeds ~100 games or projected evidence would overflow your
+context, chunk the appid list across subagents (e.g. 20 games each), have
+each return its projected themes, then merge and cluster in the lead agent.
+
+## R3. Single-title deep dive ("why did <game> work?")
+
+```bash
+gmc games resolve --source steam --query <title> --json   # if appid unknown
+gmc games detail --source steam <appid> --json
+gmc games analysis --source steam <appid> --sections reviews,marketing,creators,media --json
+gmc games success-report --source steam <appid> --json    # long-form narrative
+gmc campaigns signals --source steam <appid> --json       # cross-channel timeline
+```
+
+Use `--fields` on detail to keep output small. Respect preview/locked rules
+(pitfalls P3) on every response.
+
+## R4. Market sizing and distribution
+
+```bash
+gmc games count --source steam <filters> --json
+gmc games aggregate --source steam --metric count,median_reviews \
+  --group-by release_year <filters> --json
+gmc games aggregate --source steam --metric count --group-by coverage <filters> --json
+```
+
+`data.basis = server_aggregate` means market-wide for the filter set (within
+GMC source coverage) — unlike evidence packs, these are not page-bounded.
+
+**Price/distribution questions belong here, not in `cohort pricing`.** Run
+the aggregate with explicit buckets first (e.g.
+`--bucket price:0,5,10,15,20,25,30,40,60`); `gmc cohort pricing` is
+returned-page (top ~20) texture, useful only as a supplement and must be
+labeled as page-bounded evidence.
+
+Per-bucket "hit rate" pattern (one request per condition): pair the same
+bucket spec with shared filters — `--reviews-min 500 --metric count` gives
+reach per price band; `--reviews-min 10 --rating-min 80 --metric count`
+gives the well-rated share. Divide by the unconditional bucket counts.
+Never read unconditional rating aggregates in low-traction buckets
+(pitfall P5).
+
+## Output contract for every analysis
+
+Always include in your final answer: the cohort definition and size, how many
+games carried the evidence (usable vs skipped, with reasons), which plan/
+entitlement context applied, notable `warnings`, and a clear line between
+data and your synthesis.

package/src/args.js

@@ -1,7 +1,7 @@
 import { EXIT_USAGE } from "./constants.js";
 import { writeJsonError } from "./output.js";
 
-export const BOOLEAN_OPTIONS = new Set(["json", "help", "version", "no-open"]);
+export const BOOLEAN_OPTIONS = new Set(["json", "help", "version", "no-open", "global"]);
 
 export function parseArgs(args) {
   const command = [];
@@ -60,6 +60,7 @@ function isCommandToken(command, token) {
       "login",
       "logout",
       "config",
+      "skill",
       "update",
       "version"
     ].includes(token);
@@ -70,6 +71,9 @@ function isCommandToken(command, token) {
   if (command[0] === "config") {
     return ["get", "set"].includes(token);
   }
+  if (command[0] === "skill") {
+    return ["install", "print", "status"].includes(token);
+  }
   if (command[0] === "games") {
     return ["search", "count", "aggregate", "resolve", "benchmark", "detail", "analysis", "compare", "topics", "success-report"].includes(token);
   }

package/src/config.js

@@ -13,6 +13,7 @@ import {
 import { matches } from "./args.js";
 import { writeJsonError } from "./output.js";
 import { runBrowserLogin } from "./browser-login.js";
+import { handleSkillInstall, handleSkillPrint, handleSkillStatus } from "./skill.js";
 
 export function loadConfig() {
   const configPath = resolveConfigPath(process.env.GMC_CONFIG_PATH);
@@ -89,6 +90,18 @@ function resolveAuthMode({ envApiKey, envCliCredential, fileConfig }) {
 }
 
 export async function handleLocalCommand(command, options, positional, config) {
+  if (matches(command, ["skill", "install"])) {
+    return handleSkillInstall(options);
+  }
+
+  if (matches(command, ["skill", "print"])) {
+    return handleSkillPrint(options);
+  }
+
+  if (matches(command, ["skill", "status"])) {
+    return handleSkillStatus();
+  }
+
   if (matches(command, ["login"])) {
     const apiKey = options["api-key"];
     const apiBaseUrl = options["api-base-url"] || options["base-url"] || config.apiBaseUrl;

package/src/constants.js

@@ -8,7 +8,7 @@ export const EXIT_API = 4;
 
 export const CLI_PACKAGE_NAME = "@witchpot/gmc";
 export const CLI_BETA_PACKAGE_NAME = "@witchpot/gmc";
-export const CLI_VERSION = "0.1.6";
+export const CLI_VERSION = "0.1.8";
 
 export const DEFAULT_API_BASE_URL = "https://gamemarketcopilot.com";
 export const DEFAULT_CONFIG_PATH = path.join(homedir(), ".config", "gmc", "config.json");
@@ -19,6 +19,9 @@ export const SUPPORTED_BETA_COMMANDS = [
   "gmc schema --json",
   "gmc --version",
   "gmc update --json",
+  "gmc skill install --json",
+  "gmc skill print --format agents-md",
+  "gmc skill status --json",
   "gmc games search --source steam --query <text> --json",
   "gmc games count --source steam --release-year <year> --reviews-gt <number> --json",
   "gmc games aggregate --source steam --metric count,median_reviews --group-by release_year --json",

package/src/help.js

@@ -21,6 +21,9 @@ Usage:
   gmc update --json
   gmc config get --json
   gmc config set apiBaseUrl <url>
+  gmc skill install [--global] --json
+  gmc skill print --format agents-md
+  gmc skill status --json
   gmc schema --json
   gmc games search --source steam --query <text> --json
   gmc games count --source steam --release-year <year> --reviews-gt <number> --json

package/src/main.js

@@ -48,6 +48,10 @@ export async function main(argv = process.argv.slice(2)) {
   const config = loadConfig();
   const localOutput = await handleLocalCommand(command, options, positional, config);
   if (localOutput) {
+    if (typeof localOutput.raw === "string") {
+      process.stdout.write(localOutput.raw);
+      process.exit(0);
+    }
     process.stdout.write(`${JSON.stringify(applyOutputProjection(localOutput, {
       fields: options.fields,
       preset: options.preset

package/src/skill.js

@@ -0,0 +1,132 @@
+import { cpSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { EXIT_USAGE } from "./constants.js";
+import { writeJsonError } from "./output.js";
+
+export const SKILL_NAME = "gmc-analysis";
+const SKILL_REFERENCE_FILES = ["recipes.md", "pitfalls.md", "quota.md"];
+const PACKAGED_SKILL_DIR = fileURLToPath(new URL(`../skill/${SKILL_NAME}/`, import.meta.url));
+
+export function getPackagedSkillDir() {
+  return PACKAGED_SKILL_DIR;
+}
+
+export function readSkillVersion(skillDir) {
+  try {
+    const source = readFileSync(path.join(skillDir, "SKILL.md"), "utf8");
+    const frontmatter = source.match(/^---\n([\s\S]*?)\n---/);
+    const version = frontmatter?.[1].match(/^\s*version:\s*"?([0-9][0-9A-Za-z.\-]*)"?\s*$/m);
+    return version?.[1] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function installTargets(cwd = process.cwd()) {
+  return {
+    project: path.join(cwd, ".claude", "skills", SKILL_NAME),
+    global: path.join(homedir(), ".claude", "skills", SKILL_NAME)
+  };
+}
+
+export function handleSkillInstall(options) {
+  const targets = installTargets();
+  const target = options.dir
+    ? path.resolve(String(options.dir))
+    : options.global
+      ? targets.global
+      : targets.project;
+  mkdirSync(path.dirname(target), { recursive: true });
+  cpSync(PACKAGED_SKILL_DIR, target, { recursive: true });
+
+  return {
+    data: {
+      ok: true,
+      skill: SKILL_NAME,
+      version: readSkillVersion(PACKAGED_SKILL_DIR),
+      installedPath: target,
+      scope: options.dir ? "custom" : options.global ? "global" : "project",
+      next: [
+        "Claude Code picks up project skills from .claude/skills automatically.",
+        "For Codex or other AGENTS.md-based agents run: gmc skill print --format agents-md >> AGENTS.md"
+      ]
+    }
+  };
+}
+
+/**
+ * Self-contained AGENTS.md edition: the SKILL.md body with every reference
+ * inlined (AGENTS.md consumers do not receive the skill directory), heading
+ * levels demoted so the section nests under an existing document.
+ */
+export function buildAgentsMdSection() {
+  const version = readSkillVersion(PACKAGED_SKILL_DIR);
+  const body = stripFrontmatter(readFileSync(path.join(PACKAGED_SKILL_DIR, "SKILL.md"), "utf8"));
+  const references = SKILL_REFERENCE_FILES.map((file) =>
+    readFileSync(path.join(PACKAGED_SKILL_DIR, "references", file), "utf8")
+  );
+
+  return [
+    `<!-- ${SKILL_NAME} skill v${version} - generated by \`gmc skill print --format agents-md\`; refresh by re-running it after CLI updates -->`,
+    demoteHeadings(body.trim(), 1),
+    ...references.map((content) => demoteHeadings(content.trim(), 2))
+  ].join("\n\n") + "\n";
+}
+
+export function handleSkillPrint(options) {
+  const format = String(options.format ?? "agents-md");
+  if (format === "agents-md") {
+    return { raw: buildAgentsMdSection() };
+  }
+  if (format === "skill-md") {
+    return { raw: readFileSync(path.join(PACKAGED_SKILL_DIR, "SKILL.md"), "utf8") };
+  }
+
+  writeJsonError({
+    code: "CLI_USAGE_ERROR",
+    message: "--format must be one of: agents-md, skill-md"
+  });
+  process.exit(EXIT_USAGE);
+}
+
+export function handleSkillStatus() {
+  const targets = installTargets();
+  const packagedVersion = readSkillVersion(PACKAGED_SKILL_DIR);
+  const installs = Object.entries(targets).map(([scope, dir]) => {
+    const installed = existsSync(path.join(dir, "SKILL.md"));
+    const version = installed ? readSkillVersion(dir) : null;
+    return {
+      scope,
+      path: dir,
+      installed,
+      version,
+      ...(installed && version !== packagedVersion ? { stale: true } : {})
+    };
+  });
+
+  return {
+    data: {
+      skill: SKILL_NAME,
+      packaged: {
+        version: packagedVersion,
+        path: PACKAGED_SKILL_DIR
+      },
+      installs
+    },
+    ...(installs.some((entry) => entry.stale)
+      ? { warnings: ["An installed copy is older than the packaged skill. Re-run gmc skill install."] }
+      : {})
+  };
+}
+
+function stripFrontmatter(source) {
+  return source.replace(/^---\n[\s\S]*?\n---\n/, "");
+}
+
+function demoteHeadings(markdown, levels) {
+  const prefix = "#".repeat(levels);
+  return markdown.replace(/^(#{1,4}) /gm, `${prefix}$1 `);
+}

package/src/skill.test.js

@@ -0,0 +1,65 @@
+import assert from "node:assert/strict";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import {
+  buildAgentsMdSection,
+  getPackagedSkillDir,
+  handleSkillInstall,
+  handleSkillStatus,
+  readSkillVersion
+} from "./skill.js";
+
+test("packaged skill declares a parseable version", () => {
+  const version = readSkillVersion(getPackagedSkillDir());
+  assert.match(version ?? "", /^\d+\.\d+\.\d+$/);
+});
+
+test("agents-md edition is self-contained and demotes headings", () => {
+  const section = buildAgentsMdSection();
+
+  assert.match(section, /^<!-- gmc-analysis skill v\d+\.\d+\.\d+/);
+  assert.match(section, /^## GMC Analysis/m);
+  // References must be inlined for AGENTS.md consumers without the skill dir.
+  assert.match(section, /^### Recipes/m);
+  assert.match(section, /^### Pitfalls and pivots/m);
+  assert.match(section, /^### Quota etiquette/m);
+  // Core field-test learnings must survive into the distributed edition.
+  assert.match(section, /skippedReasons/);
+  assert.match(section, /appearsInGames/);
+});
+
+test("skill install copies the packaged skill to a custom directory", () => {
+  const targetRoot = mkdtempSync(path.join(tmpdir(), "gmc-skill-install-"));
+  const targetDir = path.join(targetRoot, "gmc-analysis");
+  try {
+    const result = handleSkillInstall({ dir: targetDir });
+
+    assert.equal(result.data.ok, true);
+    assert.equal(result.data.scope, "custom");
+    assert.equal(result.data.installedPath, targetDir);
+    assert.ok(existsSync(path.join(targetDir, "SKILL.md")));
+    assert.ok(existsSync(path.join(targetDir, "references", "pitfalls.md")));
+    assert.equal(
+      readFileSync(path.join(targetDir, "SKILL.md"), "utf8"),
+      readFileSync(path.join(getPackagedSkillDir(), "SKILL.md"), "utf8")
+    );
+    assert.equal(readSkillVersion(targetDir), result.data.version);
+  } finally {
+    rmSync(targetRoot, { recursive: true, force: true });
+  }
+});
+
+test("skill status reports packaged version and install slots", () => {
+  const result = handleSkillStatus();
+
+  assert.equal(result.data.skill, "gmc-analysis");
+  assert.match(result.data.packaged.version ?? "", /^\d+\.\d+\.\d+$/);
+  const scopes = result.data.installs.map((entry) => entry.scope).sort();
+  assert.deepEqual(scopes, ["global", "project"]);
+  for (const entry of result.data.installs) {
+    assert.equal(typeof entry.installed, "boolean");
+  }
+});