intent list

intent list discovers skill-enabled packages and shows the skills available under the project's permissions and exclusions. It does not change permissions or write guidance.

npx @tanstack/intent@latest list [--json] [--debug] [--global] [--global-only] [--show-hidden] [--no-notices]

Options#

Output#

• --json: print structured skills, packages, and diagnostics instead of text output

• --debug: print discovery details to stderr, including scan counts and package.json reads

• --show-hidden: include a hidden-source summary in text output when run outside an agent session

• --no-notices: suppress non-critical notices in text mode; the notice for intent.skills: ["*"] remains visible

Scan scope#

• --global: include global packages after project packages

• --global-only: list global packages only

Behavior#

Default list#

Intent scans project and workspace dependencies, applies package.json#intent.skills, then removes packages and skills matched by intent.exclude. It uses project node_modules when available and Yarn's PnP API in PnP projects without usable node_modules.

Global packages are scanned only with --global or --global-only. When both local and global copies of a package are found, the local copy takes precedence. Version conflicts show the chosen package and other discovered versions and paths.

Run intent install to configure permissions on first use. Listing skills does not open the install picker.

Which skills appear#

The nearest configured intent.skills list applies, including inherited workspace permissions. Each entry enables a package, a package pattern, or one exact skill:

Workspace patterns and individual skills also use the workspace: prefix, such as workspace:@scope/* and workspace:@scope/internal#testing. Package patterns support *; individual-skill entries require an exact package and skill name. Git sources are not supported.

• No configured list: all discovered sources appear, with a migration notice. This is the existing-project upgrade path; a future version will require explicit permissions.

• An empty list ([]): no sources are permitted, with an informational notice.

• All sources (["*"]): all discovered sources appear, with a notice that unvetted skills may enter agent guidance.

  Permissions select sources and skill names. They do not freeze skill content when dependencies update. See Configuration and Trust model.

Exclusions#

intent.exclude takes precedence over permissions. Intent combines exclusions from package.json files between the workspace or project root and the current directory.

Only exact names and * wildcards are supported. Excluded packages do not trigger unlisted-source notices. Manage exclusions with intent exclude.

Hidden sources#

Packages outside an explicit allowlist are omitted from the available catalog. In a human session, a policy notice names them; --show-hidden adds their names and skill counts to the text output. This does not enable them.

In agent sessions, hidden sources are reported by count only. --show-hidden cannot reveal their identities there; run it outside the agent session to review candidates. A configured package or package pattern that was not discovered also produces a notice.

Default output#

Text output includes:

• A summary with package and skill counts.

• A package table with PACKAGE, SOURCE, VERSION, and SKILLS columns.

• A skill tree grouped by package, with descriptions and commands to load each skill.

• Version conflicts and discovery warnings, when present.

  Load commands use the detected package manager and preserve the selected global scan scope. SOURCE distinguishes local discovery from explicit global scanning.

  Text output and discovery warnings go to stdout. Policy notices and --debug details go to stderr.

JSON output#

--json prints a structured catalog to stdout. This example shows one available skill with no hidden sources or diagnostics; paths and package metadata vary by project:

{
  "skills": [
    {
      "use": "@tanstack/query#fetching",
      "packageName": "@tanstack/query",
      "packageRoot": "/path/to/project/node_modules/@tanstack/query",
      "packageVersion": "5.0.0",
      "packageSource": "local",
      "skillName": "fetching",
      "description": "Query data fetching patterns",
      "type": "core",
      "framework": "react"
    }
  ],
  "packages": [
    {
      "name": "@tanstack/query",
      "version": "5.0.0",
      "source": "local",
      "packageRoot": "/path/to/project/node_modules/@tanstack/query",
      "skillCount": 1
    }
  ],
  "hiddenSourceCount": 0,
  "hiddenSources": [],
  "warnings": [],
  "notices": [],
  "conflicts": []
}

JSON includes diagnostics in the object instead of printing separate warning or notice blocks. --debug still writes to stderr. Treat identifiers as data when constructing commands; JSON does not contain shell-escaped arguments.

Status messages#

Common errors#

• Invalid permissions or unreadable policy files: Intent stops and reports the problem. Fix the reported package.json or intent.skills entry before retrying.

• Unsupported runnable identifier: generated commands accept only ASCII letters, numbers, _, ., /, @, #, and -. Identifiers cannot start with #; leading and trailing whitespace is rejected rather than trimmed. Rename the package or skill to generate runnable guidance. --json can still expose permitted identifiers as data.

• Unreadable or out-of-package skill metadata: discovery skips skill files whose real path cannot be resolved or lies outside the package root, with a warning. It checks the opened file's identity before reading and uses that descriptor for the full metadata read, including large frontmatter, so later pathname replacement cannot redirect the read. Symlinks within the resolved package root remain supported.

• Deno without node_modules: this discovery mode is unsupported.

Related#

• intent install
• intent load
• intent exclude
• Configuration
• Trust model