feat: add compact skill resolution for install mappings

.changeset/yummy-balloons-bow.md

@@ -0,0 +1,9 @@
+---
+'@tanstack/intent': patch
+---
+
+Add compact skill mappings and runtime resolution for agent config setup.
+
+`intent install` now writes verified `intent-skills` blocks with compact `when`/`use` entries instead of embedding `load` paths. This keeps generated config portable across npm, pnpm, Bun, and Deno node_modules layouts, including transitive/package-manager-internal installs.
+
+Add `intent resolve <package>#<skill>` to resolve compact mappings to the installed skill path at runtime, with `--json`, `--global`, and `--global-only` support. `intent list`, `intent install`, and `intent resolve` now scan local project packages by default and require explicit global flags for global package scanning.

docs/cli/intent-install.md

@@ -1,41 +1,81 @@
----
-title: intent install
-id: intent-install
----
-
-`intent install` prints instructions for setting up an `intent-skills` mapping block in your project guidance file.
-
-```bash
-npx @tanstack/intent@latest install
-```
-
-The command prints text only. It does not edit files.
-
-## Output
-
-The printed instructions include this tagged block template:
-
-```yaml
-<!-- intent-skills:start -->
-# Skill mappings — when working in these areas, load the linked skill file into context.
-skills:
-  - task: "describe the task or code area here"
-    load: "node_modules/package-name/skills/skill-name/SKILL.md"
-<!-- intent-skills:end -->
-```
-
-They also ask you to:
-
-1. Check for an existing block first
-2. Run `intent list` to discover installed skills, including any packages surfaced by the command's explicit global scan
-3. Ask whether you want a config target other than `AGENTS.md`
-4. Update an existing block in place when one already exists
-5. Add task-to-skill mappings
-6. Preserve all content outside the tagged block
-
-If no existing block is found, `AGENTS.md` is the default target.
-
-## Related
-
-- [intent list](./intent-list)
-- [Quick Start for Consumers](../getting-started/quick-start-consumers)
+---
+title: intent install
+id: intent-install
+---
+
+`intent install` creates or updates an `intent-skills` guidance block in a project guidance file.
+
+```bash
+npx @tanstack/intent@latest install [--map] [--dry-run] [--print-prompt] [--global] [--global-only]
+```
+
+## Options
+
+- `--map`: write explicit task-to-skill mappings instead of lightweight loading guidance
+- `--dry-run`: print the generated block without writing files
+- `--print-prompt`: print the agent setup prompt instead of writing files
+- `--global`: include global packages after project packages when `--map` is passed
+- `--global-only`: install mappings from global packages only when `--map` is passed
+
+## Behavior
+
+- Writes lightweight skill loading guidance by default.
+- Creates `AGENTS.md` when no managed block exists.
+- Updates an existing managed block in a supported config file.
+- Preserves all content outside the managed block.
+- Scans packages and writes compact `when` and `use` mappings only when `--map` is passed.
+- Skips reference, meta, maintainer, and maintainer-only skills in `--map` mode.
+- Writes compact `when` and `use` entries instead of load paths in `--map` mode.
+- Verifies the managed block before reporting success.
+- Prints `No intent-enabled skills found.` and does not create a config file when `--map` finds no actionable skills.
+
+Supported config files: `AGENTS.md`, `CLAUDE.md`, `.cursorrules`, `.github/copilot-instructions.md`.
+
+## Default output
+
+The default block tells agents to discover skills and load matching guidance on demand:
+
+```markdown
+<!-- intent-skills:start -->
+## Skill Loading
+
+Before substantial work:
+- Skill check: run `npx @tanstack/intent@latest list`, or use skills already listed in context.
+- Skill guidance: if one local skill clearly matches the task, run `npx @tanstack/intent@latest load <package>#<skill>` and follow the returned `SKILL.md`.
+- Monorepos: when working across packages, run the skill check from the workspace root and prefer the local skill for the package being changed.
+- Multiple matches: prefer the most specific local skill for the package or concern you are changing; load additional skills only when the task spans multiple packages or concerns.
+<!-- intent-skills:end -->
+```
+
+## Mapping output
+
+`--map` writes compact skill identities:
+
+```yaml
+<!-- intent-skills:start -->
+# Skill mappings - load `use` with `npx @tanstack/intent@latest load <use>`.
+skills:
+  - when: "Query data fetching patterns"
+    use: "@tanstack/query#fetching"
+<!-- intent-skills:end -->
+```
+
+- `when`: task-routing phrase for agents
+- `use`: portable skill identity in `<package>#<skill>` format
+- The block does not store `load` paths, absolute paths, or package-manager-internal paths
+
+## Status messages
+
+- Created: `Created AGENTS.md with 1 mapping.`
+- Updated: `Updated AGENTS.md with 2 mappings.`
+- Unchanged: `No changes to AGENTS.md; 2 mappings already current.`
+- Guidance created: `Created AGENTS.md with skill loading guidance.`
+- Guidance unchanged: `No changes to AGENTS.md; skill loading guidance already current.`
+- Placement tip: `Tip: Keep the intent-skills block near the top of AGENTS.md so agents read it before task-specific instructions.`
+- No actionable skills in `--map` mode: `No intent-enabled skills found.`
+
+## Related
+
+- [intent list](./intent-list)
+- [intent load](./intent-load)
+- [Quick Start for Consumers](../getting-started/quick-start-consumers)

