Programmatic API for adding individual skill mappings

[IzumiSy]

I'd like to be able to add a skill mapping for my own CLI tool's skill programmatically, without going through the interactive intent install flow.

Motivation

I'm building a CLI tool that ships its own SKILL.md. I want to provide an install-skills command so that users can wire up the skill into their agent config by simply running:

npx my-cli install-skills

Ideally, this would be part of the tool's onboarding flow — for example, running automatically after npx my-cli init — so that agent skills are set up as a natural part of getting started, not a separate manual step.

The key requirement is that users don't need to know about @tanstack/intent at all — the skill installation is handled entirely by my CLI.

The current intent install command doesn't fit this use case because it outputs a prompt for an AI agent to act on, rather than writing files directly. What I need is a way to add just my tool's skill mapping — without touching any other existing mappings.

Proposed API

I heard that a more engine-oriented architecture is planned. If so, I'd love to see the engine expose something like:

import { addSkill } from '@tanstack/intent'

await addSkill({
  task: 'working with my-cli commands and configuration',
  load: 'node_modules/my-cli/skills/core/SKILL.md',
  target: 'CLAUDE.md', // optional, defaults to AGENTS.md
  cwd: process.cwd(),
})

Expected behavior:

• If an intent-skills block already exists in the target file, append or update only the entry for this skill
• If no block exists, create one
• Leave all other existing mappings untouched