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,61 @@
----
-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` mapping block in a project guidance file.
+
+```bash
+npx @tanstack/intent@latest install [--dry-run] [--print-prompt] [--global] [--global-only]
+```
+
+## Options
+
+- `--dry-run`: print the generated mapping block without writing files
+- `--print-prompt`: print the agent setup prompt instead of writing files
+- `--global`: include global packages after project packages
+- `--global-only`: install mappings from global packages only
+
+## Behavior
+
+- Scans project-local packages by default.
+- Includes global packages only when `--global` or `--global-only` is passed.
+- Creates `AGENTS.md` when actionable skills are found and no managed block exists.
+- Updates an existing managed block in a supported config file.
+- Preserves all content outside the managed block.
+- Skips reference, meta, maintainer, and maintainer-only skills.
+- Writes compact `when` and `use` entries instead of load paths.
+- Verifies the managed block before reporting success.
+- Prints `No actionable intent skills found.` and does not create a config file when no actionable skills are discovered.
+
+Supported config files: `AGENTS.md`, `CLAUDE.md`, `.cursorrules`, `.github/copilot-instructions.md`.
+
+## Output
+
+The generated block uses compact skill identities:
+
+```yaml
+<!-- intent-skills:start -->
+# Skill mappings - resolve `use` with `npx @tanstack/intent@latest resolve <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.`
+- No actionable skills: `No actionable intent skills found.`
+
+## Related
+
+- [intent list](./intent-list)
+- [intent resolve](./intent-resolve)
+- [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 `, `; 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",
+      "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-resolve.md

@@ -0,0 +1,63 @@
+---
+title: intent resolve
+id: intent-resolve
+---
+
+`intent resolve` resolves a compact skill identity to the skill file path reported by the current install.
+
+```bash
+npx @tanstack/intent@latest resolve <package>#<skill> [--json] [--global] [--global-only]
+```
+
+## Options
+
+- `--json`: print structured JSON instead of only the path
+- `--global`: resolve from project packages first, then global packages
+- `--global-only`: resolve 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 the resolved skill path by default
+- Returns scanner-reported paths, including package-manager-internal paths for transitive installs
+
+The package can be scoped or unscoped. The skill can include slash-separated sub-skill names.
+
+Examples:
+
+```bash
+npx @tanstack/intent@latest resolve @tanstack/query#fetching
+npx @tanstack/intent@latest resolve @tanstack/query#core/fetching
+npx @tanstack/intent@latest resolve some-lib#core
+```
+
+## JSON output
+
+`--json` prints:
+
+```json
+{
+  "package": "@tanstack/query",
+  "skill": "fetching",
+  "path": "node_modules/@tanstack/query/skills/fetching/SKILL.md",
+  "source": "local",
+  "version": "5.0.0",
+  "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 resolve",
+          "to": "cli/intent-resolve"
+        },
         {
           "label": "intent meta",
           "to": "cli/intent-meta"