headless-primitive
Author, extend, or repair primitives in libs/headless. Use when adding a new headless primitive, changing its accessibility contract, updating slots/state attrs, wiring overlay behavior, or expanding the example styling lab and tests.
Best use case
headless-primitive is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Author, extend, or repair primitives in libs/headless. Use when adding a new headless primitive, changing its accessibility contract, updating slots/state attrs, wiring overlay behavior, or expanding the example styling lab and tests.
Teams using headless-primitive should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/headless-primitive/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How headless-primitive Compares
| Feature / Agent | headless-primitive | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Author, extend, or repair primitives in libs/headless. Use when adding a new headless primitive, changing its accessibility contract, updating slots/state attrs, wiring overlay behavior, or expanding the example styling lab and tests.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# Headless Primitive Maintenance Use this skill when working on `@momentumcms/headless` itself. ## Start Here Read these files before changing behavior: 1. `libs/headless/CLAUDE.md` 2. `docs/headless/overview.md` 3. `docs/headless/styling.md` Read these too when the styling surface or demos change: 1. `apps/example-angular/src/app/pages/headless-styling-lab.page.ts` 2. `libs/e2e-tests/src/specs/headless-styling.spec.ts` 3. `docs/agent-notes.md` ## Non-Negotiable Rules - Keep primitives unstyled. No bundled CSS, no visual classes, no theme tokens inside `libs/headless`. - Expose behavior on the host element. Prefer `template: '<ng-content />'` and avoid wrapper elements unless the platform forces one. - Preserve the global styling contract. Stable `data-slot` selectors and normalized state attributes matter as much as the public TypeScript API. - Favor Angular CDK and Angular Aria primitives over custom behavior when they fit. - If a primitive participates in the styling lab, pair it with a visible readout or outcome that browser tests can assert. ## Implementation Workflow 1. Check the current export surface in `libs/headless/src/index.ts`. 2. Follow the existing family pattern before inventing a new one. 3. Add or update unit specs next to the primitive. 4. If the styling or interaction contract changes, update `/headless-styling-lab` and its Playwright spec. 5. Update `docs/headless/overview.md` and `docs/headless/styling.md` when the public surface changes. 6. Add a note to `docs/agent-notes.md` for any bug, workaround, or testing heuristic worth keeping. ## Verification Run the narrowest useful set first: ```bash pnpm nx test headless pnpm nx lint headless pnpm nx build headless ``` If you touched the styling contract, example route, or browser behavior, also run: ```bash pnpm nx test example-angular pnpm nx lint example-angular pnpm nx build example-angular pnpm playwright test -c apps/example-angular-e2e/playwright.config.ts libs/e2e-tests/src/specs/headless-styling.spec.ts ``` ## Common Pitfalls - Do not let effects both track and mutate shared field signals. Registration helpers that read signal state usually need `untracked(...)`. - Do not make the coverage inventory act like navigation. Inventory should state scope, not bounce users out of the lab. - Do not trust visual polish without a behavior assertion. Filtering, selection, open state, dismissals, and keyboard flow should all have observable outcomes.
Related Skills
headless-ui
Use @momentumcms/headless inside generated Momentum apps. Use when building custom public UI, composing accessible primitives, configuring global styles for hdl-* elements, or adding app-level tests around headless interactions.
ui-audit
Comprehensive UI component audit for Momentum CMS. Use when asked to audit, review, check, or validate a UI component. Checks Storybook stories, interaction tests, variants, kitchen sink integration, admin dashboard usage, accessibility, and responsive design (mobile-first). AUTOMATICALLY FIXES issues found and verifies with visual inspection. Triggers include "audit button", "review the card component", "check accessibility of tabs", or "/ui-audit <component-name>".
test-all
Run the FULL Momentum CMS test suite — every single suite, no skips. Triggers on "test all", "test everything", "run all tests", "run the test all script", "test-all script", "run the full suite", "run every test", "test the whole thing", "make sure everything passes", "run test:all", or ANY variation asking to run all/every/full tests. Also triggers on typos like "test al", "tets all", "tes all". NEVER skip suites unless the user EXPLICITLY names suites to skip.
stroll-test
End-to-end CLI stroll test of npm-published Momentum CMS packages. Scaffolds a fresh project with create-momentum-app, adds all plugins, runs migrations, starts server, and verifies everything works. Triggers include "stroll test", "cli stroll", "test published packages", or "/stroll-test".
skill-improve
Self-improving skill loop. Analyzes eval failures, rewrites the skill, re-evaluates, and repeats until convergence. Run after /skill-eval produces baseline results.
skill-eval
Run structured evaluations comparing skill vs no-skill performance. Measures assertion pass rates, timing, and output quality to systematically improve skills.
prepare-release
Prepare a patch/minor/major version release for all Momentum CMS packages. Bumps versions, generates changelogs, verifies builds/tests, adds new packages to Nx release config, and commits. Triggers include "prepare release", "bump version", "release patch", or "/prepare-release".
momentum-api
Work with Momentum API for data operations in Angular components
migrations
Run migrations, generate schemas, and manage code generation for Momentum CMS. Use when working with database migrations, Drizzle schema generation, type generation, or Angular schematics.
mcp-setup
Set up the Momentum CMS MCP server plugin and generate Claude Code MCP config for AI tool integration. Use when connecting Claude Code (or any MCP client) to a Momentum CMS instance.
SYSTEM ROLE & BEHAVIORAL PROTOCOLS
**ROLE:** Senior Frontend Architect & Avant-Garde UI Designer.
e2e-test
Write and validate Playwright E2E tests for Momentum CMS features. UI tests ALWAYS start from /admin dashboard and navigate via sidebar/dashboard — never go directly to deep URLs. Always starts the server and inspects the actual UI before writing assertions. Triggers include "write e2e tests for...", "add e2e tests", "test the admin UI for...", or "/e2e-test <feature>".