AI agents

Install

Install the package as described in Installation. The skill, the component catalog and the checks all ship inside @gunkin/uiify, so there is nothing else to download.

Connect the agent

Link the skill into your project so it follows the installed package. Create both links: Claude Code reads .claude/skills, and the commands and rules use .agents/skills.

mkdir -p .agents/skills .claude/skills
ln -s ../../node_modules/@gunkin/uiify/skills/uiify .agents/skills/uiify
ln -s ../../node_modules/@gunkin/uiify/skills/uiify .claude/skills/uiify

In a monorepo, point the links at the resolved package path.

If links are not possible (Windows without symlink rights) or your team wants the skill in git, copy the directory to both places instead:

mkdir -p .agents/skills/uiify .claude/skills/uiify
cp -R node_modules/@gunkin/uiify/skills/uiify/. .agents/skills/uiify/
cp -R node_modules/@gunkin/uiify/skills/uiify/. .claude/skills/uiify/

Then write the component catalog into your AGENTS.md:

node .agents/skills/uiify/scripts/sync-agents.mjs --write

The command adds a marked section with a few fixed rules and a compact list of components and props, so the agent does not guess names. It also updates CLAUDE.md when that file exists. Everything between the uiify:start and uiify:end comments is generated; write your own notes outside it.

Agents that read AGENTS.md, such as Codex, get the catalog from that file. UIify has not been tested with them, only with Claude Code.

If you use TanStack Intent, npx @tanstack/intent@latest list finds the skill because the package carries the tanstack-intent keyword. Intent only points at the skill. The catalog section is still written by sync-agents.mjs.

Run the skill with a page brief:

/uiify Build a responsive product page at /products

Screens and the check

A screen is a component that only arranges UIify parts. The catalog tells the agent that a screen imports from @gunkin/uiify, blocks and your own components, and never sets className or style. Check that it did:

node .agents/skills/uiify/scripts/check-screens.mjs src/screens

It prints screens: ok or one line per finding, and exits with 1 when there is a finding. Pass --allow <module> for an extra module your screens may import. Run tsc as well; the check does not replace the type check.

To see the same mistakes while you type, add the optional oxlint or ESLint fragments from node_modules/@gunkin/uiify/skills/uiify/references/editor-lint.md. The script stays the source of truth.

Upgrading

Update the package, then refresh the catalog:

npm install @gunkin/uiify@latest
node .agents/skills/uiify/scripts/sync-agents.mjs --write

Or just run /uiify: it checks the section first and refreshes it when needed. A linked skill follows the package by itself. --write refreshes every copied skill directory too.

To fail a pipeline when the section is stale, run the check in CI:

node .agents/skills/uiify/scripts/sync-agents.mjs --check

It prints one line per file, such as AGENTS.md: outdated 0.0.30 → 0.0.31, and exits with 1 when a section is missing, outdated or edited.

If you changed the generated text, the command reports edited and keeps your version. Review it, then add --force to replace it. Only the text between the markers is replaced; the rest of the file stays as it is.

After an upgrade, run sync-agents.mjs --write, then check-screens.mjs on your screens folder and tsc; fix what they report. A component or prop that a release removed is no longer exported, so tsc names every screen that still uses it.

What the catalog contains

Each component with its parts and the props that take a fixed set of values, the shared layout props, and how responsive values are written. It leaves out styling details and examples. The skill's references/ folder holds the longer recipes, which the agent reads only for the components a page needs.

Troubleshooting

If the agent reads the package type files to find a component or prop, the catalog section is probably missing from the file it reads. Run sync-agents.mjs --check, and pass the file name if your instructions live elsewhere:

node .agents/skills/uiify/scripts/sync-agents.mjs --write docs/AGENT-RULES.md

If the command says that @gunkin/uiify is not installed, run it from the project root where the dependency is installed.