Skip to content

chore(ci): update skills #214

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
coryrylan wants to merge 1 commit into
base: main
Choose a base branch
from
Open

chore(ci): update skills #214

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .agents/hooks/pre-tool-use-bash.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ COMMAND=$(hook_command_from_input "$INPUT" || true)
GIT_PREFIX='(^|[;&|][[:space:]]*)git([[:space:]]+(-C[[:space:]]+[^[:space:];&|]+|--no-pager|-c[[:space:]]+[^[:space:];&|]+|--work-tree(=|[[:space:]]+)[^[:space:];&|]+))*[[:space:]]+'

HOOK_OS=$(uname -s 2>/dev/null || true)
if [[ -z "${NVE_AGENT:-}" && "$HOOK_OS" != "Darwin" ]]; then
if [[ "$HOOK_OS" != "Darwin" && ( -z "${NVE_AGENT:-}" || "${NVE_AGENT:-}" == "cursor" ) ]]; then
export NVE_AGENT="isolated"
fi

Expand Down
28 changes: 17 additions & 11 deletions .agents/skills/agent-upkeep/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -138,7 +138,7 @@ There are suppressions left that do not occur anymore. Consider re-running the c

This is success, not failure. It means your fix worked and the stale entry is still on disk. Resolve it by pruning. Do **not** revert your fix, do not re-run `--suppress-rule` to make the message go away, and do not add `--pass-on-unpruned-suppressions`, which only hides the condition and leaves the ratchet slipping backwards.

**Done when**: the rule's suppression count strictly decreases, no stale suppressions remain, the file's public API is byte-identical, `pnpm run lint` passes with no new inline disables, and `pnpm run test` and `pnpm run test:types` pass.
**Done when**: the rule's suppression count strictly decreases, no stale suppressions remain, the file's public API is byte-identical, and every applicable project verification script passes with no new inline disables.
Comment thread
coderabbitai[bot] marked this conversation as resolved.

<!-- vale Vale.Spelling = YES -->

Expand All @@ -159,32 +159,36 @@ Do not invent bugs. If the script finds no quarantined test, it moves to another
### Procedure

1. **Confirm the failure first.** Un-skip the test and run it. It must fail.
2. If it passes immediately, the bug is already fixed. That is still a valid pull request: remove the `.skip` and say so. Stop there.
2. If it passes immediately, the bug is already fixed. That is still a valid pull request: remove the `.skip`, say so, and stop editing. Because this changes only test maintenance, use a `chore` commit and do not trigger an empty package release.
3. If you cannot make it fail, the quarantine is not reproducible. Re-apply the skip, stop, and report what you tried.
4. Otherwise make the smallest change that turns the test green.
5. Do not refactor surrounding code, do not fix adjacent issues, do not tidy imports.
6. Do not weaken the test to make it pass. If you change an assertion to match broken behavior, stop.

The script ranks quarantined **visual** tests last because you cannot update visual baselines. If the script selects one and the fix needs a new baseline, stop, and report it for a human.

**Done when**: the test fails before the fix and passes after, you do not change its assertions, you change no other test, and the full project CI passes.
**Done when**: the test either fails before the production fix and passes after, or passes immediately and needs only removal of `.skip`. In both cases, do not change its assertions or any other test, and require the full project CI to pass.

## Verification

After the final change, run lint first. For Mode A, run it from every selector-provided `packages[].workingDirectory`; for other tasks, run it from the target project directory:
After the final change, inspect the target project's `package.json` and run lint first when the script exists. For Mode A, run it from every selector-provided `packages[].workingDirectory`; for other tasks, run it from the target project directory:

```shell
mise exec -- pnpm run lint
mise exec -- pnpm run --if-present lint
```

Then run tests and type checks from the project containing the hand-fixed source file for Mode A, or from the target project directory for other tasks:
Then run every command below from the project containing the hand-fixed source file for Mode A, or from the target project directory for other tasks. `--if-present` skips only scripts that the project does not define:

```shell
mise exec -- pnpm run test
mise exec -- pnpm run test:types
mise exec -- pnpm run --if-present test
mise exec -- pnpm run --if-present test:types
mise exec -- pnpm run --if-present test:axe
mise exec -- pnpm run --if-present test:ssr
mise exec -- pnpm run --if-present test:lighthouse
mise exec -- pnpm run --if-present test:visual
```