docs/cli/intent-list.md

@@ -1,70 +1,105 @@
----
-title: intent list
-id: intent-list
----
-
-`intent list` discovers skill-enabled packages and prints available skills.
-
-```bash
-npx @tanstack/intent@latest list [--json]
-```
-
-## Options
-
-- `--json`: print JSON instead of text output
-
-## What you get
-
-- Scans project and workspace dependencies for intent-enabled packages and skills
-- Intentionally includes accessible global packages when listing installed skills
-- Includes warnings from discovery
-- If no packages are discovered, prints `No intent-enabled packages found.`
-- Summary line with package count, skill count, and detected package manager
-- Package table columns: `PACKAGE`, `SOURCE`, `VERSION`, `SKILLS`, `REQUIRES`
-- Skill tree grouped by package
-- Optional warnings section (`⚠ ...` per warning)
-
-`REQUIRES` uses `intent.requires` values joined by `, `; empty values render as `–`.
-`SOURCE` is a lightweight indicator showing whether the selected package came from local discovery or explicit global scanning.
-
-## JSON output
-
-`--json` prints the `ScanResult` object:
-
-```json
-{
-  "packageManager": "npm | pnpm | yarn | bun | unknown",
-  "packages": [
-    {
-      "name": "string",
-      "version": "string",
-      "source": "local | global",
-      "intent": {
-        "version": 1,
-        "repo": "string",
-        "docs": "string",
-        "requires": ["string"]
-      },
-      "skills": [
-        {
-          "name": "string",
-          "path": "string",
-          "description": "string",
-          "type": "string (optional)",
-          "framework": "string (optional)"
-        }
-      ]
-    }
-  ],
-  "warnings": ["string"]
-}
-```
-
-`packages` are ordered using `intent.requires` when possible. When the same package exists both locally and globally, `intent list` prefers the local package.
-
-## Common errors
-
-- Scanner failures are printed as errors
-- Unsupported environments:
-  - Yarn PnP without `node_modules`
-  - Deno projects without `node_modules`
+---
+title: intent list
+id: intent-list
+---
+
+`intent list` discovers skill-enabled packages and prints available skills.
+
+```bash
+npx @tanstack/intent@latest list [--json] [--global] [--global-only]
+```
+
+## Options
+
+- `--json`: print JSON instead of text output
+- `--global`: include global packages after project packages
+- `--global-only`: list global packages only
+
+## What you get
+
+- Scans project and workspace dependencies for intent-enabled packages and skills
+- Includes global packages only when `--global` or `--global-only` is passed
+- Includes warnings from discovery
+- If no packages are discovered, prints `No intent-enabled packages found.`
+- Summary line with package count, skill count, and detected package manager
+- Package table columns: `PACKAGE`, `SOURCE`, `VERSION`, `SKILLS`, `REQUIRES`
+- Skill tree grouped by package
+- Optional warnings section (`⚠ ...` per warning)
+
+`REQUIRES` uses `intent.requires` values joined by a comma and space; empty values render as `–`.
+`SOURCE` is a lightweight indicator showing whether the selected package came from local discovery or explicit global scanning.
+When both local and global packages are scanned, local packages take precedence.
+
+## JSON output
+
+`--json` prints the `ScanResult` object:
+
+```json
+{
+  "packageManager": "npm | pnpm | yarn | bun | unknown",
+  "packages": [
+    {
+      "name": "string",
+      "version": "string",
+      "source": "local | global",
+      "packageRoot": "string",
+      "intent": {
+        "version": 1,
+        "repo": "string",
+        "docs": "string",
+        "requires": ["string"]
+      },
+      "skills": [
+        {
+          "name": "string",
+          "path": "string",
+          "description": "string",
+          "type": "string (optional)",
+          "framework": "string (optional)"
+        }
+      ]
+    }
+  ],
+  "warnings": ["string"],
+  "conflicts": [
+    {
+      "packageName": "string",
+      "chosen": {
+        "version": "string",
+        "packageRoot": "string"
+      },
+      "variants": [
+        {
+          "version": "string",
+          "packageRoot": "string"
+        }
+      ]
+    }
+  ],
+  "nodeModules": {
+    "local": {
+      "path": "string | null",
+      "detected": true,
+      "exists": true,
+      "scanned": true
+    },
+    "global": {
+      "path": "string | null",
+      "detected": true,
+      "exists": true,
+      "scanned": false,
+      "source": "string (optional)"
+    }
+  }
+}
+```
+
+`packages` are ordered using `intent.requires` when possible.
+When the same package exists both locally and globally and global scanning is enabled, `intent list` prefers the local package.
+
+## Common errors
+
+- Scanner failures are printed as errors
+- Unsupported environments:
+  - Yarn PnP without `node_modules`
+  - Deno projects without `node_modules`

