fix(cli): improve skills validation

[coryrylan]

• Added a well-known endpoint for installing the elements skill via skills CLI
• Implemented validation for skill names and descriptions to ensure compliance with defined standards.
• Updated the elements skill metadata to include a title and license in the generated markdown.
• Refactored skill markdown formatting to ensure proper structure and compliance with new requirements.
• Introduced tests for validating skill entries and ensuring correct markdown formatting.
• Removed deprecated markdown utility functions and updated imports accordingly.

Summary by CodeRabbit

• New Features

  • Added support for publishing and installing the hosted elements skill through the site build, with a standardized skill artifact format.
  • Improved generated skill output and setup flow for more consistent installation results.

• Bug Fixes

  • Tightened validation for skill names and descriptions to prevent invalid entries.
  • Ensured generated skill files use stable formatting and deterministic output, including cleanup of stale files.

• Documentation

  • Expanded skill setup guidance with clearer install options and updated examples.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds a new .well-known/agent-skills discovery mechanism: a utils.ts module generates and validates skill artifacts (index.json + per-skill Markdown with sha256 digests), replacing markdown.ts. An Eleventy plugin publishes the elements skill during site builds, with supporting docs, config, and test updates.

Changes

Agent Skills Artifacts and Site Publishing

Layer / File(s)	Summary
Discovery schema and validation contracts projects/internals/tools/src/skills/utils.ts, projects/internals/tools/src/skills/registry.ts	Defines discovery index/entry interfaces, name/description validation constraints, and duplicate-name checks; updates elementsSkill.title to "NVIDIA Elements Design System (nve)".
Artifact generation and writing projects/internals/tools/src/skills/utils.ts, .../utils.test.ts	createAgentSkillArtifacts builds sorted, sha256-digested SKILL.md/index.json content; writeAgentSkillArtifacts recreates and writes .well-known/agent-skills; covered by a new test suite.
Module wiring and service update projects/internals/tools/src/skills/index.ts, service.ts, index.test.ts, service.test.ts	Removes markdown.js re-export/module, adds utils.js re-export, updates service.ts import, and revises tests for the new frontmatter shape.
Eleventy plugin for elements skill projects/site/src/_11ty/plugins/agent-skills.js, .../agent-skills.test.ts, .../public-output.js, llms-txt.js, llms-txt.test.ts, eleventy.config.js	Adds a plugin that writes elements-only skill artifacts on eleventy.before; extracts a shared getPublicOutputPath helper used by both plugins; registers the plugin in build mode.
Docs and test config projects/cli/README.md, projects/site/src/docs/skills/index.md, projects/site/package.json	Documents the hosted well-known install path, updates the manual frontmatter example, and simplifies the site's Vitest command to rely on default discovery.

Estimated code review effort: 3 (Moderate) | ~30 minutes

Sequence Diagram(s)

sequenceDiagram
    participant Eleventy as Eleventy Build
    participant Plugin as agentSkillsPlugin
    participant Utils as writeAgentSkillArtifacts
    participant FS as Filesystem

    Eleventy->>Plugin: eleventy.before hook
    Plugin->>Plugin: filter registry to "elements" skill
    Plugin->>Utils: writeAgentSkillArtifacts(publicOutputPath, [elements])
    Utils->>Utils: createAgentSkillArtifacts (validate, sort, sha256 digest)
    Utils->>FS: remove existing .well-known/agent-skills dir
    Utils->>FS: write SKILL.md per skill
    Utils->>FS: write index.json
    FS-->>Utils: write complete
    Utils-->>Plugin: return AgentSkillArtifacts

Loading

Possibly related PRs

• NVIDIA/elements#78: Refactors the same internals/tools/src/skills module, including moving formatSkillMarkdown into utils.ts and updating SkillsService markdown/YAML output expectations.
• NVIDIA/elements#91: Both PRs modify projects/site/package.json's wireit.test Vitest command configuration.

Suggested labels: scope(cli), scope(internals), scope(docs)

Suggested reviewers: johnyanarella

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately reflects the main changes around CLI skills validation and related markdown/schema updates.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch topic-skills-well-known

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

projects/internals/tools/src/skills/index.test.ts

Parsing error: error TS5012: Cannot read file '/tsconfig.json': ENOENT: no such file or directory, open '/tsconfig.json'.

projects/internals/tools/src/skills/service.test.ts

Parsing error: error TS5012: Cannot read file '/tsconfig.json': ENOENT: no such file or directory, open '/tsconfig.json'.

projects/internals/tools/src/skills/utils.test.ts

Parsing error: error TS5012: Cannot read file '/tsconfig.json': ENOENT: no such file or directory, open '/tsconfig.json'.

• 6 others

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with 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.

Inline comments:
In `@projects/cli/README.md`:
- Around line 166-172: The install example in the README points `npx skills add`
at the hosted `elements` URL, but that CLI resolves the
`/.well-known/skills/index.json` discovery path while this site publishes
`/.well-known/agent-skills/index.json`. Update the example in the README to use
the correct `skills`-compatible endpoint or add a `/.well-known/skills` alias so
`npx skills add` can discover the `elements` skill from the hosted registry.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Enterprise

Run ID: f89cf562-79e3-4a36-9472-1da88361ed99

📥 Commits

Reviewing files that changed from the base of the PR and between a9a0571 and 663c098.

📒 Files selected for processing (17)

• projects/cli/README.md
• projects/internals/tools/src/skills/index.test.ts
• projects/internals/tools/src/skills/index.ts
• projects/internals/tools/src/skills/markdown.ts
• projects/internals/tools/src/skills/registry.ts
• projects/internals/tools/src/skills/service.test.ts
• projects/internals/tools/src/skills/service.ts
• projects/internals/tools/src/skills/utils.test.ts
• projects/internals/tools/src/skills/utils.ts
• projects/site/eleventy.config.js
• projects/site/package.json
• projects/site/src/_11ty/plugins/agent-skills.js
• projects/site/src/_11ty/plugins/agent-skills.test.ts
• projects/site/src/_11ty/plugins/llms-txt.js
• projects/site/src/_11ty/plugins/llms-txt.test.ts
• projects/site/src/_11ty/utils/public-output.js
• projects/site/src/docs/skills/index.md

💤 Files with no reviewable changes (1)

• projects/internals/tools/src/skills/markdown.ts

[coryrylan]

🎉 This issue has been resolved in version 2.1.4 🎉

Changelog