objectstack-ai · xuyushun441-sys · Jun 14, 2026 · Jun 14, 2026 · Jun 14, 2026
diff --git a/.changeset/docs-skills-install-and-generated.md b/.changeset/docs-skills-install-and-generated.md
@@ -0,0 +1,7 @@
+---
+---
+
+docs(skills): document the skill install command and generate the skill catalog
+(README index + guide tables/cards) from each `SKILL.md` frontmatter via a new
+`build-skill-docs.ts` script. Documentation + dev-tooling only — no package
+runtime change, so this is an empty changeset.
diff --git a/content/docs/concepts/skills.mdx b/content/docs/concepts/skills.mdx
@@ -15,6 +15,22 @@ Skills are **not runtime code**. They are machine-readable knowledge definitions
 
 ---
 
+## Installing skills
+
+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.
+
+```bash
+# New project — create-objectstack installs skills automatically
+npm create objectstack@latest my-app
+
+# Existing project — add the whole bundle (re-run to update)
+npx skills add objectstack-ai/framework --all
+```
+
+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).
+
+---
+
 ## Why Skills?
 
 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:
 
 ## Skill Architecture
 
-Each skill follows a **three-layer structure** inspired by [shadcn/ui](https://ui.shadcn.com/):
+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:
 
-| Layer | File | Purpose |
-| :--- | :--- | :--- |
-| **Overview** | `SKILL.md` | High-level guide with decision trees and quick-start examples |
-| **Rules** | `rules/*.md` | Detailed implementation rules with ✅ correct / ❌ incorrect code examples |
-| **Evaluations** | `evals/*.md` | Test cases to validate AI assistant understanding |
+| Layer | File | Required | Purpose |
+| :--- | :--- | :--- | :--- |
+| **Overview** | `SKILL.md` | Yes | High-level guide with decision trees and quick-start examples |
+| **Rules** | `rules/*.md` | Optional | Detailed implementation rules with ✅ correct / ❌ incorrect code examples |
+| **Evaluations** | `evals/*.md` | Optional | Test cases to validate AI assistant understanding |
 
 ### SKILL.md — The Entry Point
 
 Each `SKILL.md` starts with structured metadata:
 
 ```yaml
 ---
-skill: objectstack-schema
-version: 3.0
-domain: data
-description: Design ObjectStack data schemas
-tags: [object, field, validation, index, relationship]
+name: objectstack-data
+description: >
+  Design ObjectStack data schemas — objects, fields, relationships,
+  validations, indexes, lifecycle hooks, permissions, and seed datasets.
+  Use when … Do not use for …
+license: Apache-2.0
+metadata:
+  domain: data
+  tags: object, field, validation, index, relationship, hook, seed
 ---
 ```
 
@@ -95,62 +115,15 @@ This format ensures AI assistants generate protocol-compliant code.
 
 ---
 
-## The 10 Skills
-
-ObjectStack provides **10 domain-specific skills** covering every aspect of the protocol:
-
-<Cards>
-  <Card
-    icon={<Database />}
-    title="Schema Design"
-    description="Objects, Fields, Relationships, Validations, and Indexes."
-  />
-  <Card
-    icon={<Target />}
-    title="Query Design"
-    description="Filters, sorting, pagination, aggregation, joins, and full-text search."
-  />
-  <Card
-    icon={<Globe />}
-    title="API Design"
-    description="REST endpoints, service discovery, authentication, and inter-service communication."
-  />
-  <Card
-    icon={<Layout />}
-    title="UI Design"
-    description="Views, Apps, Dashboards, Reports, and Actions."
-  />
-  <Card
-    icon={<Workflow />}
-    title="Automation Design"
-    description="Flows, Workflows, Triggers, and Approval processes."
-  />
-  <Card
-    icon={<Bot />}
-    title="AI Agent Design"
-    description="Agents, Tools, Skills, and RAG pipelines."
-  />
-  <Card
-    icon={<Puzzle />}
-    title="Plugin Development"
-    description="Plugin lifecycle, Service registry, Hooks, and Events."
-  />
-  <Card
-    icon={<Zap />}
-    title="Quickstart"
-    description="Project scaffolding, defineStack(), drivers, and adapters."
-  />
-  <Card
-    icon={<Languages />}
-    title="I18n Design"
-    description="Translation bundles, locale configuration, and coverage detection."
-  />
-  <Card
-    icon={<Wrench />}
-    title="Hooks System"
-    description="Data lifecycle hooks, plugin hooks, and kernel events."
-  />
-</Cards>
+## The skill catalog
+
+ObjectStack provides **nine domain-specific skills**, one per protocol domain — Platform, Data, Query, UI, Automation, AI, API, i18n, and Formula.
+
+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.
+
+<Callout type="info">
+Lifecycle hooks, plugin development, and project bootstrap are **not** separate skills — they live in **Data** (record hooks) and **Platform** (plugins, kernel events, `defineStack`).
+</Callout>
 
 ---
 
@@ -159,43 +132,36 @@ ObjectStack provides **10 domain-specific skills** covering every aspect of the
 Each skill has **clear boundaries** — it knows what it's responsible for and explicitly delegates to other skills when needed:
 
 ```
-                    ┌──────────────┐
-                    │  Quickstart  │
-                    │  (Bootstrap) │
-                    └──────┬───────┘
-                           │
-              ┌────────────┼────────────┐
-              ▼            ▼            ▼
-       ┌────────────┐ ┌────────┐ ┌──────────┐
-       │   Schema   │ │ Plugin │ │   I18n   │
-       │   Design   │ │  Dev   │ │  Design  │
-       └──────┬─────┘ └────────┘ └──────────┘
-              │
-    ┌─────────┼─────────┐
-    ▼         ▼         ▼
-┌────────┐ ┌──────┐ ┌──────────┐
-│ Query  │ │  UI  │ │Automation│
-│ Design │ │Design│ │  Design  │
-└────────┘ └──────┘ └────┬─────┘
-                         │
-                    ┌────┴─────┐
-                    ▼          ▼
-              ┌──────────┐ ┌──────┐
-              │ AI Agent │ │ API  │
-              │  Design  │ │Design│
-              └──────────┘ └──────┘
+                     ┌──────────┐
+                     │ Platform │   bootstrap · plugins · kernel · deploy
+                     └────┬─────┘
+                          │
+                     ┌────▼─────┐
+                     │   Data   │   objects · fields · hooks · RLS · seed
+                     └────┬─────┘
+            ┌─────────────┼─────────────┐
+            ▼             ▼             ▼
+        ┌───────┐     ┌──────┐    ┌────────────┐
+        │ Query │     │  UI  │    │ Automation │
+        └───────┘     └──────┘    └─────┬──────┘
+                          │             │
+                     ┌────▼────┐   ┌────▼────┐
+                     │   API   │   │   AI    │
+                     └─────────┘   └─────────┘
+
+  Formula and i18n are cross-cutting — load them alongside any host skill.
 ```
 
-| Skill | Delegates To | For |
+| Skill | Delegates to | For |
 | :--- | :--- | :--- |
-| Schema | Query | Querying and filtering records |
-| Schema | UI | Building views and forms |
-| Query | Schema | Understanding field types |
-| UI | Schema | Field definitions for columns |
-| Automation | Schema | Record-triggered flows |
-| AI Agent | Automation | Flow-based agent tools |
-| Plugin | Schema | Registering objects |
-| Quickstart | All | Setting up the full stack |
+| Data | Query | Querying and filtering records |
+| Data | UI | Building views and forms |
+| Query | Data | Understanding field types |
+| UI | Data | Field definitions for columns |
+| Automation | Data | Record-triggered flows |
+| AI | Automation | Flow-based agent tools |
+| Platform | Data | Registering objects from a plugin |
+| Data / Automation / UI | Formula | Any CEL predicate or expression |
 
 ---
 
@@ -206,7 +172,7 @@ Each skill has **clear boundaries** — it knows what it's responsible for and e
 Skills are automatically loaded from the `skills/` directory when using GitHub Copilot in VS Code. Reference a skill directly:
 
 ```
-@workspace Use the objectstack-schema skill to design a customer object
+@workspace Use the objectstack-data skill to design a customer object
 with name, email, industry, and annual_revenue fields.
 ```
 
@@ -224,7 +190,7 @@ that filters opportunities by stage and aggregates revenue by quarter.
 Add the skill files to your Cursor rules or reference them in prompts:
 
 ```
-@skills/objectstack-plugin/SKILL.md Create a plugin that adds
+@skills/objectstack-platform/SKILL.md Create a plugin that adds
 an audit logging service to the kernel.
 ```
 
@@ -240,7 +206,7 @@ Skills are **structured metadata** — not executable code. They define *what* t
 
 ### 2. Composable
 
-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.
+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.
 
 ### 3. Protocol-Aligned
 

diff --git a/content/docs/getting-started/quick-start.mdx b/content/docs/getting-started/quick-start.mdx
@@ -22,6 +22,20 @@ npx @objectstack/cli init my-app
 cd my-app
 ```
 
+### Add AI skills to your editor
+
+Install the ObjectStack skill bundle so your AI assistant (Claude Code, Copilot, Cursor, …) knows the protocol's schemas and conventions:
+
+```bash
+npx skills add objectstack-ai/framework --all
+```
+
+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.
+
+<Callout type="info">
+Scaffolding with `npm create objectstack@latest` runs this step automatically.
+</Callout>
+
 ### Define your first object
 
 The scaffolded project includes a sample object. Open `src/objects/my_app.ts`: