|
| 1 | +--- |
| 2 | +title: AI Skills System |
| 3 | +description: How ObjectStack uses structured AI skills to enable intelligent code generation, review, and automation |
| 4 | +--- |
| 5 | + |
| 6 | +import { Bot, Brain, Cpu, Database, Globe, Layout, Shield, Workflow, Wrench, Languages, Zap, Puzzle, BookOpen, Target, ArrowRight } from 'lucide-react'; |
| 7 | + |
| 8 | +# AI Skills System |
| 9 | + |
| 10 | +ObjectStack introduces a **Skills System** — structured, domain-specific knowledge modules that enable AI assistants (GitHub Copilot, Claude Code, Cursor, etc.) to understand and generate protocol-compliant code. |
| 11 | + |
| 12 | +<Callout type="info"> |
| 13 | +Skills are **not runtime code**. They are machine-readable knowledge definitions that teach AI assistants the ObjectStack protocol — its schemas, patterns, constraints, and best practices. |
| 14 | +</Callout> |
| 15 | + |
| 16 | +--- |
| 17 | + |
| 18 | +## Why Skills? |
| 19 | + |
| 20 | +Traditional AI code assistants generate generic code. They don't understand: |
| 21 | + |
| 22 | +- That ObjectStack field names **must** be `snake_case` |
| 23 | +- That schemas are **Zod-first**, not TypeScript-first |
| 24 | +- That plugins follow a specific **lifecycle** (init → start → destroy) |
| 25 | +- That queries use a **structured AST**, not raw SQL strings |
| 26 | + |
| 27 | +**Skills solve this.** Each skill teaches the AI assistant the rules, patterns, and constraints for a specific ObjectStack protocol domain. |
| 28 | + |
| 29 | +``` |
| 30 | +┌─────────────────────────────────────────────────────────────┐ |
| 31 | +│ AI Assistant │ |
| 32 | +│ (GitHub Copilot / Claude Code / Cursor) │ |
| 33 | +├─────────────────────────────────────────────────────────────┤ |
| 34 | +│ Skills Layer │ |
| 35 | +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ |
| 36 | +│ │ Schema │ │ Query │ │ UI │ │ Plugin │ ... │ |
| 37 | +│ │ Skill │ │ Skill │ │ Skill │ │ Skill │ │ |
| 38 | +│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ |
| 39 | +├─────────────────────────────────────────────────────────────┤ |
| 40 | +│ ObjectStack Protocol │ |
| 41 | +│ Objects, Fields, Views, Flows, Agents, Plugins, ... │ |
| 42 | +└─────────────────────────────────────────────────────────────┘ |
| 43 | +``` |
| 44 | + |
| 45 | +## Skill Architecture |
| 46 | + |
| 47 | +Each skill follows a **three-layer structure** inspired by [shadcn/ui](https://ui.shadcn.com/): |
| 48 | + |
| 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 | |
| 54 | + |
| 55 | +### SKILL.md — The Entry Point |
| 56 | + |
| 57 | +Each `SKILL.md` starts with structured metadata: |
| 58 | + |
| 59 | +```yaml |
| 60 | +--- |
| 61 | +skill: objectstack-schema |
| 62 | +version: 3.0 |
| 63 | +domain: data |
| 64 | +description: Design ObjectStack data schemas |
| 65 | +tags: [object, field, validation, index, relationship] |
| 66 | +--- |
| 67 | +``` |
| 68 | + |
| 69 | +The body contains: |
| 70 | +- **When to use** this skill (and when NOT to) |
| 71 | +- **Decision trees** for choosing between options |
| 72 | +- **Quick-start examples** for common patterns |
| 73 | +- **Cross-references** to related skills |
| 74 | + |
| 75 | +### Rules — The Guardrails |
| 76 | + |
| 77 | +Rules are detailed implementation constraints shown with side-by-side correct/incorrect examples: |
| 78 | + |
| 79 | +```markdown |
| 80 | +## ❌ INCORRECT: TypeScript types without Zod |
| 81 | +interface User { |
| 82 | + name: string; |
| 83 | + email: string; |
| 84 | +} |
| 85 | + |
| 86 | +## ✅ CORRECT: Zod-first schema definition |
| 87 | +const UserSchema = z.object({ |
| 88 | + name: z.string(), |
| 89 | + email: z.string().email(), |
| 90 | +}); |
| 91 | +type User = z.infer<typeof UserSchema>; |
| 92 | +``` |
| 93 | + |
| 94 | +This format ensures AI assistants generate protocol-compliant code. |
| 95 | + |
| 96 | +--- |
| 97 | + |
| 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> |
| 154 | + |
| 155 | +--- |
| 156 | + |
| 157 | +## Skill Boundaries |
| 158 | + |
| 159 | +Each skill has **clear boundaries** — it knows what it's responsible for and explicitly delegates to other skills when needed: |
| 160 | + |
| 161 | +``` |
| 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 | + └──────────┘ └──────┘ |
| 187 | +``` |
| 188 | + |
| 189 | +| Skill | Delegates To | For | |
| 190 | +| :--- | :--- | :--- | |
| 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 | |
| 199 | + |
| 200 | +--- |
| 201 | + |
| 202 | +## Using Skills |
| 203 | + |
| 204 | +### With GitHub Copilot |
| 205 | + |
| 206 | +Skills are automatically loaded from the `skills/` directory when using GitHub Copilot in VS Code. Reference a skill directly: |
| 207 | + |
| 208 | +``` |
| 209 | +@workspace Use the objectstack-schema skill to design a customer object |
| 210 | +with name, email, industry, and annual_revenue fields. |
| 211 | +``` |
| 212 | + |
| 213 | +### With Claude Code |
| 214 | + |
| 215 | +Claude Code reads `CLAUDE.md` at the repo root, which references all skills: |
| 216 | + |
| 217 | +``` |
| 218 | +Read skills/objectstack-query/SKILL.md and help me build a query |
| 219 | +that filters opportunities by stage and aggregates revenue by quarter. |
| 220 | +``` |
| 221 | + |
| 222 | +### With Cursor |
| 223 | + |
| 224 | +Add the skill files to your Cursor rules or reference them in prompts: |
| 225 | + |
| 226 | +``` |
| 227 | +@skills/objectstack-plugin/SKILL.md Create a plugin that adds |
| 228 | +an audit logging service to the kernel. |
| 229 | +``` |
| 230 | + |
| 231 | +--- |
| 232 | + |
| 233 | +## Design Philosophy |
| 234 | + |
| 235 | +The Skills System embodies ObjectStack's core principles: |
| 236 | + |
| 237 | +### 1. Metadata-Driven |
| 238 | + |
| 239 | +Skills are **structured metadata** — not executable code. They define *what* the AI should know, not *how* to run it. This mirrors ObjectStack's approach to data, UI, and automation. |
| 240 | + |
| 241 | +### 2. Composable |
| 242 | + |
| 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. |
| 244 | + |
| 245 | +### 3. Protocol-Aligned |
| 246 | + |
| 247 | +Each skill maps directly to an ObjectStack protocol domain. The schema skill teaches the Data Protocol, the UI skill teaches the UI Protocol, and so on. This ensures consistency between AI-generated code and the protocol specification. |
| 248 | + |
| 249 | +### 4. Testable |
| 250 | + |
| 251 | +The `evals/` directory in each skill allows teams to validate that their AI assistant correctly understands the protocol. This is analogous to test suites for runtime code — but for AI comprehension. |
| 252 | + |
| 253 | +--- |
| 254 | + |
| 255 | +## Next Steps |
| 256 | + |
| 257 | +- [AI Skills Reference](/docs/guides/skills) — Detailed guide to each skill with usage examples |
| 258 | +- [AI Capabilities](/docs/guides/ai-capabilities) — AI agents, RAG pipelines, and intelligent automation |
| 259 | +- [Plugin Development](/docs/guides/plugin-development) — Build custom plugins |
| 260 | +- [Quick Start](/docs/getting-started/quick-start) — Build your first ObjectStack app |
0 commit comments