docs(components): deprecate bulk catalog layout#191
Merged
Conversation
Updates components.d/README.md to promote the flat catalog layout (one entry per skill, one top-level `skills/<catalog_dir>/` directory per skill) as the canonical pattern for new components, and marks the bulk layout (single entry's `path` pointing at a parent directory containing multiple skills) as deprecated. Concretely: - `path` is described as pointing at a single skill directory (one with `SKILL.md` at its root) rather than a parent of multiple skills. - The canonical Example section now shows two flat-layout entries instead of the prior single bulk entry. - A new "Bulk layout (deprecated)" section captures the old pattern inside a GitHub Admonition (`> [!IMPORTANT]`), explains why the flat layout is preferred (discoverability, explicit naming, decoupling the catalog shape from upstream source structure), and reassures existing components that they keep working — the sync workflow handles both layouts identically. No changes to the sync workflow, schema validation, or existing components.d/*.yml files — those are unaffected and will be migrated to the flat layout incrementally. Signed-off-by: JC Fillion-Robin <jcfr@nvidia.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Onboarding type
components.d/<slug>.ymlfile)For new product onboarding — author affirmations
By submitting this PR, I confirm on behalf of my team:
.agents/skills/orskills/path used for new entries (or existing path retained for legacy entries percomponents.d/<slug>.yml)Reviewer checklist (OSS Skills PIC)
components.d/<slug>.ymlentry valid (required fields, uniquecatalog_dir, path exists in source repo, filename slug matches name)SKILL.mdfrontmatter spec-compliant (at least one sampled)All PRs
git commit -s).If you forgot, run
git rebase --signoff origin/main && git push --force-with-leaseto retroactively sign all commits in your branch.Other context (for non-onboarding PRs)
Updates
components.d/README.mdto promote the flat catalog layout (one entry per skill, one top-levelskills/<catalog_dir>/directory per skill) as the canonical pattern for new components, and marks the bulk layout (single entry'spathpointing at a parent directory containing multiple skills) as deprecated.Concretely:
pathis described as pointing at a single skill directory (one withSKILL.mdat its root) rather than a parent of multiple skills.> [!IMPORTANT]), explains why the flat layout is preferred (discoverability, explicit naming, decoupling the catalog shape from upstream source structure), and reassures existing components that they keep working — the sync workflow handles both layouts identically.No changes to the sync workflow, schema validation, or existing components.d/*.yml files — those are unaffected and will be migrated to the flat layout incrementally.