Quick Start for Maintainers

After setup, request library changes as usual; Intent’s maintainer commands keep skill metadata consistent and record source-review evidence before handoff.

Install#

Enable the maintainer workflow#

Run maintainer setup from the library repository:

This registers existing package-owned skills, copies the CI workflow when missing, and creates missing planning records and an intent-maintainer block in AGENTS.md, or updates the file that already contains an Intent maintainer or consumer block. It preserves surrounding instructions and a separate intent-skills consumer block. Review this setup diff and keep it in the repository so later agent sessions receive the same authoring and review procedure.

Create the first useful batch#

Ask your coding agent for the developer tasks the library should support. For example:

Create a skill batch covering safe retries, cancellation, and pagination. Use our public examples and tests, and include executable checks for the important failure cases.

The installed instructions load Intent's generate-skill procedure. The agent reads the relevant source, tests, examples, docs, and existing skills; proposes a bounded batch when its scope is undecided; and creates or updates the guidance owned by those tasks. A focused batch does not require a full-library interview or a fixed number of skills.

Use maintainer add to create or register each agreed skill, keeping the file beside the owning package:

Run it from the repository root and pass --package for a workspace package, or run it inside that package's directory and the command registers the skill there. Omit --package for a standalone library. Repeat --task for each developer task the skill covers; it records them in domain_map.yaml so maintainer check does not ask for them later. For existing guidance, supply its name, domain, package, and path; the command preserves the file and reads its frontmatter. The maintainer command reference covers custom paths, prerequisites, and retiring a skill with maintainer remove.

Every skill batch also creates or incrementally updates three planning documents. These records preserve prior scope, maintainer decisions, exclusions, source mappings, and remaining work across later batches.

skills/
  task-name/
    SKILL.md
  _artifacts/
    domain_map.yaml
    skill_spec.md
    skill_tree.yaml

_artifacts/
  domain_map.yaml
  skill_spec.md
  skill_tree.yaml
packages/
  client/
    skills/
      task-name/
        SKILL.md

Existing custom skill and artifact locations are retained when supported. The domain map records domains and developer tasks, the spec records readable coverage and decisions, and the tree records skill placement, prerequisites, and source mappings.

Review the resulting skills, planning documents, and checks as one batch:

A missing runtime or independent run remains explicitly unverified. Structural validation alone does not establish task correctness, skill discovery, or fresh-consumer behavior.

For direct authoring guidance, load meta generate-skill. Explicitly requested full-library design still uses meta domain-discovery, then meta tree-generator, then meta generate-skill.

Choose how consumers install the skills#

Skills ship with their owning npm package by default. Repository installers and native plugins are optional additional distribution routes.

Selecting skills for repository distribution requires registered, authored skills: maintainer sync refuses to generate exports while a selected skill still carries the intent:needs-authoring marker. On a brand-new library, author the batch first, then rerun setup with the selection. Select the public skills explicitly:

Use the actual registered names; each must be a tree entry whose SKILL.md exists. When the repository, plugin name, or selection cannot be resolved, setup reports every missing input in one error. This records the selection in the skill tree. maintainer sync generates plugin metadata pointing to the existing package directories and prints consumer commands for npx skills add and gh skill add. Consumers can also use the native Claude or Cursor plugin flow. No second copy of the skill text is created, and later skills are not added automatically.

To explicitly record package-only distribution or turn off earlier repository exports:

A repository discovery skill can help developers decide whether the library fits before installation. Respect their existing stack and hand implementation to the installed package's version of the guidance. Repository skills can be installed at project or user scope; those are consumer choices, separate from where the source files live. See repository distribution.

Keep guidance current during library work#

Continue requesting library changes normally. intent maintainer review uses Git changes and content fingerprints to find work that has not been reviewed. Intent identifies candidates; the agent and maintainer decide whether the guidance should change. A new file does not automatically require a new skill. A justified no-change outcome records why accurate guidance stayed unchanged, while missing evidence remains pending.

Before handoff, run sync so the metadata matches the final files, review the pending items in your terminal, then run the combined check:

Interactive review shows each item's current guidance and changed files, asks for an outcome, and records the reason and evidence you supply. maintainer check then reports authoring gaps, generated files, and pending reviews together.

After assessing every pending item, intent maintainer review --unchanged "<reason>" or --updated "<reason>" records a shared conclusion. Use a JSON report when items need different outcomes or evidence.

Coding agents follow the same steps without a terminal. The installed guidance instructs the agent to run intent maintainer review --json, examine affected skills, the planning record, and changed files outside existing source mappings, annotate each completed item with an outcome, reason, and evidence, then record the report with intent maintainer review --record <report.json>. The report's recording block lists the accepted outcomes and required fields; recording a report that annotates nothing fails.

Completed outcomes are saved in .intent/review-state.json. Keep that file with the source, skill, and planning-record changes it describes. Files Intent writes for you, such as the agent instruction block, plugin manifests, package.json, and lockfiles, do not appear as unmapped changes.

See intent review for comparison rules, report fields, ignored paths, recording, and failure recovery.

Configure publishing#

Run the same synchronization command after skill edits:

maintainer sync aligns the tree, adds the tanstack-intent keyword, updates existing package files allowlists, and generates selected repository exports. It preserves authored decisions and an absent npm allowlist. Inspect the packed archive as part of the library’s release checks, including whether planning records should be excluded.

maintainer setup already copies check-skills.yml to the workspace root's .github/workflows/ directory and skips an existing destination file. The copy is a short caller for Intent's reusable workflows, pinned to the commit of the Intent release that copied it and granting each job only the permissions it needs; Dependabot or Renovate can propose pin updates for review. Setup uses the immutable SHA packaged with the installed release; it does not resolve mutable tags. CI runs the copy of @tanstack/intent your lockfile pins, so keep it in devDependencies. The workflow validates skills and recorded source reviews on pull requests. After a release or manual run, it writes a read-only review report when recorded review state or conservative staleness signals require attention. Review-reminder PRs are optional: set the repository Actions variable INTENT_REVIEW_PULL_REQUESTS=true to enable a separate publisher job that never executes Intent or checks out the library. See setup commands.

Publish through the library's normal release process. Skills in the package's published skills/ directory version with that library release. Consumers install the library, configure permitted skill sources with consumer intent install, discover the installed skills with intent list, and load matching guidance with intent load.

Check package and release signals#

intent stale remains the conservative package-level check for version drift, missing source sync SHAs, artifact warnings, and workspace package coverage. It does not compare source diffs or prove that guidance changed. Use intent maintainer review for source-aware, recorded maintenance in repositories that enabled the maintainer workflow.