Skip to content

Commit 117cc38

Browse files
hotlonghotlong
authored
Merge pull request #1043 from objectstack-ai/copilot/create-skills-folder-and-skill-md-again
2 parents 2640588 + b17393d commit 117cc38

12 files changed

Lines changed: 2144 additions & 0 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
1515
absent, fixing the CI `@objectstack/client#test` failure.
1616

1717
### Added
18+
- **Agent Skills — `skills/` directory (agentskills.io)** — Created `skills/` folder at
19+
repository root following the [agentskills.io specification](https://agentskills.io/specification).
20+
Five expert-knowledge skills with hand-written `SKILL.md` files and `references/` quick-lookup
21+
tables:
22+
- `skills/schema-design/` — Data schema design (Object, Field, Validation, Index)
23+
- `skills/ui-design/` — UI protocol (View, App, Dashboard, Report, Action)
24+
- `skills/automation-design/` — Automation (Flow, Workflow, Trigger, Approval)
25+
- `skills/ai-agent-design/` — AI Agent protocol (Agent, Skill, RAG, Tool)
26+
- `skills/api-design/` — API protocol (REST endpoints, Discovery, Datasource)
27+
Each `SKILL.md` includes YAML frontmatter (`name`, `description`, `license`, `metadata`),
28+
domain rules, usage guidance, best practices, common pitfalls, and code examples.
29+
Zod schema files remain the single source of truth; skills reference them for validation.
1830
- **Discovery Schema — `ServiceStatus` enum & `handlerReady` field** — Added `'registered'`
1931
status to `ServiceInfoSchema` to distinguish routes that are declared in the dispatcher
2032
table but whose HTTP handler has not been verified. Added optional `handlerReady` boolean

‎ROADMAP.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -968,6 +968,27 @@ Final polish and advanced features.
968968

969969
---
970970

971+
## Agent Skills Ecosystem (agentskills.io)
972+
973+
The `skills/` directory at repository root follows the [agentskills.io specification](https://agentskills.io/specification)
974+
to expose ObjectStack protocol expertise as discoverable Agent Skills. Each skill contains a
975+
hand-written `SKILL.md` with YAML frontmatter and an optional `references/` directory for
976+
quick-lookup tables derived from Zod schemas.
977+
978+
| Skill | Directory | Domain |
979+
|:---|:---|:---|
980+
| Schema Design | [`skills/schema-design/`](skills/schema-design/SKILL.md) | Object, Field, Validation, Index |
981+
| UI Design | [`skills/ui-design/`](skills/ui-design/SKILL.md) | View, App, Dashboard, Report, Action |
982+
| Automation Design | [`skills/automation-design/`](skills/automation-design/SKILL.md) | Flow, Workflow, Trigger, Approval |
983+
| AI Agent Design | [`skills/ai-agent-design/`](skills/ai-agent-design/SKILL.md) | Agent, Skill, RAG, Tool, Model |
984+
| API Design | [`skills/api-design/`](skills/api-design/SKILL.md) | REST endpoints, Discovery, Datasource |
985+
986+
> **Note:** Zod schema files in `packages/spec/src/` remain the single source of truth.
987+
> Skills are non-generated, human-curated expert knowledge documents. They are **not** published
988+
> as npm packages and do not require a build step.
989+
990+
---
991+
971992
## Related Documents
972993

973994
| Document | Description |

‎skills/ai-agent-design/SKILL.md‎

Lines changed: 351 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,351 @@
1+
---
2+
name: ai-agent-design
3+
description: >
4+
Design ObjectStack AI agents, skills, tools, and RAG pipelines.
5+
Use when configuring autonomous agents, defining agent skills and tool sets,
6+
setting up retrieval-augmented generation, or integrating LLM models
7+
in an ObjectStack project.
8+
license: Apache-2.0
9+
compatibility: Requires @objectstack/spec Zod schemas (v4+)
10+
metadata:
11+
author: objectstack-ai
12+
version: "1.0"
13+
domain: ai
14+
tags: agent, skill, tool, rag, llm
15+
---
16+
17+
# AI Agent Design — ObjectStack AI Protocol
18+
19+
Expert instructions for designing AI-powered agents, skills, tools, and RAG
20+
pipelines using the ObjectStack specification. This skill covers the
21+
Agent → Skill → Tool three-tier architecture aligned with Salesforce
22+
Agentforce, Microsoft Copilot Studio, and ServiceNow Now Assist patterns.
23+
24+
---
25+
26+
## When to Use This Skill
27+
28+
- You are creating an **AI agent** with a specific role and capabilities.
29+
- You need to define **skills** — bundles of related tools an agent can use.
30+
- You are configuring **tools** for data queries, actions, or integrations.
31+
- You want to set up a **RAG pipeline** for knowledge retrieval.
32+
- You are choosing and configuring **LLM models** for your agent.
33+
34+
---
35+
36+
## Three-Tier Architecture
37+
38+
```
39+
Agent → Skill → Tool
40+
│ │ │
41+
│ │ └─ Atomic operation (query, action, flow, API call)
42+
│ └─ Capability bundle with instructions & trigger phrases
43+
└─ Autonomous actor with role, instructions, and guardrails
44+
```
45+
46+
### Why Three Tiers?
47+
48+
| Tier | Analogy | Reuse Level |
49+
|:-----|:--------|:------------|
50+
| **Agent** | Job role (e.g., "Help Desk Agent") | Per use-case |
51+
| **Skill** | Competency (e.g., "Case Management") | Across agents |
52+
| **Tool** | Specific operation (e.g., "create_record") | Across skills |
53+
54+
> **Best practice:** Always model via Skills first. Direct tool assignment to
55+
> agents is supported but considered legacy. Skills provide better
56+
> discoverability, instruction scoping, and reuse.
57+
58+
---
59+
60+
## Agent Configuration
61+
62+
### Required Properties
63+
64+
| Property | Type | Description |
65+
|:---------|:-----|:------------|
66+
| `name` | `snake_case` | Unique agent identifier |
67+
| `label` | string | Human-readable name |
68+
| `role` | string | Agent's persona/role description |
69+
| `instructions` | string | System prompt — detailed behavioural guidance |
70+
71+
### Important Optional Properties
72+
73+
| Property | Purpose |
74+
|:---------|:--------|
75+
| `skills` | Array of skill names — **primary capability model** |
76+
| `tools` | Direct tool references — legacy fallback |
77+
| `model` | LLM model configuration |
78+
| `knowledge` | RAG knowledge sources |
79+
| `guardrails` | Safety constraints and topic restrictions |
80+
| `structuredOutput` | Output format (JSON schema, regex, etc.) |
81+
| `temperature` | LLM creativity level (0.0–2.0) |
82+
| `maxTokens` | Response token limit |
83+
| `active` | Enable/disable the agent |
84+
85+
### Agent Example
86+
87+
```typescript
88+
import { defineAgent } from '@objectstack/spec';
89+
90+
export default defineAgent({
91+
name: 'support_tier_1',
92+
label: 'First Line Support',
93+
role: 'Help Desk Assistant for customer support cases',
94+
instructions: `
95+
You are a friendly and professional help desk assistant.
96+
97+
RULES:
98+
- Always greet the customer by name if available.
99+
- Search the knowledge base before creating a new case.
100+
- Escalate to a human agent if the issue is critical or security-related.
101+
- Never share internal system details with customers.
102+
- Respond in the customer's preferred language.
103+
`,
104+
skills: ['case_management', 'knowledge_search'],
105+
model: {
106+
provider: 'openai',
107+
model: 'gpt-4o',
108+
temperature: 0.3,
109+
},
110+
guardrails: {
111+
blockedTopics: ['internal_pricing', 'employee_data'],
112+
maxTurns: 20,
113+
requireApprovalFor: ['delete_record', 'escalate'],
114+
},
115+
});
116+
```
117+
118+
---
119+
120+
## Skill Configuration
121+
122+
A **Skill** is a named bundle of tools with dedicated instructions and
123+
trigger conditions.
124+
125+
### Required Properties
126+
127+
| Property | Type | Description |
128+
|:---------|:-----|:------------|
129+
| `name` | `snake_case` | Unique skill identifier (`/^[a-z_][a-z0-9_]*$/`) |
130+
| `label` | string | Human-readable name |
131+
| `tools` | `string[]` | Tool names this skill grants access to |
132+
| `active` | boolean | Is the skill enabled (default: `true`) |
133+
134+
### Important Optional Properties
135+
136+
| Property | Purpose |
137+
|:---------|:--------|
138+
| `description` | What the skill does — helps the agent decide when to use it |
139+
| `instructions` | LLM prompt guidance specific to this skill's context |
140+
| `triggerPhrases` | Natural language phrases that activate the skill |
141+
| `triggerConditions` | Programmatic activation rules |
142+
| `permissions` | Required permission profiles/roles |
143+
144+
### Skill Example
145+
146+
```typescript
147+
import { defineSkill } from '@objectstack/spec';
148+
149+
export default defineSkill({
150+
name: 'case_management',
151+
label: 'Case Management',
152+
description: 'Create, update, query, and escalate support cases.',
153+
instructions: `
154+
When managing cases:
155+
- Always check for duplicate cases before creating a new one.
156+
- Set priority based on customer tier: Enterprise → High, Pro → Medium, Free → Low.
157+
- Escalated cases must include a summary of actions already taken.
158+
`,
159+
tools: [
160+
'query_support_case',
161+
'create_support_case',
162+
'update_support_case',
163+
'escalate_case',
164+
],
165+
triggerPhrases: [
166+
'I need help with a case',
167+
'Create a support ticket',
168+
'What is the status of my case',
169+
'Escalate this issue',
170+
],
171+
triggerConditions: [
172+
{ field: 'object', operator: 'eq', value: 'support_case' },
173+
],
174+
permissions: ['support_agent', 'support_admin'],
175+
active: true,
176+
});
177+
```
178+
179+
### Trigger Conditions
180+
181+
| Operator | Meaning |
182+
|:---------|:--------|
183+
| `eq` | Equals |
184+
| `neq` | Not equals |
185+
| `in` | Value is in array |
186+
| `not_in` | Value is not in array |
187+
| `contains` | String contains substring |
188+
189+
---
190+
191+
## Tool Configuration
192+
193+
Tools are the atomic operations that skills expose to agents.
194+
195+
### Tool Types
196+
197+
| Type | Purpose | Example |
198+
|:-----|:--------|:--------|
199+
| `action` | Trigger a server-side action | "Close case", "Send email" |
200+
| `flow` | Launch a flow | "Reset password flow" |
201+
| `query` | Query ObjectStack records | "Get open cases for account" |
202+
| `vector_search` | Semantic search over embeddings | "Find similar articles" |
203+
204+
### Tool Definition
205+
206+
```typescript
207+
{
208+
name: 'query_support_case',
209+
type: 'query',
210+
object: 'support_case',
211+
description: 'Search support cases by any combination of filters.',
212+
parameters: {
213+
status: { type: 'string', description: 'Filter by case status' },
214+
account_id: { type: 'string', description: 'Filter by account ID' },
215+
priority: { type: 'string', enum: ['low', 'medium', 'high', 'urgent'] },
216+
},
217+
}
218+
```
219+
220+
---
221+
222+
## RAG Pipeline Configuration
223+
224+
Retrieval-Augmented Generation gives agents access to domain knowledge.
225+
226+
### RAG Pipeline Structure
227+
228+
```typescript
229+
{
230+
name: 'support_knowledge',
231+
label: 'Support Knowledge Base',
232+
sources: [
233+
{
234+
type: 'object',
235+
object: 'knowledge_article',
236+
fields: ['title', 'content', 'category'],
237+
filter: [{ field: 'published', operator: 'equals', value: true }],
238+
},
239+
{
240+
type: 'document',
241+
path: 'docs/support-handbook.md',
242+
},
243+
],
244+
indexes: [
245+
{
246+
name: 'article_embeddings',
247+
model: 'text-embedding-3-small',
248+
dimensions: 1536,
249+
distanceMetric: 'cosine',
250+
},
251+
],
252+
retrieval: {
253+
topK: 5,
254+
scoreThreshold: 0.75,
255+
reranker: 'cohere-rerank-v3',
256+
},
257+
}
258+
```
259+
260+
### RAG Best Practices
261+
262+
1. **Chunk documents appropriately.** 500–1000 tokens per chunk with 100-token
263+
overlap works well for most use cases.
264+
2. **Set a `scoreThreshold`** to filter low-relevance results. Start with `0.7`
265+
and tune.
266+
3. **Use a reranker** for better precision when the initial retrieval returns
267+
many candidates.
268+
4. **Filter by published/active status** to avoid surfacing draft or archived
269+
content.
270+
5. **Index only searchable fields** — do not index system fields or IDs.
271+
272+
---
273+
274+
## Model Configuration
275+
276+
### Supported Providers
277+
278+
| Provider | Models | Use Case |
279+
|:---------|:-------|:---------|
280+
| `openai` | GPT-4o, GPT-4o-mini, o1, o3-mini | General purpose, reasoning |
281+
| `anthropic` | Claude Sonnet 4, Claude Haiku | Long context, safety |
282+
| `azure_openai` | Same as OpenAI, enterprise managed | Compliance, data residency |
283+
| `local` | Ollama, vLLM, llama.cpp | On-premise, air-gapped |
284+
285+
### Model Selection Guidelines
286+
287+
| Scenario | Recommended |
288+
|:---------|:------------|
289+
| Complex reasoning, multi-step planning | GPT-4o / Claude Sonnet 4 |
290+
| High-volume, low-latency | GPT-4o-mini / Claude Haiku |
291+
| Sensitive data, on-premise | Local models via Ollama |
292+
| Structured data extraction | Any model + `structuredOutput` config |
293+
294+
### Temperature Guidelines
295+
296+
| Value | Use Case |
297+
|:------|:---------|
298+
| `0.0–0.3` | Factual Q&A, data extraction, code generation |
299+
| `0.3–0.7` | Conversational agents, customer support |
300+
| `0.7–1.0` | Creative writing, brainstorming |
301+
| `> 1.0` | Experimental / highly creative (use with caution) |
302+
303+
---
304+
305+
## Structured Output
306+
307+
Force the agent to respond in a specific format:
308+
309+
```typescript
310+
structuredOutput: {
311+
format: 'json_schema',
312+
schema: {
313+
type: 'object',
314+
properties: {
315+
summary: { type: 'string' },
316+
priority: { type: 'string', enum: ['low', 'medium', 'high'] },
317+
action_items: { type: 'array', items: { type: 'string' } },
318+
},
319+
required: ['summary', 'priority'],
320+
},
321+
retry: { maxAttempts: 3 },
322+
}
323+
```
324+
325+
---
326+
327+
## Common Pitfalls
328+
329+
1. **Overly broad instructions.** Agents with vague instructions hallucinate
330+
more. Be specific about what the agent should and should not do.
331+
2. **Too many tools per skill.** Keep skills focused (3–8 tools). If a skill
332+
has 15+ tools, split it.
333+
3. **Missing guardrails.** Always define `blockedTopics` and
334+
`requireApprovalFor` destructive operations.
335+
4. **Ignoring tool descriptions.** The LLM uses tool `description` to decide
336+
when to call it. Poor descriptions = wrong tool selection.
337+
5. **Not testing trigger phrases.** Ambiguous trigger phrases cause skill
338+
conflicts. Test with edge-case inputs.
339+
6. **RAG without score threshold.** Without a threshold, low-relevance
340+
passages pollute the context window and degrade responses.
341+
342+
---
343+
344+
## References
345+
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/`

0 commit comments

Comments
 (0)