# Agent skill

> A generated SKILL.md shipped inside the package — the rules an agent gets wrong about ngwr, plus the catalog it needs to stop guessing.

Source: https://ngwr.dev/guides/agent-skill

## What it is

Everything else this library ships for agents answers _what exists_. The [MCP server](https://ngwr.dev/guides/mcp) makes the catalog askable, [llms-full.txt](https://ngwr.dev/llms-full.txt) lists every entry point, and each docs page has a markdown twin. None of them carries the dozen rules that separate code which compiles from code that works: the button's selector is `wr-btn` and not `wr-button`, a checkbox's group identity is `checkboxValue` and not `value`, there is no `ControlValueAccessor` anywhere in the library. An agent discovers those by shipping something broken.

The skill is where they live. It follows the [Agent Skills](https://code.claude.com/docs/en/skills) layout — a `SKILL.md` with YAML frontmatter, plus reference files loaded only when needed — and ships inside the npm package, so an agent working in a repo that depends on ngwr can read it with no network and no configuration.

## Where it is

Three files, in the package you already installed.

```bash
node_modules/ngwr/skills/ngwr/
├── SKILL.md                  # ~1 page: frontmatter + the rules that are not guessable
└── references/
    ├── catalog.md            # every entry point, its import line and its selector(s)
    └── setup.md              # bootstrap, styles, providers with no default
```

The same tree is served from the docs site at [ngwr.dev/skills/ngwr/SKILL.md](https://ngwr.dev/skills/ngwr/SKILL.md), for an agent that has not installed the package yet.

## Using it

Point your agent at the copy in node_modules, or commit one.

```bash
# Claude Code, project-scoped — the agent picks it up from .claude/skills.
mkdir -p .claude/skills
cp -R node_modules/ngwr/skills/ngwr .claude/skills/ngwr

# Or read it in place, from any agent that can open a file:
cat node_modules/ngwr/skills/ngwr/SKILL.md
```

Copying it in pins the skill to the version you installed, which is the point — a skill describing a catalog you do not have is worse than none. Re-copy it when you upgrade, or symlink and let the package own it.

## What SKILL.md says

Roughly a page, deliberately. The format's whole idea is progressive disclosure: the short file is always in context, the reference files are opened when they are needed, and a skill that inlines a 202-row table has spent its budget on something the agent could have looked up.

| Name | Description | Type | Default |
| --- | --- | --- | --- |
| `Get the facts, do not guess` | The four sources in the package, ordered — the skill's own catalog, `llms-full.txt`, the `.md` twin of any docs page, and the MCP server. Plus the rule that matters most: read an input name, never invent one. | `section` | `—` |
| `The rules that are not guessable` | Import from the entry point and not a barrel; `wr-btn`, not `wr-button`; check for a MODE before reaching for another component; no `ControlValueAccessor`; `checkboxValue` over `value`; styles are opt-in and global; `.wr-*` classes and `--wr-*` properties are public API; `-contrast` versus `-ink`; no hard-coded strings. | `section` | `—` |
| `Setting a component up` | `ng add ngwr`, `ng g ngwr:use` with `--path` as a NAMED option, and the four providers a component cannot work without — each one a case where it compiles, renders nothing useful, and gives no error naming the cause. | `section` | `—` |
| `Testing` | Reach for the `ngwr/<name>/testing` harness instead of querying the DOM, and load the overlay ones from `documentRootLoader` — the panel is not in the fixture. | `section` | `—` |

## It is generated, so it cannot drift

`scripts/gen-ai-assets.ts` writes the skill and `llms-full.txt` from one pass over the library source, on every build of the library and of this site. The provider table it prints is imported from the MCP server's own — one list, two readers, rather than two lists that agree until someone edits one.

`pnpm check:llms` gates it in CI, and checks the OUTPUT rather than the inputs: a `SKILL.md` missing the frontmatter an agent reads to decide whether to load it, or a catalog table with a header and nothing under it, passes every input floor and is useless to its one reader.

Never hand-edit the generated files — they are rewritten on every build and are not in git. Edit the generator.

## See also

- [MCP server](https://ngwr.dev/guides/mcp) — The askable half of the same stack — search the catalog and read a published API from your agent.
- [Installation](https://ngwr.dev/start/installation) — What `ng add ngwr` does, and the manual path if you would rather do it yourself.
- [Testing](https://ngwr.dev/guides/testing) — The CDK harnesses the skill tells an agent to reach for.