For component changes also run `mise exec -- pnpm run test:axe` and `mise exec -- pnpm run test:ssr`. Do not update visual baselines. If a visual test fails, your change changed behavior: stop.
Record absent scripts as not available rather than as failures. Do not update visual baselines. If a visual test fails, your change changed behavior: stop.
Comment on lines +170 to +191

@coderabbitai coderabbitai Bot Aug 12, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Make the verification steps enforce the full project CI requirement.

Line 170 requires full project CI, but Lines 174-191 only run selected scripts from one project for Mode A. The supplied package.json context says the root CI graph also runs formatting, Vale, validation, notice, and all project CI tasks. An agent can therefore complete this procedure without running the required root checks or verifying other selected packages.

Run the repository root CI command, mise exec -- pnpm run ci, or document an equivalent complete command set. If the root graph is not used, run the listed commands from every selector-provided packages[].workingDirectory for Mode A.

Suggested scope correction 
-Then run every command below from the project containing the hand-fixed source file for Mode A, or from the target project directory for other tasks.
+Then run every command below from every selector-provided `packages[].workingDirectory` for Mode A, or from the target project directory for other tasks.
+
+From the repository root, run the full project CI graph:
+
+mise exec -- pnpm run ci
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
**Done when**: the test either fails before the production fix and passes after, or passes immediately and needs only removal of `.skip`. In both cases, do not change its assertions or any other test, and require the full project CI to pass.
## Verification
After the final change, run lint first. For Mode A, run it from every selector-provided `packages[].workingDirectory`; for other tasks, run it from the target project directory:
After the final change, inspect the target project's `package.json` and run lint first when the script exists. For Mode A, run it from every selector-provided `packages[].workingDirectory`; for other tasks, run it from the target project directory:
```shell
mise exec -- pnpm run lint
mise exec -- pnpm run --if-present lint
```
Then run tests and type checks from the project containing the hand-fixed source file for Mode A, or from the target project directory for other tasks:
Then run every command below from the project containing the hand-fixed source file for Mode A, or from the target project directory for other tasks. `--if-present` skips only scripts that the project does not define:
```shell
mise exec -- pnpm run test
mise exec -- pnpm run test:types
mise exec -- pnpm run --if-present test
mise exec -- pnpm run --if-present test:types
mise exec -- pnpm run --if-present test:axe
mise exec -- pnpm run --if-present test:ssr
mise exec -- pnpm run --if-present test:lighthouse
mise exec -- pnpm run --if-present test:visual
```
For component changes also run `mise exec -- pnpm run test:axe` and `mise exec -- pnpm run test:ssr`. Do not update visual baselines. If a visual test fails, your change changed behavior: stop.
Record absent scripts as not available rather than as failures. Do not update visual baselines. If a visual test fails, your change changed behavior: stop.
**Done when**: the test either fails before the production fix and passes after, or passes immediately and needs only removal of `.skip`. In both cases, do not change its assertions or any other test, and require the full project CI to pass.
## Verification
After the final change, inspect the target project's `package.json` and run lint first when the script exists. For Mode A, run it from every selector-provided `packages[].workingDirectory`; for other tasks, run it from the target project directory:
🧰 Tools
🪛 SkillSpector (2.5.1)

[warning] 59: [AS3] Skill Enumeration: Skill enumerates or reads other installed skills. Access to other skills' SKILL.md files or the skills directory reveals prompt instructions, capabilities, and secrets that should be invisible to peer skills.

Remediation: Remove all code or instructions that list or read other skills' files or directories. Skills should operate independently; cross-skill access is a privilege escalation.

(Agent Snooping (AS3))

[warning] 120: [AS3] Skill Enumeration: Skill enumerates or reads other installed skills. Access to other skills' SKILL.md files or the skills directory reveals prompt instructions, capabilities, and secrets that should be invisible to peer skills.

Remediation: Remove all code or instructions that list or read other skills' files or directories. Skills should operate independently; cross-skill access is a privilege escalation.

(Agent Snooping (AS3))

