diff --git a/.changeset/docs-skills-install-and-generated.md b/.changeset/docs-skills-install-and-generated.md new file mode 100644 index 0000000000..7682fd64ee --- /dev/null +++ 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 index be5f7e6843..7e92c0029f 100644 --- 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,13 +60,13 @@ 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 @@ -58,11 +74,15 @@ 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: - - - } - title="Schema Design" - description="Objects, Fields, Relationships, Validations, and Indexes." - /> - } - title="Query Design" - description="Filters, sorting, pagination, aggregation, joins, and full-text search." - /> - } - title="API Design" - description="REST endpoints, service discovery, authentication, and inter-service communication." - /> - } - title="UI Design" - description="Views, Apps, Dashboards, Reports, and Actions." - /> - } - title="Automation Design" - description="Flows, Workflows, Triggers, and Approval processes." - /> - } - title="AI Agent Design" - description="Agents, Tools, Skills, and RAG pipelines." - /> - } - title="Plugin Development" - description="Plugin lifecycle, Service registry, Hooks, and Events." - /> - } - title="Quickstart" - description="Project scaffolding, defineStack(), drivers, and adapters." - /> - } - title="I18n Design" - description="Translation bundles, locale configuration, and coverage detection." - /> - } - title="Hooks System" - description="Data lifecycle hooks, plugin hooks, and kernel events." - /> - +## 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. + + +Lifecycle hooks, plugin development, and project bootstrap are **not** separate skills — they live in **Data** (record hooks) and **Platform** (plugins, kernel events, `defineStack`). + --- @@ -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 index 71312b2a4c..4b20f4d029 100644 --- 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. + + +Scaffolding with `npm create objectstack@latest` runs this step automatically. + + ### Define your first object The scaffolded project includes a sample object. Open `src/objects/my_app.ts`: diff --git a/content/docs/guides/skills.mdx b/content/docs/guides/skills.mdx index aa727cb76e..3a485fc80a 100644 --- a/content/docs/guides/skills.mdx +++ b/content/docs/guides/skills.mdx @@ -1,445 +1,236 @@ --- title: AI Skills Reference -description: Complete reference for all 10 ObjectStack AI skills — structured knowledge modules for intelligent code generation +description: Reference for every ObjectStack AI skill — domain-scoped knowledge modules that teach AI assistants the protocol's schemas and constraints --- -import { Bot, Brain, Cpu, Database, Globe, Layout, Shield, Workflow, Wrench, Languages, Zap, Puzzle, BookOpen, Target, ArrowRight, FileCode, CheckCircle, AlertTriangle, FolderOpen } from 'lucide-react'; - # AI Skills Reference -ObjectStack ships with **10 domain-specific skills** that teach AI assistants the protocol's schemas, patterns, and constraints. This guide covers every skill in detail. +ObjectStack ships a set of **domain-specific skills** that teach AI assistants (Claude Code, GitHub Copilot, Cursor, …) the protocol's schemas, patterns, and constraints. This guide is the complete catalog. -**New to skills?** Read [AI Skills System](/docs/concepts/skills) first for the conceptual overview, then return here for the complete reference. +**New to skills?** Read [AI Skills System](/docs/concepts/skills) first for the conceptual overview, then return here for the per-skill reference. --- -## Quick Reference - -| # | Skill | Domain | Path | Use When... | -| :--- | :--- | :--- | :--- | :--- | -| 1 | [Quickstart](#quickstart) | Bootstrap | `skills/objectstack-quickstart/` | Creating projects, configuring `defineStack()` | -| 2 | [Schema Design](#schema-design) | Data | `skills/objectstack-schema/` | Designing objects, fields, relationships | -| 3 | [Query Design](#query-design) | Data | `skills/objectstack-query/` | Building filters, aggregations, search | -| 4 | [API Design](#api-design) | API | `skills/objectstack-api/` | Defining endpoints, service contracts | -| 5 | [UI Design](#ui-design) | Interface | `skills/objectstack-ui/` | Creating views, dashboards, apps | -| 6 | [Automation Design](#automation-design) | Logic | `skills/objectstack-automation/` | Building flows, workflows, triggers | -| 7 | [AI Agent Design](#ai-agent-design) | Intelligence | `skills/objectstack-ai/` | Configuring agents, tools, RAG | -| 8 | [Plugin Development](#plugin-development) | Kernel | `skills/objectstack-plugin/` | Plugin lifecycle, service registry | -| 9 | [I18n Design](#i18n-design) | System | `skills/objectstack-i18n/` | Translation, locale configuration | -| 10 | [Hooks System](#hooks-system) | Core | `skills/objectstack-hooks/` | Data lifecycle events, kernel events | - ---- - -## Quickstart - - -**Path:** `skills/objectstack-quickstart/` -**Tags:** `project`, `scaffold`, `init`, `defineStack`, `driver`, `adapter`, `bootstrap`, `config` - +## Installing skills -### What It Covers +Skills install into a project from the [skills.sh](https://skills.sh) registry, reading the `skills/` directory of the [`objectstack-ai/framework`](https://github.com/objectstack-ai/framework) repository. -The Quickstart skill guides AI assistants through **project bootstrap and configuration**: +**New projects — installed automatically.** `create-objectstack` runs the install step for you during scaffolding: -- **Project scaffolding** — Using `npx @objectstack/cli init` with templates (minimal-api, full-stack, plugin) -- **`defineStack()` configuration** — The core entry point for every ObjectStack project -- **Driver selection** — Choosing between memory, SQL, Turso drivers -- **Adapter integration** — Framework adapters (Express, Fastify, Hono, Next.js, etc.) -- **Runtime boot sequence** — How the kernel loads plugins and starts services -- **Multi-app composition** — `composeStacks()` for combining multiple stacks - -### When to Use - -Use this skill when you need to: -- Create a new ObjectStack project from scratch -- Configure `objectstack.config.ts` -- Choose the right driver and adapter for your use case -- Understand the boot sequence +```bash +npm create objectstack@latest my-app +``` -### Example Prompt +**Existing projects — install the whole bundle:** -``` -Using the objectstack-quickstart skill, create a new project -with a Turso driver and Hono adapter for Cloudflare Workers. +```bash +npx skills add objectstack-ai/framework --all ``` ---- - -## Schema Design +Run the same command again at any time to pull the latest versions — `--all` is idempotent, so updating is one command regardless of how many skills the bundle contains. To choose which skills to add instead of the full set, run `npx skills add objectstack-ai/framework` without `--all`. -**Path:** `skills/objectstack-schema/` -**Tags:** `object`, `field`, `validation`, `index`, `relationship`, `hooks`, `schema`, `data-model` +Skills are versioned as **one bundle**. You do not track or update each skill individually — `--all` always installs the matching set for the `@objectstack/spec` version in your project. -### What It Covers +--- -The Schema Design skill is the **most comprehensive skill** in the system, covering the entire Data Protocol: +{/* BEGIN GENERATED: skills (packages/spec/scripts/build-skill-docs.ts) — DO NOT EDIT */} -- **48 field types** with a decision tree for selection -- **Object definitions** — capabilities like `trackHistory`, `apiEnabled`, `trash`, `versioning` -- **Relationships** — lookup, master-detail, many-to-many patterns -- **Validation rules** — script, unique, state machine, cross-field, format validators -- **Index strategy** — btree, gin, gist, fulltext, composite, partial indexes -- **Lifecycle hooks** — beforeInsert, afterUpdate, and 12 other data events -- **Advanced features** — tenancy, soft delete, versioning, field encryption +ObjectStack ships **9 domain-specific skills**. Each is self-contained — an AI assistant loads only the ones a task needs. -### When to Use +## Quick Reference -Use this skill when you need to: -- Design new business objects or modify existing ones -- Choose the right field type for your data -- Configure relationships between objects -- Set up validation rules and indexes +| # | Skill | Domain | Path | What it covers | +| :--- | :--- | :--- | :--- | :--- | +| 1 | [Platform](#platform) | `platform` | `skills/objectstack-platform/` | Bootstrap, configure, extend, and operate ObjectStack runtimes. Covers project setup (`defineStack`, drivers, adapters, scaffolding), plugin and service development (PluginContext, DI, kernel hooks like `kernel:ready` and `data:*`), and operations (CLI commands, migrations, deployment, test harnesses via LiteKernel). | +| 2 | [Data](#data) | `data` | `skills/objectstack-data/` | Design ObjectStack data schemas — objects, fields, field conditional rules, relationships, validations, indexes, lifecycle hooks, permissions, row-level security — and the seed datasets (`defineDataset()`) that load fixtures and reference data alongside them. | +| 3 | [Query](#query) | `query` | `skills/objectstack-query/` | Construct ObjectQL queries — filters, sorting, pagination, aggregation, joins/expansion, window functions, and full-text search. | +| 4 | [UI](#ui) | `ui` | `skills/objectstack-ui/` | Author ObjectStack UI metadata — Views (list/form/kanban/calendar/gantt), Apps (navigation), Pages, Dashboards, Reports, Charts, Actions, and package Docs (`src/docs/*.md`). | +| 5 | [Automation](#automation) | `automation` | `skills/objectstack-automation/` | Design ObjectStack automation — Flows (visual logic), Workflows (declarative rules), Triggers, Approvals, scheduled jobs, and webhooks. | +| 6 | [AI](#ai) | `ai` | `skills/objectstack-ai/` | Design ObjectStack AI agents, tools, skills, conversations, model registry entries, and MCP integrations. | +| 7 | [API](#api) | `api` | `skills/objectstack-api/` | Design the server-side API surface that an ObjectStack runtime exposes — REST/GraphQL endpoints, auth providers, realtime channels, error envelopes, batch/versioning contracts. | +| 8 | [i18n](#i18n) | `i18n` | `skills/objectstack-i18n/` | Author ObjectStack translation bundles — object/field labels, view text, app navigation strings, automation messages — and configure locale fallback, coverage reporting, and the per-locale source layout. | +| 9 | [Formula](#formula) | `expression` | `skills/objectstack-formula/` | Author CEL expressions used across ObjectStack — formula fields, field conditional rules (`visibleWhen`, `readonlyWhen`, `requiredWhen`), validation / sharing / visibility predicates, flow conditions, and dynamic seed values. Use whenever the user is writing an `F`, `P`, or `cel` tagged-template literal, or asks "how do I express X as a formula / predicate". Do not use for SQL fragments (driver-native), cron schedules (cron dialect), or L2 hook bodies (those belong in objectstack-data). | -### When NOT to Use +--- -| Instead of... | Use... | -| :--- | :--- | -| Querying/filtering records | [Query Design](#query-design) | -| Building REST APIs | [API Design](#api-design) | -| Creating views or forms | [UI Design](#ui-design) | -| Workflow state machines | [Automation Design](#automation-design) | +### Platform -### Example Prompt +**Domain** `platform` · **Path** `skills/objectstack-platform/` -``` -Using the objectstack-schema skill, design a project_task object -with status state machine (draft → active → completed → archived), -priority field, and master-detail relationship to a project object. -``` +Bootstrap, configure, extend, and operate ObjectStack runtimes. Covers project setup (`defineStack`, drivers, adapters, scaffolding), plugin and service development (PluginContext, DI, kernel hooks like `kernel:ready` and `data:*`), and operations (CLI commands, migrations, deployment, test harnesses via LiteKernel). ---- +Use when the user is writing `objectstack.config.ts`, building a plugin or driver, wiring a framework adapter, running `os` CLI commands, or planning deployment. -## Query Design +Do not use for data schema design (see objectstack-data) or query patterns (see objectstack-query); data lifecycle hooks (beforeInsert / afterUpdate) belong in objectstack-data — only kernel / service-level events live here. - -**Path:** `skills/objectstack-query/` -**Tags:** `query`, `filter`, `sort`, `pagination`, `aggregation`, `search`, `ObjectQL`, `DSL` - +**Tags:** `project`, `defineStack`, `driver`, `adapter`, `plugin`, `kernel`, `service`, `DI`, `lifecycle`, `cli`, `deploy`, `ops` -### What It Covers +--- -The Query Design skill covers the **ObjectQL query language**: +### Data -- **Query structure** — QueryAST with required properties -- **Filter operators** — comparison (`$eq`, `$gt`, `$in`), string (`$contains`, `$startsWith`), logical (`$and`, `$or`, `$not`) -- **Nested filters** — Relation filters and `$field` references -- **Sorting & pagination** — `orderBy` with offset and cursor pagination -- **Aggregation** — count, sum, avg, min, max, count_distinct, array_agg, string_agg -- **GroupBy + HAVING** — Grouped aggregations with filtering -- **Expand system** — Related record expansion (max depth 3) -- **Joins** — inner, left, right, full with strategy hints -- **Full-text search** — Fuzzy matching, boost, and highlighting -- **Window functions** — row_number, rank, dense_rank, lag, lead +**Domain** `data` · **Path** `skills/objectstack-data/` -### When to Use +Design ObjectStack data schemas — objects, fields, field conditional rules, relationships, validations, indexes, lifecycle hooks, permissions, row-level security — and the seed datasets (`defineDataset()`) that load fixtures and reference data alongside them. -Use this skill when you need to: -- Build complex data queries -- Implement search functionality -- Create aggregated reports -- Join data across objects +Use when the user is creating or modifying `*.object.ts` / `*.seed.ts` files, picking field types, modelling relationships, writing `beforeInsert`/`afterUpdate` hooks, configuring per-object access control, or authoring bootstrap / demo data. Use for `visibleWhen` / `readonlyWhen` / `requiredWhen` rules that belong on fields. -### Example Prompt +Do not use for querying data (see objectstack-query) or for plugin / kernel hooks (see objectstack-platform). CEL expressions in formulas / validations / sharing rules / dynamic seed values: load objectstack-formula alongside. -``` -Using the objectstack-query skill, build a query that finds all -opportunities closing this quarter with amount > $100,000, -grouped by stage with total revenue per stage. -``` +**Tags:** `object`, `field`, `validation`, `index`, `relationship`, `hook`, `schema`, `permission`, `rls`, `security`, `seed`, `dataset`, `fixture` --- -## API Design +### Query - -**Path:** `skills/objectstack-api/` -**Tags:** `rest`, `endpoint`, `service`, `datasource` - - -### What It Covers - -- **Auto-generated CRUD** — GET, POST, PATCH, DELETE with filter/sort/pagination -- **Custom endpoints** — Definition with `handlerStatus` (implemented, stub, planned) -- **14 API methods** — get, list, create, update, delete, upsert, bulk, aggregate, history, search, restore, purge, import, export -- **Service discovery** — `/api/v1/discovery` and `/.well-known/objectstack` -- **Authentication & authorization** — RBAC, RLS, FLS, rate limiting -- **Datasource configuration** — SQL, MySQL, SQLite, Turso, memory drivers -- **Inter-service communication** — Service contracts and kernel resolution +**Domain** `query` · **Path** `skills/objectstack-query/` -### When to Use +Construct ObjectQL queries — filters, sorting, pagination, aggregation, joins/expansion, window functions, and full-text search. -Use this skill when you need to: -- Define custom API endpoints -- Configure datasources and connections -- Set up authentication and authorization -- Design inter-service communication +Use when the user is writing a query DSL expression, picking pagination strategy, or designing a list view's filter spec. -### Example Prompt +Do not use for defining objects / fields / relationships (see objectstack-data) or for designing the API endpoint that exposes a query (see objectstack-api). -``` -Using the objectstack-api skill, define a custom endpoint -POST /api/v1/invoices/:id/send that triggers an email flow -and updates the invoice status. -``` +**Tags:** `query`, `filter`, `sort`, `paginate`, `aggregate`, `ObjectQL`, `full-text` --- -## UI Design +### UI - -**Path:** `skills/objectstack-ui/` -**Tags:** `view`, `app`, `dashboard`, `report`, `action` - +**Domain** `ui` · **Path** `skills/objectstack-ui/` -### What It Covers +Author ObjectStack UI metadata — Views (list/form/kanban/calendar/gantt), Apps (navigation), Pages, Dashboards, Reports, Charts, Actions, and package Docs (`src/docs/*.md`). -- **7 view types** — grid, kanban, gallery, calendar, timeline, gantt, map -- **3 form types** — simple, tabbed, wizard -- **Field conditional rules** — `visibleWhen`, `readonlyWhen`, `requiredWhen` with CEL predicates -- **List view columns** — field, label, width, align, hidden, pinned, sortable, link, summary -- **App navigation** — object, dashboard, url, divider items -- **Dashboard design** — Grid layout with metric, chart, list, calendar, custom widgets, and dataset-bound widgets -- **Report types** — tabular, summary, matrix, chart -- **Actions** — button, url, flow, api with visibility conditions and confirmations +Use when the user is adding `*.view.ts` / `*.app.ts` / `*.dashboard.ts` / `*.action.ts` / `src/docs/*.md` files or designing a Studio-rendered UI surface, including dataset-bound dashboard/report widgets. -### When to Use +Do not use for: data schema (see objectstack-data), interactive screen flows / wizards (those are `*.flow.ts` with `type: 'screen'` — see objectstack-automation), the React renderer implementation (lives in `packages/client-react`, not metadata), or Studio's own admin UI (that ships with the platform). CEL expressions in visibility/conditional rules: load objectstack-formula alongside. -Use this skill when you need to: -- Design list views, forms, or kanban boards -- Build app navigation structures -- Create dashboards with widgets -- Configure user-facing actions and buttons - -### Example Prompt - -``` -Using the objectstack-ui skill, design a CRM app with: -- A kanban view for opportunities grouped by stage -- A tabbed form for customer details -- A dashboard with revenue metrics and pipeline chart -``` +**Tags:** `view`, `app`, `page`, `dashboard`, `report`, `chart`, `action`, `widget`, `doc` --- -## Automation Design - - -**Path:** `skills/objectstack-automation/` -**Tags:** `flow`, `workflow`, `trigger`, `approval`, `state-machine` - - -### What It Covers +### Automation -- **5 flow types** — autolaunched, screen, schedule, record_triggered, platform_event -- **18 flow node types** — start, end, decision, loop, assignment, create_record, update_record, http_request, script, screen, etc. -- **Workflows** — State machine configuration with initial/final states, transition guards -- **Approval processes** — Entry conditions, steps, escalation, timeouts -- **Triggers** — before/after events with OLD/NEW variable access +**Domain** `automation` · **Path** `skills/objectstack-automation/` -### When to Use +Design ObjectStack automation — Flows (visual logic), Workflows (declarative rules), Triggers, Approvals, scheduled jobs, and webhooks. -Use this skill when you need to: -- Build visual logic flows for business processes -- Design state machines for record lifecycle -- Set up approval workflows -- Configure scheduled or event-driven automations +Use when the user is adding `*.flow.ts` / `*.workflow.ts`, wiring an event-driven rule, or modelling an approval chain. -### Example Prompt +Do not use for data lifecycle hooks at the object layer (see objectstack-data) or for kernel / plugin events (see objectstack-platform). CEL expressions in flow conditions / workflow predicates: load objectstack-formula alongside. -``` -Using the objectstack-automation skill, design an auto-escalation -flow that reassigns overdue support cases to a manager after 48 hours. -``` +**Tags:** `flow`, `workflow`, `trigger`, `approval`, `state-machine`, `scheduled`, `webhook` --- -## AI Agent Design +### AI - -**Path:** `skills/objectstack-ai/` -**Tags:** `agent`, `skill`, `tool`, `rag`, `llm` - +**Domain** `ai` · **Path** `skills/objectstack-ai/` -### What It Covers +Design ObjectStack AI agents, tools, skills, conversations, model registry entries, and MCP integrations. -- **Three-tier architecture** — Agent → Skill → Tool -- **Agent configuration** — name, role, instructions, skills, tools, model, guardrails, temperature -- **Skill bundles** — Groups of related tools with trigger conditions -- **Tool types** — action, flow, query, vector_search -- **RAG pipelines** — Sources, indexes, retrieval strategy, generation model -- **LLM providers** — OpenAI, Anthropic, Azure OpenAI, local (Ollama, vLLM) -- **Guardrails** — Input/output validation, PII masking, content filtering +Use when the user is adding `*.agent.ts` / `*.tool.ts` / `*.skill.ts`, configuring an LLM provider, wiring agent tools, or designing an embedding/RAG flow on top of ObjectStack data. -### When to Use +Do not use for general LLM prompting questions unrelated to ObjectStack metadata. -Use this skill when you need to: -- Configure AI agents for specific business tasks -- Design RAG pipelines with vector search -- Define agent tools and skills -- Choose LLM models and temperature settings - -### Example Prompt - -``` -Using the objectstack-ai skill, design a customer service agent -with case triage, knowledge base search, and response generation tools. -``` +**Tags:** `agent`, `tool`, `skill`, `conversation`, `llm`, `embedding`, `mcp` --- -## Plugin Development +### API - -**Path:** `skills/objectstack-plugin/` -**Tags:** `plugin`, `kernel`, `service`, `hook`, `event`, `DI`, `lifecycle`, `bootstrap` - - -### What It Covers +**Domain** `api` · **Path** `skills/objectstack-api/` -- **ObjectKernel vs LiteKernel** — Production vs serverless/test environments -- **Plugin interface** — name, version, type, dependencies, init/start/destroy phases -- **PluginContext API** — Service registry, hook/event system, logger, kernel access -- **Service registry** — DI container, factories, lifecycle (singleton/transient/scoped) -- **Hook/event system** — Inter-plugin communication and lifecycle events -- **Bootstrap sequence** — The full initialization order -- **Health monitoring** — Plugin health checks and feature flags +Design the server-side API surface that an ObjectStack runtime exposes — REST/GraphQL endpoints, auth providers, realtime channels, error envelopes, batch/versioning contracts. -### When to Use +Use when the user is adding `*.endpoint.ts`, configuring auth providers, defining custom routes, or extending the REST/GraphQL generator. -Use this skill when you need to: -- Build a custom plugin from scratch -- Register services with the DI container -- Subscribe to kernel lifecycle events -- Understand the bootstrap sequence +Do not use for: consuming an ObjectStack API from a client (that is just standard HTTP — no skill needed); the auto-generated CRUD endpoints (those follow from objectstack-data); request-side query syntax (see objectstack-query). CEL expressions in route guards or auth predicates: load objectstack-formula alongside. -### Example Prompt - -``` -Using the objectstack-plugin skill, create a caching plugin -that registers a cache service with TTL support and integrates -with the kernel's health monitoring. -``` +**Tags:** `rest`, `graphql`, `endpoint`, `auth`, `realtime`, `server` --- -## I18n Design +### i18n - -**Path:** `skills/objectstack-i18n/` -**Tags:** `i18n`, `translation`, `locale`, `internationalization`, `l10n` - +**Domain** `i18n` · **Path** `skills/objectstack-i18n/` -### What It Covers +Author ObjectStack translation bundles — object/field labels, view text, app navigation strings, automation messages — and configure locale fallback, coverage reporting, and the per-locale source layout. -- **Translation architecture** — Object-first model, global groups, locale files -- **File organization** — bundled, per_locale (recommended), per_namespace (enterprise) -- **Object translation** — Fields, options, views, sections, actions, notifications, errors -- **Coverage detection** — Missing, redundant, and stale translation detection -- **Message interpolation** — Simple format vs ICU MessageFormat -- **Translation workflow** — Extract → translate → validate → deploy -- **Advanced patterns** — RTL support, namespace isolation, translation memory +Use when the user is adding `*.translation.ts` files, wiring a new locale, or resolving missing-translation warnings. -### When to Use +Do not use for general i18n library questions unrelated to ObjectStack bundles. -Use this skill when you need to: -- Add multi-language support to your application -- Design translation bundle structures -- Configure locale settings and fallback chains -- Detect missing translations - -### Example Prompt - -``` -Using the objectstack-i18n skill, set up i18n for a CRM app -with English, Chinese, and Japanese locales using per_locale -file organization. -``` +**Tags:** `i18n`, `translation`, `locale`, `l10n`, `bundle`, `coverage` --- -## Hooks System - - -**Path:** `skills/objectstack-hooks/` -**Tags:** `hooks`, `lifecycle`, `validation`, `business-logic`, `events` - - -### What It Covers - -- **14 data lifecycle events** — beforeFind, afterFind, beforeInsert, afterInsert, beforeUpdate, afterUpdate, beforeDelete, afterDelete, and more -- **Plugin hooks** — kernel:ready, data:*, custom events -- **HookContext API** — Access to record data, query, user context -- **Registration methods** — Inline hooks, plugin hooks, object-level hooks -- **Data hooks vs Plugin hooks** — When to use each +### Formula -### When to Use +**Domain** `expression` · **Path** `skills/objectstack-formula/` -Use this skill when you need to: -- Add validation logic before record creation -- Enrich data after record updates -- Listen to kernel lifecycle events -- Implement cross-cutting concerns (audit, cache invalidation) +Author CEL expressions used across ObjectStack — formula fields, field conditional rules (`visibleWhen`, `readonlyWhen`, `requiredWhen`), validation / sharing / visibility predicates, flow conditions, and dynamic seed values. Use whenever the user is writing an `F`, `P`, or `cel` tagged-template literal, or asks "how do I express X as a formula / predicate". Do not use for SQL fragments (driver-native), cron schedules (cron dialect), or L2 hook bodies (those belong in objectstack-data). -### Example Prompt +Do not use for SQL fragments (driver-native), cron schedules (cron dialect), or L2 hook bodies (those belong in objectstack-data). -``` -Using the objectstack-hooks skill, implement a beforeInsert hook -that validates email uniqueness and an afterInsert hook that sends -a welcome notification. -``` +**Tags:** `cel`, `formula`, `predicate`, `condition`, `validation`, `visibility`, `seed-dynamic` --- -## Skill Directory Structure +{/* END GENERATED: skills */} -Every skill follows a consistent directory layout: +## Skill anatomy + +Every skill is a directory under `skills/`: ``` skills/objectstack-{domain}/ -├── SKILL.md # Entry point — overview, decision trees, quick-start -├── rules/ # Detailed implementation rules -│ ├── naming.md # Naming convention rules -│ ├── patterns.md # Common pattern rules -│ └── ... -├── evals/ # AI comprehension test cases -│ └── ... -└── references/ # Reference materials - └── ... +├── SKILL.md # required — frontmatter (name, description, domain, tags) + prose guide +├── references/ +│ └── _index.md # generated — pointers into @objectstack/spec Zod sources +├── rules/ # optional — detailed implementation rules +└── evals/ # optional — AI comprehension test cases ``` +`SKILL.md` is the only required file. The `references/_index.md` index is generated by `packages/spec/scripts/build-skill-references.ts` and points into the published `@objectstack/spec` schemas in `node_modules` — skills never bundle copies of the schemas, so they stay version-aligned automatically. + + +The catalog above (names, domains, descriptions) is **generated from each `SKILL.md` frontmatter** by `build-skill-docs.ts`. Edit the frontmatter, not this page — then run `pnpm --filter @objectstack/spec gen:skill-docs`. + + --- -## Best Practices +## Best practices -### 1. Start with the Right Skill +### 1. Start with the right skill -Don't guess — use the [Quick Reference](#quick-reference) table to find the skill that matches your task. If unsure, start with **Quickstart**. +Use the [Quick Reference](#quick-reference) table to find the skill that matches your task rather than guessing. When a task spans domains, the per-skill "Do not use for …" notes point you to the right neighbour. -### 2. Chain Skills for Complex Tasks +### 2. Chain skills for complex tasks -Most real-world tasks span multiple domains. Chain skills in order: +Most real-world work spans multiple domains. A typical CRM feature chains: ``` -Schema Design → Query Design → UI Design → API Design +Data → Query → UI → Automation → API ``` -### 3. Reference Skills in Prompts +### 3. Load Formula alongside its host -Be explicit about which skill you're using. This helps the AI assistant load the right context and constraints. +Any CEL expression — a validation predicate, a flow condition, a field visibility rule — is covered by **Formula**. Load it *in addition to* the host skill (Data, Automation, UI), not instead of it. -### 4. Respect Skill Boundaries +### 4. Respect skill boundaries -If a skill says "delegate to X for Y", follow that guidance. Skills are designed to be focused and composable — not monolithic. +If a skill says "delegate to X for Y", follow it. Skills are deliberately focused and composable — keeping them narrow is what lets an assistant load only the context a task needs. --- -## Next Steps +## Next steps -- [AI Skills System](/docs/concepts/skills) — Conceptual overview of the skills architecture +- [AI Skills System](/docs/concepts/skills) — conceptual overview of the skills architecture - [AI Capabilities](/docs/guides/ai-capabilities) — AI agents, RAG pipelines, and intelligent automation -- [Plugin Development](/docs/guides/plugin-development) — Build custom plugins -- [Development Standards](/docs/guides/standards) — Naming conventions and project structure +- [Plugin Development](/docs/guides/plugin-development) — build custom plugins +- [Development Standards](/docs/guides/standards) — naming conventions and project structure diff --git a/packages/spec/package.json b/packages/spec/package.json index a5adc2e222..00a258d3b3 100644 --- a/packages/spec/package.json +++ b/packages/spec/package.json @@ -185,6 +185,8 @@ "gen:openapi": "tsx scripts/build-openapi.ts", "gen:docs": "tsx scripts/build-docs.ts", "gen:skill-refs": "tsx scripts/build-skill-references.ts", + "gen:skill-docs": "tsx scripts/build-skill-docs.ts", + "check:skill-docs": "tsx scripts/build-skill-docs.ts --check", "analyze": "tsx scripts/analyze-bundle-size.ts", "gen:sbom": "tsx scripts/generate-sbom.ts", "test": "vitest run", diff --git a/packages/spec/scripts/build-skill-docs.ts b/packages/spec/scripts/build-skill-docs.ts new file mode 100644 index 0000000000..51f42b7ada --- /dev/null +++ b/packages/spec/scripts/build-skill-docs.ts @@ -0,0 +1,258 @@ +// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license. + +/** + * Build Skill Docs + * + * The catalog of AI skills (names, domains, "use when / do not use") lives in + * exactly one place: the YAML frontmatter of each skill's `SKILL.md`. + * Hand-maintained copies of that catalog drift — they have, repeatedly. This + * script regenerates every derived listing from the frontmatter so there is a + * single source of truth. + * + * Derived listings (rewritten between `` + * markers; prose outside the markers is preserved): + * - skills/README.md → the Index table + * - content/docs/guides/skills.mdx → Quick Reference table + per-skill cards + * + * Usage: + * tsx scripts/build-skill-docs.ts # write + * tsx scripts/build-skill-docs.ts --check # verify in sync (CI); exit 1 on drift + */ + +import fs from 'fs'; +import path from 'path'; + +// ── Paths ──────────────────────────────────────────────────────────────────── + +const REPO_ROOT = path.resolve(__dirname, '../../..'); +const SKILLS_DIR = path.resolve(REPO_ROOT, 'skills'); +const README = path.resolve(SKILLS_DIR, 'README.md'); +const GUIDE = path.resolve(REPO_ROOT, 'content/docs/guides/skills.mdx'); + +// Marker comments delimit the generated region. MDX does not support HTML +// comments (``) — it needs `{/* */}` — so the syntax is per file type. +type CommentStyle = 'html' | 'mdx'; +function marks(style: CommentStyle): { begin: string; end: string } { + const id = 'skills (packages/spec/scripts/build-skill-docs.ts) — DO NOT EDIT'; + return style === 'mdx' + ? { begin: `{/* BEGIN GENERATED: ${id} */}`, end: `{/* END GENERATED: skills */}` } + : { begin: ``, end: `` }; +} + +// ── Display config ─────────────────────────────────────────────────────────── +// Presentation only (order + human label). The catalog itself is read from the +// SKILL.md frontmatter — adding a skill here without a SKILL.md, or vice-versa, +// is reported as an error so the two cannot silently diverge. + +const DISPLAY: Array<{ name: string; label: string }> = [ + { name: 'objectstack-platform', label: 'Platform' }, + { name: 'objectstack-data', label: 'Data' }, + { name: 'objectstack-query', label: 'Query' }, + { name: 'objectstack-ui', label: 'UI' }, + { name: 'objectstack-automation', label: 'Automation' }, + { name: 'objectstack-ai', label: 'AI' }, + { name: 'objectstack-api', label: 'API' }, + { name: 'objectstack-i18n', label: 'i18n' }, + { name: 'objectstack-formula', label: 'Formula' }, +]; + +// ── Frontmatter parser ─────────────────────────────────────────────────────── +// Narrow parser for the controlled SKILL.md frontmatter shape (folded `>` +// description + nested `metadata:` map). Avoids a YAML dependency, matching the +// sibling build-skill-references.ts. + +interface Skill { + name: string; + label: string; + anchor: string; + domain: string; + tags: string[]; + /** Prose before "Use when …". */ + summary: string; + /** The "Use when …" clause (kept verbatim, leading words included). */ + useWhen: string; + /** The "Do not use …" clause (kept verbatim, leading words included). */ + notFor: string; +} + +function parseFrontmatter(name: string, label: string): Skill { + const file = path.resolve(SKILLS_DIR, name, 'SKILL.md'); + const raw = fs.readFileSync(file, 'utf-8'); + const parts = raw.split(/^---\s*$/m); + if (parts.length < 3) throw new Error(`${name}: no YAML frontmatter`); + const lines = parts[1].split('\n'); + + let description = ''; + let domain = ''; + let tags: string[] = []; + + for (let i = 0; i < lines.length; i++) { + if (/^description:\s*>/.test(lines[i])) { + const buf: string[] = []; + i++; + while (i < lines.length && /^\s+\S/.test(lines[i])) { + buf.push(lines[i].trim()); + i++; + } + i--; + description = buf.join(' ').replace(/\s+/g, ' ').trim(); + } else if (/^metadata:\s*$/.test(lines[i])) { + i++; + while (i < lines.length && /^\s+\S/.test(lines[i])) { + const m = lines[i].match(/^\s+(\w+):\s*(.*)$/); + if (m && m[1] === 'domain') domain = m[2].replace(/['"]/g, '').trim(); + if (m && m[1] === 'tags') tags = m[2].split(',').map((t) => t.trim()).filter(Boolean); + i++; + } + i--; + } + } + + if (!description) throw new Error(`${name}: missing description`); + if (!domain) throw new Error(`${name}: missing metadata.domain`); + + // Split the description into summary / use-when / do-not-use, keeping each + // clause verbatim (no paraphrasing — the frontmatter is the source). + const useIdx = description.search(/\bUse when\b/); + const notIdx = description.search(/\bDo not use\b/); + const summary = (useIdx >= 0 ? description.slice(0, useIdx) : description).trim(); + const useWhen = + useIdx >= 0 ? description.slice(useIdx, notIdx >= 0 ? notIdx : undefined).trim() : ''; + const notFor = notIdx >= 0 ? description.slice(notIdx).trim() : ''; + + return { + name, + label, + anchor: name.replace(/^objectstack-/, ''), + domain, + tags, + summary, + useWhen, + notFor, + }; +} + +// ── Renderers ──────────────────────────────────────────────────────────────── + +function renderReadmeBlock(skills: Skill[]): string { + const { begin, end } = marks('html'); + const rows = skills.map( + (s) => `| [${s.label}](./${s.name}/SKILL.md) | \`${s.domain}\` | ${s.summary} |`, + ); + return [ + begin, + '', + `| Skill | Domain | What it covers |`, + `|:------|:-------|:---------------|`, + ...rows, + '', + end, + ].join('\n'); +} + +function renderGuideBlock(skills: Skill[]): string { + const { begin, end } = marks('mdx'); + const tableRows = skills.map( + (s, i) => + `| ${i + 1} | [${s.label}](#${s.anchor}) | \`${s.domain}\` | \`skills/${s.name}/\` | ${s.summary} |`, + ); + + const cards = skills.flatMap((s) => { + // No explicit `{#id}` — MDX would parse it as a JS expression. The heading + // text auto-slugs (rehype-slug) to `s.anchor`, which the table links to. + const lines = [ + `### ${s.label}`, + '', + `**Domain** \`${s.domain}\` · **Path** \`skills/${s.name}/\``, + '', + s.summary, + '', + ]; + if (s.useWhen) lines.push(s.useWhen, ''); + if (s.notFor) lines.push(s.notFor, ''); + if (s.tags.length) lines.push(`**Tags:** ${s.tags.map((t) => `\`${t}\``).join(', ')}`, ''); + lines.push('---', ''); + return lines; + }); + + return [ + begin, + '', + `ObjectStack ships **${skills.length} domain-specific skills**. Each is self-contained — an AI assistant loads only the ones a task needs.`, + '', + '## Quick Reference', + '', + `| # | Skill | Domain | Path | What it covers |`, + `| :--- | :--- | :--- | :--- | :--- |`, + ...tableRows, + '', + '---', + '', + ...cards, + end, + ].join('\n'); +} + +// ── Marker splice ──────────────────────────────────────────────────────────── + +function spliceBlock(file: string, block: string, style: CommentStyle): string { + const { begin, end } = marks(style); + const content = fs.readFileSync(file, 'utf-8'); + const b = content.indexOf(begin); + const e = content.indexOf(end); + if (b === -1 || e === -1 || e < b) { + throw new Error( + `${path.relative(REPO_ROOT, file)}: missing or malformed generated markers.\n` + + `Add a "${begin}" / "${end}" pair where the generated listing should go.`, + ); + } + return content.slice(0, b) + block + content.slice(e + end.length); +} + +// ── Main ───────────────────────────────────────────────────────────────────── + +function main() { + const check = process.argv.includes('--check'); + + // Catalog ⇄ DISPLAY must be in lockstep. + const onDisk = fs + .readdirSync(SKILLS_DIR) + .filter((d) => d.startsWith('objectstack-') && fs.existsSync(path.resolve(SKILLS_DIR, d, 'SKILL.md'))); + const configured = new Set(DISPLAY.map((d) => d.name)); + const missing = onDisk.filter((d) => !configured.has(d)); + const extra = DISPLAY.filter((d) => !onDisk.includes(d.name)).map((d) => d.name); + if (missing.length || extra.length) { + if (missing.length) console.error(`✗ SKILL.md without DISPLAY entry: ${missing.join(', ')}`); + if (extra.length) console.error(`✗ DISPLAY entry without SKILL.md: ${extra.join(', ')}`); + process.exit(1); + } + + const skills = DISPLAY.map((d) => parseFrontmatter(d.name, d.label)); + + const targets: Array<{ file: string; style: CommentStyle; render: (s: Skill[]) => string }> = [ + { file: README, style: 'html', render: renderReadmeBlock }, + { file: GUIDE, style: 'mdx', render: renderGuideBlock }, + ]; + + let drift = false; + for (const { file, style, render } of targets) { + const next = spliceBlock(file, render(skills), style); + const rel = path.relative(REPO_ROOT, file); + if (check) { + if (fs.readFileSync(file, 'utf-8') !== next) { + console.error(`✗ ${rel} is out of date — run \`pnpm --filter @objectstack/spec gen:skill-docs\``); + drift = true; + } else { + console.log(`✓ ${rel}`); + } + } else { + fs.writeFileSync(file, next); + console.log(`✅ ${rel}`); + } + } + + if (check && drift) process.exit(1); + console.log(check ? '\n✅ Skill docs in sync' : `\n✅ Generated from ${skills.length} SKILL.md files`); +} + +main(); diff --git a/skills/README.md b/skills/README.md index cc79a1cfd6..9b8e9874a6 100644 --- a/skills/README.md +++ b/skills/README.md @@ -12,17 +12,23 @@ authoritative Zod sources in `node_modules/@objectstack/spec/src/...`. ## Index -| Skill | Use when you are… | -|:------|:------------------| -| [objectstack-platform](./objectstack-platform/SKILL.md) | Bootstrapping or operating a runtime — `defineStack`, drivers, adapters, plugins, services, CLI, deploy. | -| [objectstack-data](./objectstack-data/SKILL.md) | Modelling objects, fields, field conditional rules, relationships, validations, indexes, lifecycle hooks, permissions / RLS, or seed datasets. | -| [objectstack-query](./objectstack-query/SKILL.md) | Writing ObjectQL — filters, sorting, pagination, aggregation, joins, window functions, full-text search. | -| [objectstack-ui](./objectstack-ui/SKILL.md) | Designing Views, Apps, Pages, Dashboards, dataset-bound widgets, Reports, Charts, or Actions. | -| [objectstack-automation](./objectstack-automation/SKILL.md) | Wiring Flows, Workflows, Triggers, Approvals, scheduled jobs, or webhooks. | -| [objectstack-ai](./objectstack-ai/SKILL.md) | Designing Agents, Tools, Skills, Conversations, Model Registry entries, or MCP integrations. | -| [objectstack-api](./objectstack-api/SKILL.md) | Exposing server-side API surface — REST/GraphQL endpoints, auth, realtime, error envelopes. | -| [objectstack-i18n](./objectstack-i18n/SKILL.md) | Authoring translation bundles, configuring locale fallback, or reading coverage reports. | -| [objectstack-formula](./objectstack-formula/SKILL.md) | Writing CEL expressions — formula fields, field rules, predicates (validation / sharing / visibility), conditions, dynamic seed values. | + + +| Skill | Domain | What it covers | +|:------|:-------|:---------------| +| [Platform](./objectstack-platform/SKILL.md) | `platform` | Bootstrap, configure, extend, and operate ObjectStack runtimes. Covers project setup (`defineStack`, drivers, adapters, scaffolding), plugin and service development (PluginContext, DI, kernel hooks like `kernel:ready` and `data:*`), and operations (CLI commands, migrations, deployment, test harnesses via LiteKernel). | +| [Data](./objectstack-data/SKILL.md) | `data` | Design ObjectStack data schemas — objects, fields, field conditional rules, relationships, validations, indexes, lifecycle hooks, permissions, row-level security — and the seed datasets (`defineDataset()`) that load fixtures and reference data alongside them. | +| [Query](./objectstack-query/SKILL.md) | `query` | Construct ObjectQL queries — filters, sorting, pagination, aggregation, joins/expansion, window functions, and full-text search. | +| [UI](./objectstack-ui/SKILL.md) | `ui` | Author ObjectStack UI metadata — Views (list/form/kanban/calendar/gantt), Apps (navigation), Pages, Dashboards, Reports, Charts, Actions, and package Docs (`src/docs/*.md`). | +| [Automation](./objectstack-automation/SKILL.md) | `automation` | Design ObjectStack automation — Flows (visual logic), Workflows (declarative rules), Triggers, Approvals, scheduled jobs, and webhooks. | +| [AI](./objectstack-ai/SKILL.md) | `ai` | Design ObjectStack AI agents, tools, skills, conversations, model registry entries, and MCP integrations. | +| [API](./objectstack-api/SKILL.md) | `api` | Design the server-side API surface that an ObjectStack runtime exposes — REST/GraphQL endpoints, auth providers, realtime channels, error envelopes, batch/versioning contracts. | +| [i18n](./objectstack-i18n/SKILL.md) | `i18n` | Author ObjectStack translation bundles — object/field labels, view text, app navigation strings, automation messages — and configure locale fallback, coverage reporting, and the per-locale source layout. | +| [Formula](./objectstack-formula/SKILL.md) | `expression` | Author CEL expressions used across ObjectStack — formula fields, field conditional rules (`visibleWhen`, `readonlyWhen`, `requiredWhen`), validation / sharing / visibility predicates, flow conditions, and dynamic seed values. Use whenever the user is writing an `F`, `P`, or `cel` tagged-template literal, or asks "how do I express X as a formula / predicate". Do not use for SQL fragments (driver-native), cron schedules (cron dialect), or L2 hook bodies (those belong in objectstack-data). | + + + +> Regenerate with `pnpm --filter @objectstack/spec gen:skill-docs` after editing any `SKILL.md` frontmatter. ---