Skip to content

Commit ddeb934

Browse files
xuyushun441-sysos-zhuangclaude
authored
docs(skills): document install command + generate skill catalog from frontmatter (#1842)
* docs(skills): document install command + generate skill catalog from 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> * chore: add empty changeset for docs-only skills update Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com> Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1 parent c89e8b3 commit ddeb934

7 files changed

Lines changed: 481 additions & 437 deletions

File tree

‎.changeset/docs-skills-install-and-generated.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
---
3+
4+
docs(skills): document the skill install command and generate the skill catalog
5+
(README index + guide tables/cards) from each `SKILL.md` frontmatter via a new
6+
`build-skill-docs.ts` script. Documentation + dev-tooling only — no package
7+
runtime change, so this is an empty changeset.

‎content/docs/concepts/skills.mdx‎

Lines changed: 70 additions & 104 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,22 @@ Skills are **not runtime code**. They are machine-readable knowledge definitions
1515

1616
---
1717

18+
## Installing skills
19+
20+
Skills are distributed through the [skills.sh](https://skills.sh) registry from the [`objectstack-ai/framework`](https://github.com/objectstack-ai/framework) repository's `skills/` directory.
21+
22+
```bash
23+
# New project — create-objectstack installs skills automatically
24+
npm create objectstack@latest my-app
25+
26+
# Existing project — add the whole bundle (re-run to update)
27+
npx skills add objectstack-ai/framework --all
28+
```
29+
30+
The bundle is versioned and updated as **one unit** — `--all` is idempotent, so you never track skills individually. For the full per-skill catalog and install options, see the [AI Skills Reference](/docs/guides/skills#installing-skills).
31+
32+
---
33+
1834
## Why Skills?
1935

2036
Traditional AI code assistants generate generic code. They don't understand:
@@ -44,25 +60,29 @@ Traditional AI code assistants generate generic code. They don't understand:
4460

4561
## Skill Architecture
4662

47-
Each skill follows a **three-layer structure** inspired by [shadcn/ui](https://ui.shadcn.com/):
63+
Each skill can use up to a **three-layer structure** inspired by [shadcn/ui](https://ui.shadcn.com/). Only `SKILL.md` is required; richer skills add the other two:
4864

49-
| Layer | File | Purpose |
50-
| :--- | :--- | :--- |
51-
| **Overview** | `SKILL.md` | High-level guide with decision trees and quick-start examples |
52-
| **Rules** | `rules/*.md` | Detailed implementation rules with ✅ correct / ❌ incorrect code examples |
53-
| **Evaluations** | `evals/*.md` | Test cases to validate AI assistant understanding |
65+
| Layer | File | Required | Purpose |
66+
| :--- | :--- | :--- | :--- |
67+
| **Overview** | `SKILL.md` | Yes | High-level guide with decision trees and quick-start examples |
68+
| **Rules** | `rules/*.md` | Optional | Detailed implementation rules with ✅ correct / ❌ incorrect code examples |
69+
| **Evaluations** | `evals/*.md` | Optional | Test cases to validate AI assistant understanding |
5470

5571
### SKILL.md — The Entry Point
5672

5773
Each `SKILL.md` starts with structured metadata:
5874

5975
```yaml
6076
---
61-
skill: objectstack-schema
62-
version: 3.0
63-
domain: data
64-
description: Design ObjectStack data schemas
65-
tags: [object, field, validation, index, relationship]
77+
name: objectstack-data
78+
description: >
79+
Design ObjectStack data schemas — objects, fields, relationships,
80+
validations, indexes, lifecycle hooks, permissions, and seed datasets.
81+
Use when … Do not use for …
82+
license: Apache-2.0
83+
metadata:
84+
domain: data
85+
tags: object, field, validation, index, relationship, hook, seed
6686
---
6787
```
6888

@@ -95,62 +115,15 @@ This format ensures AI assistants generate protocol-compliant code.
95115

96116
---
97117

98-
## The 10 Skills
99-
100-
ObjectStack provides **10 domain-specific skills** covering every aspect of the protocol:
101-
102-
<Cards>
103-
<Card
104-
icon={<Database />}
105-
title="Schema Design"
106-
description="Objects, Fields, Relationships, Validations, and Indexes."
107-
/>
108-
<Card
109-
icon={<Target />}
110-
title="Query Design"
111-
description="Filters, sorting, pagination, aggregation, joins, and full-text search."
112-
/>
113-
<Card
114-
icon={<Globe />}
115-
title="API Design"
116-
description="REST endpoints, service discovery, authentication, and inter-service communication."
117-
/>
118-
<Card
119-
icon={<Layout />}
120-
title="UI Design"
121-
description="Views, Apps, Dashboards, Reports, and Actions."
122-
/>
123-
<Card
124-
icon={<Workflow />}
125-
title="Automation Design"
126-
description="Flows, Workflows, Triggers, and Approval processes."
127-
/>
128-
<Card
129-
icon={<Bot />}
130-
title="AI Agent Design"
131-
description="Agents, Tools, Skills, and RAG pipelines."
132-
/>
133-
<Card
134-
icon={<Puzzle />}
135-
title="Plugin Development"
136-
description="Plugin lifecycle, Service registry, Hooks, and Events."
137-
/>
138-
<Card
139-
icon={<Zap />}
140-
title="Quickstart"
141-
description="Project scaffolding, defineStack(), drivers, and adapters."
142-
/>
143-
<Card
144-
icon={<Languages />}
145-
title="I18n Design"
146-
description="Translation bundles, locale configuration, and coverage detection."
147-
/>
148-
<Card
149-
icon={<Wrench />}
150-
title="Hooks System"
151-
description="Data lifecycle hooks, plugin hooks, and kernel events."
152-
/>
153-
</Cards>
118+
## The skill catalog
119+
120+
ObjectStack provides **nine domain-specific skills**, one per protocol domain — Platform, Data, Query, UI, Automation, AI, API, i18n, and Formula.
121+
122+
The authoritative list (names, domains, and "use when / do not use" boundaries) is generated from each skill's `SKILL.md` frontmatter. See the **[AI Skills Reference](/docs/guides/skills)** for the full catalog with per-skill detail.
123+
124+
<Callout type="info">
125+
Lifecycle hooks, plugin development, and project bootstrap are **not** separate skills — they live in **Data** (record hooks) and **Platform** (plugins, kernel events, `defineStack`).
126+
</Callout>
154127

155128
---
156129

@@ -159,43 +132,36 @@ ObjectStack provides **10 domain-specific skills** covering every aspect of the
159132
Each skill has **clear boundaries** — it knows what it's responsible for and explicitly delegates to other skills when needed:
160133

161134
```
162-
┌──────────────┐
163-
│ Quickstart │
164-
│ (Bootstrap) │
165-
└──────┬───────┘
166-
│
167-
┌────────────┼────────────┐
168-
▼ ▼ ▼
169-
┌────────────┐ ┌────────┐ ┌──────────┐
170-
│ Schema │ │ Plugin │ │ I18n │
171-
│ Design │ │ Dev │ │ Design │
172-
└──────┬─────┘ └────────┘ └──────────┘
173-
│
174-
┌─────────┼─────────┐
175-
▼ ▼ ▼
176-
┌────────┐ ┌──────┐ ┌──────────┐
177-
│ Query │ │ UI │ │Automation│
178-
│ Design │ │Design│ │ Design │
179-
└────────┘ └──────┘ └────┬─────┘
180-
│
181-
┌────┴─────┐
182-
▼ ▼
183-
┌──────────┐ ┌──────┐
184-
│ AI Agent │ │ API │
185-
│ Design │ │Design│
186-
└──────────┘ └──────┘
135+
┌──────────┐
136+
│ Platform │ bootstrap · plugins · kernel · deploy
137+
└────┬─────┘
138+
│
139+
┌────▼─────┐
140+
│ Data │ objects · fields · hooks · RLS · seed
141+
└────┬─────┘
142+
┌─────────────┼─────────────┐
143+
▼ ▼ ▼
144+
┌───────┐ ┌──────┐ ┌────────────┐
145+
│ Query │ │ UI │ │ Automation │
146+
└───────┘ └──────┘ └─────┬──────┘
147+
│ │
148+
┌────▼────┐ ┌────▼────┐
149+
│ API │ │ AI │
150+
└─────────┘ └─────────┘
151+
152+
Formula and i18n are cross-cutting — load them alongside any host skill.
187153
```
188154

189-
| Skill | Delegates To | For |
155+
| Skill | Delegates to | For |
190156
| :--- | :--- | :--- |
191-
| Schema | Query | Querying and filtering records |
192-
| Schema | UI | Building views and forms |
193-
| Query | Schema | Understanding field types |
194-
| UI | Schema | Field definitions for columns |
195-
| Automation | Schema | Record-triggered flows |
196-
| AI Agent | Automation | Flow-based agent tools |
197-
| Plugin | Schema | Registering objects |
198-
| Quickstart | All | Setting up the full stack |
157+
| Data | Query | Querying and filtering records |
158+
| Data | UI | Building views and forms |
159+
| Query | Data | Understanding field types |
160+
| UI | Data | Field definitions for columns |
161+
| Automation | Data | Record-triggered flows |
162+
| AI | Automation | Flow-based agent tools |
163+
| Platform | Data | Registering objects from a plugin |
164+
| Data / Automation / UI | Formula | Any CEL predicate or expression |
199165

200166
---
201167

@@ -206,7 +172,7 @@ Each skill has **clear boundaries** — it knows what it's responsible for and e
206172
Skills are automatically loaded from the `skills/` directory when using GitHub Copilot in VS Code. Reference a skill directly:
207173

208174
```
209-
@workspace Use the objectstack-schema skill to design a customer object
175+
@workspace Use the objectstack-data skill to design a customer object
210176
with name, email, industry, and annual_revenue fields.
211177
```
212178

@@ -224,7 +190,7 @@ that filters opportunities by stage and aggregates revenue by quarter.
224190
Add the skill files to your Cursor rules or reference them in prompts:
225191

226192
```
227-
@skills/objectstack-plugin/SKILL.md Create a plugin that adds
193+
@skills/objectstack-platform/SKILL.md Create a plugin that adds
228194
an audit logging service to the kernel.
229195
```
230196

@@ -240,7 +206,7 @@ Skills are **structured metadata** — not executable code. They define *what* t
240206

241207
### 2. Composable
242208

243-
Skills are independently installable and referenceable. A developer working only on data modeling can load `objectstack-schema` without loading `objectstack-ui`. This follows the same composability pattern as ObjectStack plugins.
209+
Skills are independently installable and referenceable. A developer working only on data modeling can load `objectstack-data` without loading `objectstack-ui`. This follows the same composability pattern as ObjectStack plugins.
244210

245211
### 3. Protocol-Aligned
246212

‎content/docs/getting-started/quick-start.mdx‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,20 @@ npx @objectstack/cli init my-app
2222
cd my-app
2323
```
2424

25+
### Add AI skills to your editor
26+
27+
Install the ObjectStack skill bundle so your AI assistant (Claude Code, Copilot, Cursor, …) knows the protocol's schemas and conventions:
28+
29+
```bash
30+
npx skills add objectstack-ai/framework --all
31+
```
32+
33+
Re-run the same command any time to update — the bundle is versioned as one unit. See the [AI Skills Reference](/docs/guides/skills) for the full catalog.
34+
35+
<Callout type="info">
36+
Scaffolding with `npm create objectstack@latest` runs this step automatically.
37+
</Callout>
38+
2539
### Define your first object
2640

2741
The scaffolded project includes a sample object. Open `src/objects/my_app.ts`:

0 commit comments

Comments
 (0)