[warning] 193: [AS3] Skill Enumeration: Skill enumerates or reads other installed skills. Access to other skills' SKILL.md files or the skills directory reveals prompt instructions, capabilities, and secrets that should be invisible to peer skills.

Remediation: Remove all code or instructions that list or read other skills' files or directories. Skills should operate independently; cross-skill access is a privilege escalation.

(Agent Snooping (AS3))

[warning] 265: [AS3] Skill Enumeration: Skill enumerates or reads other installed skills. Access to other skills' SKILL.md files or the skills directory reveals prompt instructions, capabilities, and secrets that should be invisible to peer skills.

Remediation: Remove all code or instructions that list or read other skills' files or directories. Skills should operate independently; cross-skill access is a privilege escalation.

(Agent Snooping (AS3))

[warning] 266: [AS3] Skill Enumeration: Skill enumerates or reads other installed skills. Access to other skills' SKILL.md files or the skills directory reveals prompt instructions, capabilities, and secrets that should be invisible to peer skills.

Remediation: Remove all code or instructions that list or read other skills' files or directories. Skills should operate independently; cross-skill access is a privilege escalation.

(Agent Snooping (AS3))

[warning] 267: [AS3] Skill Enumeration: Skill enumerates or reads other installed skills. Access to other skills' SKILL.md files or the skills directory reveals prompt instructions, capabilities, and secrets that should be invisible to peer skills.

Remediation: Remove all code or instructions that list or read other skills' files or directories. Skills should operate independently; cross-skill access is a privilege escalation.

(Agent Snooping (AS3))

[warning] 268: [AS3] Skill Enumeration: Skill enumerates or reads other installed skills. Access to other skills' SKILL.md files or the skills directory reveals prompt instructions, capabilities, and secrets that should be invisible to peer skills.

Remediation: Remove all code or instructions that list or read other skills' files or directories. Skills should operate independently; cross-skill access is a privilege escalation.

(Agent Snooping (AS3))

[error] 68: [P2] Hidden Instructions: Hidden instructions were detected in comments or invisible text. These could contain malicious directives. Manual review is recommended.

Remediation: Audit all comments and invisible characters. Remove any instructions that direct the agent to perform unauthorized actions. Use plain, reviewable content.

(Prompt Injection (P2))

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.agents/skills/agent-upkeep/SKILL.md around lines 170 - 191, Update the
Verification section in SKILL.md to enforce complete CI: run the repository-root
`mise exec -- pnpm run ci`, or document an equivalent command set covering all
root and project checks. For Mode A, ensure the verification commands run from
every selector-provided `packages[].workingDirectory`, not only one project,
while preserving the instruction to record absent scripts and stop on
visual-test failures.


Then self-review with the [audit-code skill](/.agents/skills/audit-code/SKILL.md) and fix anything it flags.

Expand Down Expand Up @@ -217,7 +221,7 @@ Always use the `upkeep/` prefix. The next run lists unmerged `upkeep/*` branches

Commit messages must follow `commitlint.config.js`:

