docs(skills): document install command + generate skill catalog from frontmatter#1842
Merged
Merged
Conversation
…frontmatter
The AI Skills docs (guides/skills.mdx, concepts/skills.mdx) had drifted badly:
they described skills that don't exist (objectstack-quickstart/schema/plugin/
hooks), claimed "10 skills" (there are 9), and the install command was
undocumented anywhere — it only ran inside create-objectstack.
- Add `packages/spec/scripts/build-skill-docs.ts`: single source of truth is
each `skills/objectstack-*/SKILL.md` frontmatter. Generates the README Index
table and the guide's Quick Reference table + per-skill cards between
BEGIN/END markers. Scripts: `gen:skill-docs` (write), `check:skill-docs`
(CI drift check). Per-file comment style — `{/* */}` for MDX, `<!-- -->`
for the README .md (MDX rejects HTML comments).
- Document installation in concepts/skills.mdx and getting-started/quick-start
.mdx: `npx skills add objectstack-ai/framework --all` (whole bundle, single
versioned unit) and the create-objectstack auto-install path.
- Fix stale references throughout concepts/skills.mdx (skill boundaries
diagram, delegation table, usage examples, SKILL.md frontmatter sample) to
the real 9-skill set.
Verified: docs portal renders all three pages (200) with correct content.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
github-actions
Bot
added
documentation
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This was referenced Jun 14, 2026
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
2 participants
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.
Why
A user couldn't find how to install the AI skills — because the install command (
npx skills add objectstack-ai/framework --all) was undocumented anywhere in the site; it only ran insidecreate-objectstack. Investigating, the skills docs had also drifted badly:guides/skills.mdxandconcepts/skills.mdxdescribed skills that don't exist (objectstack-quickstart/objectstack-schema/objectstack-plugin/objectstack-hooks) and omitted the real ones (objectstack-platform/objectstack-data/objectstack-formula).Root cause: the skill catalog was hand-maintained in multiple places with no single source.
What
1. Document installation (concepts + quick-start)
concepts/skills.mdx: new "Installing skills" section.getting-started/quick-start.mdx: new "Add AI skills to your editor" step.npx skills add objectstack-ai/framework --all(whole bundle, idempotent, single versioned unit) + thecreate-objectstackauto-install path.2. Single source of truth —
packages/spec/scripts/build-skill-docs.tsskills/README.mdIndex table and the guide's Quick Reference table + per-skill cards from eachSKILL.mdfrontmatter (name / description / domain / tags), betweenBEGIN/END GENERATEDmarkers.gen:skill-docs(write),check:skill-docs(--check, for CI drift detection).{/* */}for MDX,<!-- -->for the README.md(MDX rejects HTML comments — caught during browser verification).3. Fix stale references in
concepts/skills.mdx— skill-boundaries diagram, delegation table, usage examples, and theSKILL.mdfrontmatter sample — to the real 9-skill set.Net: −437 / +216 lines (removed fabricated content).
Verification
Ran the docs portal locally (
pnpm dev); all three pages return 200 and render correctly (Quick Reference table, per-skill cards, corrected ASCII boundary diagram, install steps). Screenshots checked for the guide, concepts, and quick-start pages.Follow-up (not in this PR)
Wire
check:skill-docsinto CI so the docs can't drift fromSKILL.mdagain.🤖 Generated with Claude Code