docs/cli/intent-load.md

@@ -0,0 +1,66 @@
+---
+title: intent load
+id: intent-load
+---
+
+`intent load` loads a compact skill identity from the current install and prints the matching `SKILL.md` content.
+
+```bash
+npx @tanstack/intent@latest load <package>#<skill> [--path] [--json] [--global] [--global-only]
+```
+
+## Options
+
+- `--path`: print the resolved skill path instead of the file content
+- `--json`: print structured JSON with metadata and content
+- `--global`: load from project packages first, then global packages
+- `--global-only`: load from global packages only
+
+## What you get
+
+- Validates `<package>#<skill>` before scanning
+- Scans project-local packages by default
+- Includes global packages only when `--global` or `--global-only` is passed
+- Prefers local packages when `--global` is used and the same package exists locally and globally
+- Prints raw `SKILL.md` content by default
+- Prints the scanner-reported path when `--path` is passed
+
+The package can be scoped or unscoped. The skill can include slash-separated sub-skill names.
+
+Examples:
+
+```bash
+npx @tanstack/intent@latest load @tanstack/query#fetching
+npx @tanstack/intent@latest load @tanstack/query#core/fetching
+npx @tanstack/intent@latest load some-lib#core --path
+```
+
+## JSON output
+
+`--json` prints:
+
+```json
+{
+  "package": "@tanstack/query",
+  "skill": "fetching",
+  "path": "node_modules/@tanstack/query/skills/fetching/SKILL.md",
+  "packageRoot": "node_modules/@tanstack/query",
+  "source": "local",
+  "version": "5.0.0",
+  "content": "---\nname: fetching\n---\n\n...",
+  "warnings": []
+}
+```
+
+## Common errors
+
+- Missing separator: `Invalid skill use "@tanstack/query": expected <package>#<skill>.`
+- Empty package: `Invalid skill use "#core": package is required.`
+- Empty skill: `Invalid skill use "@tanstack/query#": skill is required.`
+- Missing package: `Cannot resolve skill use "...": package "..." was not found.`
+- Missing skill: `Cannot resolve skill use "...": skill "..." was not found in package "...".`
+
+## Related
+
+- [intent list](./intent-list)
+- [intent install](./intent-install)

docs/config.json

@@ -38,6 +38,10 @@
           "label": "intent list",
           "to": "cli/intent-list"
         },
+        {
+          "label": "intent load",
+          "to": "cli/intent-load"
+        },
         {
           "label": "intent meta",
           "to": "cli/intent-meta"