# SKILL.md (/docs/reference/agent-skill/skill)

The complete 4AF Components workflow and repository contract for coding agents.

# 4AF Components

4AF is a public shadcn registry at `https://4af.selfsimilar.dev`. Install and inspect it with
the shadcn CLI. Do not copy component files by hand or guess registry URLs.

## Route the task

- To choose or compare components, or answer feature/API questions, read [references/component-catalog.md](references/component-catalog.md).
- To read one component's complete, agent-friendly reference, fetch
  `https://4af.selfsimilar.dev/docs/<component>.md`: the page's API and notes with separate
  install and usage code blocks. `https://4af.selfsimilar.dev/llms.txt` lists every page.
- To install into another project, use the workflow below.
- For the exact current component list, run
  `npx shadcn@latest search https://4af.selfsimilar.dev/r/registry.json -t ui`. It needs no
  setup and prints each component's description and install URL. Treat the reference catalog as
  a fast guide, not a replacement for it.

## Install into a project

Run in the target project:

```text
npx shadcn@latest info
npx shadcn@latest add https://4af.selfsimilar.dev/r/<component>.json --dry-run
npx shadcn@latest add https://4af.selfsimilar.dev/r/<component>.json
```

The target needs a shadcn `components.json` with `ui` and `lib` aliases; run
`npx shadcn@latest init` first if it has none. `info` shows the project's setup and resolved
paths. `--dry-run` lists every file, package, and theme variable the install adds or changes;
`--diff` shows changes to existing files. The theme, shared utilities, and component
dependencies install with the component. Existing files are skipped unless `--overwrite` is
passed, which discards local edits, so check `--diff` first.

To use short names, register the namespace once per project:

```bash
npx shadcn@latest registry add @4af=https://4af.selfsimilar.dev/r/{name}.json
```

Then `npx shadcn@latest add @4af/<component>`, `search @4af`, and `view @4af/<component>` work.

Afterwards inspect the diff and run the target's own typecheck or build.