| name | add-skyux-component |
| description | End-to-end workflow for adding a new component (or directive/service) to an existing @skyux/* library in this Nx monorepo. Use when asked to "add a component", "create a new SKY UX component", scaffold a component with its module, harness, code example, tests, and docs, or wire a new component into a library's public API. Covers file layout, the src/index.ts barrel and sky/Sky prefix rules, SCSS compat overrides, test harness, code-example unit tests, documentation.json, and the test/lint/format/commit gate. |
| argument-hint | <library> <ComponentName> (e.g. indicators MyThing) |
Add a SKY UX Component (end-to-end)
Use this skill to take a new component from scaffold to a fully wired,
tested, and documented addition to a published @skyux/* library. It ties
together the repo's scoped instruction files; read each referenced
instruction file when you reach that step rather than guessing.
Read AGENTS.md first if you are not already familiar
with the monorepo's conventions (Nx tasks, public API discipline, the
sky/Sky export prefix, Karma vs. Jest split, and Conventional Commits).
When to Use
- Adding a new component, directive, or service to an existing library under
libs/components/<library>/.
- Wiring a new public type/component into a library's
src/index.ts barrel.
Do NOT use this skill to create a brand-new library/package — use the
add-skyux-library skill first, then return
here to add the suite's first component. Do not use this skill to modify build
tooling.
Conventions at a Glance
- Library source lives at
libs/components/<library>/src/lib/modules/<module>/.
- Component files follow the pattern:
<name>.component.ts, .html, .scss, .spec.ts- a
NgModule (<name>.module.ts) that imports the standalone component
and exports the public-facing one.
- Components are standalone; do NOT set
standalone: true explicitly in
the decorator. Use ChangeDetectionStrategy.OnPush, input()/output(),
and signals. Follow
angular.instructions.md. The
thin NgModule wrapper above is the SKY UX public-API surface for the
standalone component and does not conflict with that file's "standalone over
NgModules" guidance.
- The public API is the
src/index.ts barrel. Public exports MUST be
prefixed with sky/Sky (e.g. SkyThingComponent, SkyThingModule,
SkyThingHarness). Export a new component or directive by its own name
(e.g. export { SkyThingComponent } from './lib/.../thing.component';).
Some existing libraries export older components/directives under obscured
aliases (e.g. as λ1); that is a legacy pattern — do NOT use it for new
exports.
Procedure
Work top to bottom. Mirror an existing sibling component in the same library
for exact style; do not invent new patterns.
- Confirm placement. Identify the target
<library> (directory name,
not package name) and the <module> folder. Inspect a sibling component
in that library and copy its structure. If the library does not exist yet,
create it first with the
add-skyux-library skill.
- Scaffold the component. Create the
.ts, .html, .scss, and
.module.ts files following Angular best practices in
angular.instructions.md.
- Export from the barrel. Add the module and any public types to
libs/components/<library>/src/index.ts, using the sky/Sky prefix.
Export a new component or directive by its own name (not an obscured
as λN alias).
- Write the component spec. Add
<name>.component.spec.ts. Most
libs/components/* projects enforce 100% coverage and run on
Karma + Jasmine (SKY UX styles are loaded, so computed styles are
assertable).
- Add a test harness. Create the harness, filters, and harness spec
under
libs/components/<library>/testing/src/modules/<module>/ per
component-harnesses.instructions.md.
Export the harness and filters from testing/src/public-api.ts.
- Add visual tests. Create a Storybook story for the component in the
library's e2e app per the
add-component-visual-tests skill.
- Add a code example + tests. Create an example under
libs/components/code-examples/src/lib/modules/<library>/<component>/<example-name>/
and its example.component.spec.ts per the
add-skyux-code-example skill.
- Update documentation. Add the new doc IDs to the library's
documentation.json (development, testing, and codeExamples
sections) so the manifest picks them up.
- Verify. Run the affected tests, lint, and format before committing:
npx nx test <library> --browsers=ChromeHeadless
npx nx test <library>-testing --browsers=ChromeHeadless
npx nx test code-examples --browsers=ChromeHeadless
npx nx build <library>-storybook
npm run lint:affected
nx format --files=<changed-file-paths>
- Commit. Use a Conventional Commit with the matching
components/<library> scope per
commit-message.instructions.md.
Definition of Done
- Component, module, spec, harness (+ spec), visual-test story, and code
example (+ spec) exist and follow a sibling component's structure.
- Public types are exported with the
sky/Sky prefix from src/index.ts
and testing/src/public-api.ts.
documentation.json lists the new development, testing, and code-example
doc IDs.- Affected tests pass at the project's coverage threshold, lint is clean, and
files are formatted.
