repository·main·Indexed 43 days ago
https://github.com/tanstack/intentA CLI tool for library maintainers to manage Agent Skills. It enables developers to auto-discover, validate, and ship skills compatible with the Agent Skills standard, ensuring they are versioned alongside library code. Features include skill loading guidance for agent configuration files, maintainer workflows for authoring and syncing skills, and an evaluation suite for measuring Copilot discovery and invocation.
When planning your file tree, use the following criteria to decide if content belongs in a core skill or a framework skill.
| Content | Goes in... |
|---|---|
| Mental models, concepts, lifecycle | Core |
| Configuration options and their effects | Core |
| Type system, generics, inference | Core |
| Common mistakes that apply to all frameworks | Core |
Hooks (useX, createX) | Framework |
Components (<Link>, <Outlet>) | Framework |
| Provider setup and wiring | Framework |
| SSR/hydration patterns specific to a framework | Framework |
| Framework-specific gotchas | Framework |
Important Rules:
SKILL.md for shared patterns and separate references/[adapter].md files for specific details.Intent operates across six lifecycle stages. It can observe and verify the first four stages, but the final two depend entirely on the agent's behavior.
| State | Meaning | Observable by Intent |
|---|---|---|
| 1. Available | Skill discovered from an installed or workspace package. | Yes |
| 2. Permitted | Project policy allows the package/skill to surface (not removed by intent.exclude). | Yes |
| 3. Loaded | A supported load path resolved the skill and returned its content. | Yes |
| 4. Delivered | Intent placed guidance where an agent can access it (e.g., session hook context). | Yes (output only) |
| 5. Activated | The agent selected or received the skill for a task. | No |
| 6. Applied | The model followed the skill correctly. | No |
Note: Observing an intent load command does not guarantee the skill was relevant or that the model successfully used the guidance.
By default, intent install creates a guidance block that instructs agents to discover skills and load matching guidance on demand. This block is inserted into supported config files like AGENTS.md.
Default Block Structure:
<!-- intent-skills:start -->
## Skill Loading
Before editing files for a substantial task:
- Run `npx @tanstack/intent@latest list` from the workspace root to see available local skills.
- If a listed skill matches the task, run `npx @tanstack/intent@latest load <package>#<skill>` before changing files.
- Use the loaded `SKILL.md` guidance while making the change.
- 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 -->Tip: Keep the intent-skills block near the top of your guidance file (e.g., AGENTS.md) so agents read it before task-specific instructions.
Every authoring batch in TanStack Intent must incrementally maintain three cumulative planning documents. These documents serve as the official record of library domains, developer tasks, maintainer decisions, coverage, and remaining work. Do not replace these documents with only the tasks from a single batch; they must be cumulative.
domain_map.yaml: Manages domain/task relationships, supported failure modes, cross-references, tensions, and knowledge gaps. It ensures task slugs and package ownership stay aligned with skills.skill_spec.md: A human-readable record of coverage and decisions. It must include a Coverage and batch history section recording assessed scope, completed batches (with source revision/version), consequential decisions, check outcomes, and remaining work. Distinguish between implemented guidance and planned work.skill_tree.yaml: Manages skill identities, paths, prerequisites, source mappings, and package placement. It tracks planned or retired statuses and maintains links to the other artifacts.Note: .intent/review-state.json records review evidence but is not a replacement for these three documents.
To ensure that generated skill content is consistently consumed by all major AI coding agents, follow these formatting rules:
```ts).## for section boundaries.SKILL.md must be self-contained, except for dependencies declared in the requires field.The state of your intent.skills configuration changes how Intent behaves and what notices it emits to stderr:
| Form | Result | Notice |
|---|---|---|
| Absent (no key) | Discovery commands surface every discovered package. | Deprecation notice until configured. |
Empty ("skills": []) | Surfaces no packages. | Info notice on stderr. |
Wildcard ("skills": ["*"]) | Permits every discovered package across all scopes/kinds. | Acknowledged-risk notice (unvetted skills may reach your agent). |
To improve agent output, identify how different skills interact through tensions and references.
Identify structural pulls where optimizing for one task makes another harder. A tension is not a failure mode, but a design tradeoff.
Identify skills that illuminate each other without conflicting. These become "See also" pointers.
tanstack-intent keyword. The registry periodically searches npm for this keyword, downloads the package tarball, extracts all skills/**/SKILL.md files, and indexes their contents. Every new version you publish is automatically indexed.The intent.skills configuration in your package.json determines which packages and specific skills are visible to Intent. The nearest configured list (including inherited workspace permissions) applies.
| Rule Pattern | Effect |
|---|---|
"*" | Enables all discovered npm and workspace sources (all packages and skills). |
"@tanstack/query" | Enables all skills within that specific npm package. |
"@tanstack/*" | Enables all skills in any matching npm packages. |
"@tanstack/query#fetching" | Enables only the fetching skill within that package. |
"workspace:@scope/internal" | Enables all skills in a specific workspace package. |
"workspace:@scope/internal#testing" | Enables only the testing skill in a specific workspace package. |
*. Individual skill entries require an exact package and skill name.[]): No sources are permitted; an informational notice is shown.When distributing skills, be aware of how versioning works across different installers:
--pin <tag-or-sha> with gh skill add or use a specific reference like owner/repo@<tag> for Claude marketplace sources.version field, you must manually bump this version on every plugin release. If no version is declared, Git-based Claude installs default to the source commit.The skill-staleness-check is an autonomous workflow triggered by upstream TanStack webhooks. It ensures that SKILL.md files remain accurate when source code changes. The workflow follows these logical steps:
changed_files from a webhook against the sources defined in SKILL.md frontmatter (using Owner/repo:relative-path and glob patterns).generate-skill meta-skill in "regeneration mode" (surgical updates rather than full rewrites).library_version in frontmatter.require them.skills/sync-state.json file is updated with the new library_version and source file SHAs.