- type is `fix` for the bug task, `chore` for everything else
- type is `fix` when the bug task changes production behavior; use `chore` for every other task, including an already-fixed bug where the only change removes `.skip`
- include a scope. Use the project directory name under `projects/`, except use `internals` for anything under `projects/internals/` and `docs` for `projects/site`. `commitlint.config.js` holds the authoritative list; if your target does not map to one of its values, use `internals`.
- subject is lower case, no trailing period, 100 characters max
- include a `Signed-off-by:` trailer
Expand All @@ -233,13 +237,15 @@ raising line coverage from 84% to 96%. No behavior change.
Signed-off-by: Elements Upkeep Agent <upkeep@example.com>
```

Open the pull request as a **draft**, labeled `upkeep`, with a body that states:
Open the pull request as a **draft**, labeled `upkeep`, with a concise body that states:

1. the selected task and why, quoting the script's `rationale`
2. the before and after measurement, with numbers
3. an explicit statement that no public API changed
4. anything you deliberately left alone

Keep the body to those facts unless a reviewer needs more context. Before finishing, verify the draft state, label, and body against the pull request's current state. Remove transient setup failures and other statements that later became false.

## Stop Conditions

Report and open nothing when any of these hold:
Expand Down
2 changes: 1 addition & 1 deletion .agents/skills/authoring-documentation/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ You MUST review @projects/site/src/docs/internal/guidelines/documentation.md bef

### How Vale Runs

- **Pre-commit** (via lint-staged):automatically lints staged `*.ts` and `*.md` files
- **Pre-commit** (via lint-staged): automatically lints staged non-test `*.ts` and `*.md` files
- **CI**:runs as part of `pnpm run ci`
- **Manual**:`pnpm run lint:vale` from the repo root (pass specific files as args to narrow scope)

Expand Down
60 changes: 60 additions & 0 deletions .agents/skills/authoring-projects/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
---
name: authoring-projects
description: Author a new standalone NVIDIA Elements workspace project containing a Lit component, including package files, the five test types, Wireit tasks, workspace and CI registration, metadata generation, documentation-site integration, dependency-lint configuration, and generated lock/notice files. Use when creating or scaffolding a new `projects/<name>` package based on the standalone component-library pattern. Do not use for adding a component to an existing project; use the component-creation skill instead.
---

# Authoring Projects

Create a private-by-default project from a current in-repository reference, then wire every consumer before customizing the component.

## Required context

1. Read the repository `AGENTS.md`.
2. Read [references/integration-checklist.md](references/integration-checklist.md).
3. Use the `component-creation` skill for the component class, API, examples, and five test files.
4. Use the `build-system` skill for Wireit changes and the `testing` skill when modifying tests.
5. Read `projects/internals/RELEASE.md` only when the user wants the package published.

## Workflow

1. Confirm the kebab-case project/component name, purpose, package description, and whether the project is private or publish-ready. Default the component name to the project name and keep a new scaffold private.
2. Inspect `git status`, confirm `projects/<name>` does not exist, and preserve unrelated work. Study the closest current standalone component package; default to `projects/plot` only when no closer reference exists.
3. Preview the deterministic scaffold from the repository root:

```shell
node .agents/skills/authoring-projects/scripts/scaffold-project.mjs \
--name <component-name> \
--description "<package and component description>" \
--dry-run
```

4. Review the planned paths, then rerun without `--dry-run`. Pass `--reference <project-name>` when another standalone project is a better structural match.
5. Customize the placeholder component through the `component-creation` workflow. Keep `index.ts` side-effect free, isolate registration in `define.ts`, use `@since 0.0.0`, and make the `@documentation` URL match the generated site route.
6. Refresh generated workspace state:

```shell
mise exec -- pnpm install
mise exec -- pnpm run format:fix
mise exec -- pnpm run notice
```

7. Run the project checks listed in its `DEVELOPMENT.md`, then verify the repository integrations:

```shell
mise exec -- pnpm -C projects/<component-name> run ci
mise exec -- pnpm -C projects/<component-name> run test:lighthouse
mise exec -- pnpm -C projects/internals/metadata run build
mise exec -- pnpm -C projects/site run build
mise exec -- pnpm run lint:knip
```
Comment on lines +41 to +49

@coderabbitai coderabbitai Bot Aug 12, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Run metadata generation before final verification.

The checklist requires metadata build as a minimum check. The workflow and CLI completion message omit it. Users can finish with stale metadata API output.

  • .agents/skills/authoring-projects/SKILL.md#L41-L48: add the metadata generation command to the verification block.
  • .agents/skills/authoring-projects/scripts/scaffold-project.mjs#L65-L68: add metadata generation to the printed next-step list.
📍 Affects 2 files
  • .agents/skills/authoring-projects/SKILL.md#L41-L48 (this comment)
  • .agents/skills/authoring-projects/scripts/scaffold-project.mjs#L65-L68
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.agents/skills/authoring-projects/SKILL.md around lines 41 - 48, The
verification checklist in .agents/skills/authoring-projects/SKILL.md lines 41-48
must include the metadata generation command alongside the existing project
checks. Update the next-step output in
.agents/skills/authoring-projects/scripts/scaffold-project.mjs lines 65-68 to
instruct users to run metadata generation before final verification.


8. Use targeted project checks for isolated changes. Run broader CI when changes affect shared infrastructure, build or release configuration, cross-project interfaces, generated artifacts, or more than one package. Inspect the final diff for generated artifacts, missing build edges, copied visual baselines, and unrelated lockfile churn.

## Guardrails

- Never overwrite an existing project or reuse another component's visual baselines.
- Declare every generated metadata/site input with its matching Wireit build dependency.
- Keep site-only workspace packages in `projects/site` dev dependencies and its workspace-scoped dependency-lint ignore because Eleventy creates their imports dynamically.
- Include CSS linting and use the repository-root stylelint path (`../../stylelint.config.mjs`) from a top-level project.
- Do not create tags, publish packages, edit release wiring, or make a private project public without explicit user authorization.
- Treat commit `c88b885b` as historical evidence, not a byte-for-byte template; the checklist records the defects that the scaffold must avoid.
50 changes: 50 additions & 0 deletions .agents/skills/authoring-projects/references/integration-checklist.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
# Standalone component project checklist

Use this checklist after scaffolding and before final verification. Commit `c88b885b` (`chore(ci): setup scene and plot`) established the reference integration surface, but this checklist corrects its omissions.

## Project package

- Create `projects/<name>/` with package metadata, exports, `sideEffects`, Wireit tasks, TypeScript/Vite/Vitest configs, README, CHANGELOG, DEVELOPMENT, NOTICE, and `.gitignore`.
- Create a side-effect-free package `src/index.ts` exporting `VERSION = '0.0.0'` and its unit/Lighthouse coverage.
- Create the component's class, CSS, example, `define.ts`, `index.ts`, and unit, axe, visual, SSR, and Lighthouse tests.
- Keep the package private until release is explicitly requested.
- List every supported command in `DEVELOPMENT.md`, including visual and SSR tests.
- Make `lint` depend on both `lint:eslint` and `lint:style`; use `../../stylelint.config.mjs` from `projects/<name>`.
- Set component metadata and JSDoc to version `0.0.0`. Route documentation to `/elements/docs/<name>/` when the page is `projects/site/src/docs/<name>/index.md`.

## Repository wiring

| Consumer | Required change |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `pnpm-workspace.yaml` | Add `projects/<name>`. |
| Root `package.json` | Add `<name>:ci`, `<name>:test:lighthouse`, and `<name>:lint:fix` dependencies. |
| `knip.config.js` | Add the project workspace entry. Add the package to the site's scoped `ignoreDependencies` when Eleventy generates site imports. |
| Metadata `api.utils.ts` | Add the project to the API project list. |
| Metadata `package.json` | Add package/custom-elements inputs and a matching `<name>:build` dependency. |
| Site `package.json` | Add dist inputs, a matching build dependency, and the workspace dev dependency. |
| Site docs | Add `projects/site/src/docs/<name>/index.md` with a matching `nve-<name>` tag. |
| Generated files | Run pnpm install and the notice generator to update `pnpm-lock.yaml`, root NOTICE, and project NOTICE files. |

## Historical traps to avoid

- The reference commit added both metadata inputs but only the `scene` build edge. Add one build edge per project input.
- Eleventy generates package imports into HTML. The site needs an actual workspace dependency even though dependency lint cannot observe a source import; use a site-scoped ignore.
- The reference package inherited a dormant `../../../stylelint.config.mjs` path and omitted `lint:style` from `lint`. Use the two-level root path and run CSS linting.
- The starter component used `@since 0.10.0` and a documentation URL that did not match its site route. New scaffolds start at `0.0.0` and keep route/file placement aligned.
- Do not copy `.visual/*.png`; generate baselines from the new component after it renders meaningful output.
- A private scaffold is not release-ready. Do not infer authorization to publish it.

## Publish-ready additions

Only when requested, follow `projects/internals/RELEASE.md` and current repository examples to:

- remove or change `private` intentionally;
- add the root semantic-release task and dependency ordering;
- add the commitlint scope;
- add build artifacts and JUnit reports to `.github/workflows/ci.yml`;
- verify the release configuration and package files;
- tell the user that the initial remote tag still requires explicit external action.

## Verification

Run commands through mise. At minimum, verify install, format, notice generation, project CI, project Lighthouse, metadata build, site build, dependency lint, and `git diff --check`. Browser-backed checks may require permission outside a sandbox. Do not raise bundle limits until measured output justifies a change.
Loading