Skip to content

Commit 69de6ce

Browse files
hotlonghotlong
committed
Refactor references in SKILL.md files across multiple skills to improve discoverability and self-containment. Added new reference files for RAG Pipeline, Auth & Realtime, Workflow Actions, Object Schema, and Dashboard & Chart. Introduced Skill Optimizer for auditing and fixing SKILL.md files. Updated documentation to ensure bundled assets are properly linked and descriptions are keyword-rich for better agent loading.
1 parent 6f15b86 commit 69de6ce

File tree

17 files changed

+835
-34
lines changed

17 files changed

+835
-34
lines changed

‎skills/objectstack-ai/SKILL.md‎

Lines changed: 4 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -343,9 +343,7 @@ structuredOutput: {
343343

344344
## References
345345

346-
- Zod source: `packages/spec/src/ai/agent.zod.ts`
347-
- Zod source: `packages/spec/src/ai/skill.zod.ts`
348-
- Zod source: `packages/spec/src/ai/tool.zod.ts`
349-
- Zod source: `packages/spec/src/ai/rag-pipeline.zod.ts`
350-
- Zod source: `packages/spec/src/ai/model-registry.zod.ts`
351-
- Documentation: `content/docs/references/ai/`
346+
- **[Agent & Skill Reference](./references/agent-skill-reference.md)** — Agent, Skill, Tool schemas, LLM providers, trigger conditions
347+
- **[RAG Pipeline Reference](./references/rag-pipeline-reference.md)** — Vector stores, chunking strategies, retrieval config, embedding models
348+
349+
> **Monorepo source** (for contributors): `packages/spec/src/ai/agent.zod.ts`, `skill.zod.ts`, `tool.zod.ts`, `rag-pipeline.zod.ts`, `model-registry.zod.ts`

‎skills/objectstack-ai/references/agent-skill-reference.md‎

Lines changed: 28 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# AI Agent Design — Skill & Tool Reference
22

33
> Auto-derived from `packages/spec/src/ai/agent.zod.ts`, `skill.zod.ts`, and related schemas.
4-
> This file is for quick reference only. The Zod source is the single source of truth.
4+
> This file is bundled with the skill for offline/external use.
55
66
## Agent Schema Properties
77

@@ -82,3 +82,30 @@
8282
| `retrieval.topK` | Number of results to retrieve |
8383
| `retrieval.scoreThreshold` | Minimum relevance score |
8484
| `retrieval.reranker` | Re-ranking model |
85+
86+
## Tool Category Enum
87+
88+
| Category | Description |
89+
|:---------|:------------|
90+
| `data` | CRUD operations on ObjectStack records |
91+
| `action` | Server-side business logic |
92+
| `flow` | Launch an automation flow |
93+
| `integration` | External API connectors |
94+
| `vector_search` | Semantic / similarity search |
95+
| `analytics` | Reporting and aggregation |
96+
| `utility` | Helper tools (formatting, validation) |
97+
98+
## Tool Schema — Full Properties
99+
100+
| Property | Required | Description |
101+
|:---------|:---------|:------------|
102+
| `name` | ✅ | Unique identifier (snake_case) |
103+
| `label` | ✅ | Human-readable name |
104+
| `description` | ✅ | What the tool does (shown to LLM) |
105+
| `category` | ✅ | Tool category (see enum above) |
106+
| `parameters` | — | JSON Schema for input parameters |
107+
| `outputSchema` | — | JSON Schema for output |
108+
| `objectName` | — | Target object (for data tools) |
109+
| `requiresConfirmation` | — | User must approve before execution |
110+
| `permissions` | — | Required roles |
111+
| `active` | — | Enable/disable |

‎skills/objectstack-ai/references/rag-pipeline-reference.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# AI Agent Design — RAG Pipeline Reference
2+
3+
> Auto-derived from `packages/spec/src/ai/rag-pipeline.zod.ts` and `model-registry.zod.ts`.
4+
> This file is bundled with the skill for offline/external use.
5+
6+
## Vector Store Providers
7+
8+
| Provider | Description |
9+
|:---------|:------------|
10+
| `pinecone` | Managed vector database |
11+
| `weaviate` | Open-source vector search |
12+
| `qdrant` | Rust-based vector engine |
13+
| `milvus` | Scalable similarity search |
14+
| `chroma` | Lightweight embedding DB |
15+
| `pgvector` | PostgreSQL extension |
16+
| `redis` | Redis vector search |
17+
| `opensearch` | AWS OpenSearch |
18+
| `elasticsearch` | Elastic vector search |
19+
| `custom` | Custom implementation |
20+
21+
## Chunking Strategies (Discriminated Union)
22+
23+
| Strategy | Key Config | Use Case |
24+
|:---------|:-----------|:---------|
25+
| `fixed` | `chunkSize`, `chunkOverlap` | Simple, predictable splitting |
26+
| `semantic` | `model`, `threshold` | Split by semantic boundaries |
27+
| `recursive` | `separators`, `chunkSize` | Hierarchical splitting (most common) |
28+
| `markdown` | `headingLevel` | Markdown-aware splitting |
29+
30+
## Retrieval Strategies (Discriminated Union)
31+
32+
| Strategy | Key Config | Use Case |
33+
|:---------|:-----------|:---------|
34+
| `similarity` | `topK`, `scoreThreshold` | Standard nearest-neighbor |
35+
| `mmr` | `topK`, `diversityWeight` | Maximal Marginal Relevance (reduce redundancy) |
36+
| `hybrid` | `textWeight`, `vectorWeight` | Combine keyword + vector search |
37+
| `parent_document` | `childChunkSize` | Retrieve parent doc from child match |
38+
39+
## Embedding Model Config
40+
41+
| Property | Required | Description |
42+
|:---------|:---------|:------------|
43+
| `provider` | ✅ | Model provider (e.g., `openai`, `local`) |
44+
| `model` | ✅ | Model name (e.g., `text-embedding-3-small`) |
45+
| `dimensions` | ✅ | Output vector dimensions |
46+
| `maxTokens` | — | Max tokens per input |
47+
| `batchSize` | — | Batch processing size |
48+
| `endpoint` | — | Custom endpoint URL |
49+
| `apiKey` | — | API key (use `secretRef` instead for production) |
50+
| `secretRef` | — | Reference to secret manager |
51+
52+
## Knowledge Source Types
53+
54+
| Type | Description |
55+
|:-----|:------------|
56+
| `object` | ObjectStack records (auto-indexed) |
57+
| `document` | Uploaded files (PDF, DOCX, etc.) |
58+
| `url` | Web pages (crawled) |
59+
| `api` | External API response data |
60+
61+
## MCP (Model Context Protocol)
62+
63+
| Property | Description |
64+
|:---------|:------------|
65+
| `transport` | `stdio` (local) or `http` (remote) |
66+
| `tools` | Exposed tool definitions |
67+
| `resources` | Exposed metadata resources |
68+
| `prompts` | Exposed agent prompts |

‎skills/objectstack-api/SKILL.md‎

Lines changed: 4 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -319,9 +319,7 @@ const aiService = kernel.resolve<AIService>('ai');
319319

320320
## References
321321

322-
- Zod source: `packages/spec/src/api/plugin-rest-api.zod.ts`
323-
- Zod source: `packages/spec/src/api/discovery.zod.ts`
324-
- Zod source: `packages/spec/src/data/datasource.zod.ts`
325-
- Zod source: `packages/spec/src/system/http-server.zod.ts`
326-
- Zod source: `packages/spec/src/contracts/`
327-
- Documentation: `content/docs/references/api/`
322+
- **[Endpoint & Method Reference](./references/endpoint-reference.md)** — API methods, HTTP verbs, error codes, security layers, drivers
323+
- **[Auth & Realtime Reference](./references/auth-realtime-reference.md)** — Auth providers, login types, realtime transport, session schema
324+
325+
> **Monorepo source** (for contributors): `packages/spec/src/api/plugin-rest-api.zod.ts`, `discovery.zod.ts`, `realtime.zod.ts`, `auth.zod.ts`

‎skills/objectstack-api/references/auth-realtime-reference.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# API Design — Auth & Realtime Reference
2+
3+
> Auto-derived from `packages/spec/src/api/auth.zod.ts`, `realtime.zod.ts`, and related schemas.
4+
> This file is bundled with the skill for offline/external use.
5+
6+
## Auth Providers
7+
8+
| Provider | Description |
9+
|:---------|:------------|
10+
| `local` | Email/password (built-in) |
11+
| `google` | Google OAuth 2.0 |
12+
| `github` | GitHub OAuth |
13+
| `microsoft` | Microsoft Entra ID |
14+
| `ldap` | LDAP/Active Directory |
15+
| `saml` | SAML 2.0 SSO |
16+
17+
## Login Types
18+
19+
| Type | Description |
20+
|:-----|:------------|
21+
| `email` | Email + password |
22+
| `username` | Username + password |
23+
| `phone` | Phone + OTP |
24+
| `magic-link` | Passwordless email link |
25+
| `social` | OAuth social login |
26+
27+
## Session User Schema
28+
29+
| Property | Type | Description |
30+
|:---------|:-----|:------------|
31+
| `id` | string | User identifier |
32+
| `email` | string | User email |
33+
| `emailVerified` | boolean | Email verification status |
34+
| `name` | string | Display name |
35+
| `image` | string | Avatar URL |
36+
| `username` | string | Username |
37+
| `roles` | string[] | Assigned roles |
38+
| `tenantId` | string | Current tenant |
39+
| `language` | string | Preferred language |
40+
| `timezone` | string | User timezone |
41+
42+
## Realtime Transport Protocols
43+
44+
| Protocol | Description |
45+
|:---------|:------------|
46+
| `websocket` | Full-duplex WebSocket connection |
47+
| `sse` | Server-Sent Events (one-way) |
48+
| `polling` | Long-polling fallback |
49+
50+
## Realtime Event Types
51+
52+
| Event | Description |
53+
|:------|:------------|
54+
| `record.created` | New record inserted |
55+
| `record.updated` | Record modified |
56+
| `record.deleted` | Record removed |
57+
| `field.changed` | Specific field value changed |
58+
59+
## Subscription Schema
60+
61+
| Property | Type | Description |
62+
|:---------|:-----|:------------|
63+
| `id` | UUID | Subscription identifier |
64+
| `events` | string[] | Event types to subscribe to |
65+
| `transport` | enum | Transport protocol |
66+
| `channel` | string | Channel name |
67+
68+
## Rate Limit Config
69+
70+
| Property | Type | Description |
71+
|:---------|:-----|:------------|
72+
| `maxRequests` | number | Max requests per window |
73+
| `windowMs` | number | Window duration in milliseconds |
74+
75+
## API Endpoint Schema
76+
77+
| Property | Required | Description |
78+
|:---------|:---------|:------------|
79+
| `name` | ✅ | Unique identifier (snake_case) |
80+
| `path` | ✅ | URL path pattern |
81+
| `method` | ✅ | HTTP method (GET/POST/PUT/PATCH/DELETE) |
82+
| `type` | ✅ | `flow`, `script`, `object_operation`, or `proxy` |
83+
| `target` | — | Target flow/script/object |
84+
| `inputMapping` | — | Request → handler input mapping |
85+
| `outputMapping` | — | Handler output → response mapping |
86+
| `authRequired` | — | Require authentication (default: true) |
87+
| `rateLimit` | — | Rate limit config |
88+
| `cacheTtl` | — | Response cache TTL in seconds |

‎skills/objectstack-api/references/endpoint-reference.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# API Design — Endpoint & Method Reference
22

33
> Auto-derived from `packages/spec/src/api/plugin-rest-api.zod.ts` and related schemas.
4-
> This file is for quick reference only. The Zod source is the single source of truth.
4+
> This file is bundled with the skill for offline/external use.
55
66
## API Methods (Object Operations)
77

‎skills/objectstack-automation/SKILL.md‎

Lines changed: 4 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -322,9 +322,7 @@ Triggers fire automatically when data events occur.
322322

323323
## References
324324

325-
- Zod source: `packages/spec/src/automation/flow.zod.ts`
326-
- Zod source: `packages/spec/src/automation/workflow.zod.ts`
327-
- Zod source: `packages/spec/src/automation/trigger-registry.zod.ts`
328-
- Zod source: `packages/spec/src/automation/approval.zod.ts`
329-
- Zod source: `packages/spec/src/automation/state-machine.zod.ts`
330-
- Documentation: `content/docs/references/automation/`
325+
- **[Node & Event Reference](./references/node-types.md)** — Flow types, 18 node types, trigger events, state machine config
326+
- **[Workflow Actions Reference](./references/workflow-actions.md)** — Approval process, field updates, email alerts, connector actions
327+
328+
> **Monorepo source** (for contributors): `packages/spec/src/automation/flow.zod.ts`, `workflow.zod.ts`, `trigger-registry.zod.ts`, `approval.zod.ts`

‎skills/objectstack-automation/references/node-types.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# Automation Design — Node & Event Reference
22

33
> Auto-derived from `packages/spec/src/automation/flow.zod.ts` and related schemas.
4-
> This file is for quick reference only. The Zod source is the single source of truth.
4+
> This file is bundled with the skill for offline/external use.
55
66
## Flow Types
77

‎skills/objectstack-automation/references/workflow-actions.md‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
# Automation Design — Workflow Actions Reference
2+
3+
> Auto-derived from `packages/spec/src/automation/workflow.zod.ts`, `approval.zod.ts`, and related schemas.
4+
> This file is bundled with the skill for offline/external use.
5+
6+
## Workflow Action Types
7+
8+
| Type | Key Properties | Description |
9+
|:-----|:---------------|:------------|
10+
| `field_update` | `field`, `value` | Set a field to a formula-capable value |
11+
| `email_alert` | `template`, `recipients[]` | Send email notification |
12+
| `connector_action` | `connectorId`, `actionId`, `input{}` | Invoke pre-built integration |
13+
| `http_call` | `url`, `method`, `headers`, `body` | Call external HTTP API |
14+
15+
## Workflow Trigger Types
16+
17+
| Trigger | Description |
18+
|:--------|:------------|
19+
| `on_create` | Fires when a record is created |
20+
| `on_update` | Fires when a record is updated |
21+
| `on_create_or_update` | Fires on create or update |
22+
| `on_delete` | Fires when a record is deleted |
23+
| `schedule` | Fires on a cron schedule |
24+
25+
## Approval Process Properties
26+
27+
| Property | Required | Description |
28+
|:---------|:---------|:------------|
29+
| `name` | ✅ | Unique identifier (snake_case) |
30+
| `object` | ✅ | Target object name |
31+
| `entryCondition` | ✅ | Formula — when to start approval |
32+
| `steps` | ✅ | Ordered approval steps |
33+
| `onApproved` | — | Actions when fully approved |
34+
| `onRejected` | — | Actions when rejected |
35+
| `onRecalled` | — | Actions when recalled by submitter |
36+
37+
## Approval Step Properties
38+
39+
| Property | Description |
40+
|:---------|:------------|
41+
| `assignTo.type` | `field` (record field), `role`, or `user` |
42+
| `assignTo.value` | Field name, role name, or user ID |
43+
| `unanimousRequired` | All assignees must approve (default: false) |
44+
| `escalation.timeout` | Time before escalation (e.g., `"48h"`) |
45+
| `escalation.action` | `approve`, `reject`, or `reassign` |
46+
47+
## Flow Variable Schema
48+
49+
| Property | Required | Description |
50+
|:---------|:---------|:------------|
51+
| `name` | ✅ | Variable name (snake_case) |
52+
| `type` | ✅ | `text`, `number`, `boolean`, `object`, `list` |
53+
| `isInput` | — | Exposed as flow input parameter |
54+
| `isOutput` | — | Exposed as flow output value |
55+
56+
## Flow Node Config (by type)
57+
58+
| Node Type | Key Config Properties |
59+
|:----------|:---------------------|
60+
| `decision` | `conditions[]` with `expression` and `targetNodeId` |
61+
| `assignment` | `assignments[]` with `variable`, `operator`, `value` |
62+
| `create_record` | `object`, `fieldValues{}` |
63+
| `update_record` | `object`, `filters`, `fieldValues{}` |
64+
| `delete_record` | `object`, `filters` |
65+
| `query_record` | `object`, `filters`, `sortBy`, `limit` |
66+
| `http_request` | `url`, `method`, `headers`, `body`, `outputVariable` |
67+
| `script` | `code` (JS/TS), `inputVariables`, `outputVariables` |
68+
| `screen` | `components[]` (form fields, buttons) |
69+
| `loop` | `collection`, `iterationVariable` |
70+
| `wait` | `waitEventConfig` with `type` and `condition` |
71+
| `subflow` | `flowName`, `inputAssignments`, `outputAssignments` |
72+
73+
## State Machine Properties
74+
75+
| Property | Required | Description |
76+
|:---------|:---------|:------------|
77+
| `field` | ✅ | State field name (e.g., `status`) |
78+
| `states` | ✅ | Map of state name → `{ initial?, final? }` |
79+
| `transitions` | ✅ | Array of `{ from, to, trigger?, guard?, actions? }` |
80+
81+
## ETL Pipeline Properties
82+
83+
| Property | Description |
84+
|:---------|:------------|
85+
| `source` | Input data source config |
86+
| `transforms` | Array of transformation steps |
87+
| `destination` | Output target config |
88+
| `schedule` | Cron expression for recurring runs |
89+
| `errorHandling` | `skip`, `abort`, or `retry` |

‎skills/objectstack-schema/SKILL.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -352,7 +352,7 @@ export default ObjectSchema.create({
352352

353353
## References
354354

355-
- Zod source: `packages/spec/src/data/field.zod.ts`
356-
- Zod source: `packages/spec/src/data/object.zod.ts`
357-
- Zod source: `packages/spec/src/data/validation.zod.ts`
358-
- Documentation: `content/docs/references/data/`
355+
- **[Field Type Reference](./references/field-types.md)** — All 48 field types, validation rules, and index types
356+
- **[Object Schema Reference](./references/object-schema.md)** — Object properties, capabilities, extension model, and naming conventions
357+
358+
> **Monorepo source** (for contributors): `packages/spec/src/data/field.zod.ts`, `object.zod.ts`, `validation.zod.ts`

0 commit comments

Comments
 (0)