Skip to content

Commit 0762205

Browse files
veithlyveithly
committed
docs: add Skills documentation with Core Concepts and How-To Guide
- Add core-concepts/skills.md: SKILL.md specification, trigger system, script execution, and security considerations - Add how-to-guides/build-skill-agents.md: step-by-step tutorial, vibe coding workflow, Web3 skills usage, and API examples - Update vibe-coding.md: add Method 5 for skill-based vibe coding - Update sidebars.ts: add new skill pages to navigation
1 parent 6a8d858 commit 0762205

File tree

4 files changed

+873
-0
lines changed

4 files changed

+873
-0
lines changed

‎docs/core-concepts/skills.md‎

Lines changed: 365 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,365 @@
1+
# Skills
2+
3+
Skills are modular, reusable AI capabilities that can be dynamically activated to enhance your agents. They provide a powerful way to organize prompts, tools, and scripts into portable packages.
4+
5+
:::tip Web3 Skills Collection
6+
Production-ready Web3 skills for cryptocurrency research, DeFi analysis, and blockchain development are available at **[spoon-awesome-skill](https://github.com/XSpoonAi/spoon-awesome-skill)**. Clone and customize them for your projects!
7+
:::
8+
9+
## Overview
10+
11+
A skill is a self-contained module defined by a `SKILL.md` file. Each skill encapsulates:
12+
13+
| Component | Description |
14+
|-----------|-------------|
15+
| **Metadata** | Name, description, version, tags, and triggers |
16+
| **Instructions** | Markdown prompts injected into the agent's context |
17+
| **Scripts** | Executable Python/Shell scripts exposed as tools |
18+
| **Triggers** | Keywords, patterns, or intents for auto-activation |
19+
20+
## Design Philosophy
21+
22+
### Portability
23+
24+
Skills are self-contained folders that can be shared by simply copying directories:
25+
26+
```
27+
skills/
28+
└── defi/
29+
├── SKILL.md # Metadata + instructions
30+
└── scripts/
31+
└── uniswap_quote.py
32+
```
33+
34+
No external dependencies or complex setup required—just copy and use.
35+
36+
### Dynamic Activation
37+
38+
Skills support multiple activation modes:
39+
40+
| Mode | Description | Example |
41+
|------|-------------|---------|
42+
| **Manual** | Explicitly activated via code | `await agent.activate_skill("defi")` |
43+
| **Auto-triggered** | Activated based on user input patterns | User says "swap ETH" → triggers `defi` skill |
44+
| **Composed** | Skills that require or include other skills | `advanced-trading` includes `defi` |
45+
46+
### Vibe Coding Experience
47+
48+
Skills enable a **"vibe coding"** workflow where you:
49+
50+
1. **Copy** existing skills from [spoon-awesome-skill](https://github.com/XSpoonAi/spoon-awesome-skill)
51+
2. **Customize** the SKILL.md prompts for your use case
52+
3. **Enable scripts** and let the AI figure out how to use them
53+
4. **Ship** without writing complex agent logic
54+
55+
## SKILL.md Specification
56+
57+
The `SKILL.md` file is the heart of every skill. It uses YAML frontmatter for metadata followed by Markdown instructions.
58+
59+
### Complete Schema
60+
61+
```yaml
62+
---
63+
# ===== Required Fields =====
64+
name: skill-name # Unique identifier (lowercase, hyphens)
65+
description: What the skill does # Human-readable description
66+
67+
# ===== Optional Metadata =====
68+
version: 1.0.0 # Semantic version
69+
author: Your Name # Skill author
70+
tags: # Categorization tags
71+
- research
72+
- web3
73+
- defi
74+
75+
# ===== Trigger Configuration =====
76+
triggers:
77+
- type: keyword # Trigger type: keyword | pattern | intent
78+
keywords: # Words that activate the skill
79+
- research
80+
- analyze
81+
- investigate
82+
priority: 80 # 0-100, higher = more likely to activate
83+
84+
- type: pattern # Regex-based triggers
85+
patterns:
86+
- "(?i)analyze.*data"
87+
- "(?i)research.*topic"
88+
priority: 70
89+
90+
- type: intent # LLM-classified intent triggers
91+
intent_category: research
92+
priority: 90
93+
94+
# ===== Parameters =====
95+
parameters: # Input parameters the skill accepts
96+
- name: topic
97+
type: string # string | integer | boolean | float
98+
required: true
99+
default: null
100+
description: Research topic
101+
102+
# ===== Script Configuration =====
103+
scripts:
104+
enabled: true # Enable/disable all scripts for this skill
105+
working_directory: ./scripts # Base directory for script files
106+
107+
definitions:
108+
- name: web_search # Script identifier
109+
description: Search the web # Tool description shown to agent
110+
type: python # python | shell | bash
111+
file: search.py # Relative to working_directory
112+
timeout: 30 # Execution timeout in seconds
113+
run_on_activation: false # Auto-run when skill activates
114+
run_on_deactivation: false # Auto-run when skill deactivates
115+
working_directory: ./custom # Override skill-level working_directory
116+
117+
- name: inline_script
118+
type: bash
119+
inline: | # Inline script (alternative to file)
120+
echo "Hello from inline script"
121+
timeout: 10
122+
---
123+
124+
# Skill Instructions
125+
126+
Your prompt content here. This Markdown content is injected into
127+
the agent's system prompt when the skill is activated.
128+
129+
## Capabilities
130+
- List what the agent can do with this skill
131+
132+
## Guidelines
133+
1. Behavioral instructions for the agent
134+
2. How to use the available tools
135+
3. Output format expectations
136+
```
137+
138+
### Field Reference
139+
140+
#### Core Fields
141+
142+
| Field | Type | Required | Description |
143+
|-------|------|----------|-------------|
144+
| `name` | string | ✓ | Unique skill identifier. Use lowercase with hyphens. |
145+
| `description` | string | ✓ | Human-readable description of the skill's purpose. |
146+
| `version` | string | | Semantic version (e.g., `1.0.0`). |
147+
| `author` | string | | Skill author name or organization. |
148+
| `tags` | string[] | | Categorization tags for discovery and filtering. |
149+
150+
#### Trigger Fields
151+
152+
| Field | Type | Description |
153+
|-------|------|-------------|
154+
| `triggers[].type` | enum | `keyword`, `pattern`, or `intent` |
155+
| `triggers[].keywords` | string[] | Words that trigger activation (for `keyword` type) |
156+
| `triggers[].patterns` | string[] | Regex patterns (for `pattern` type) |
157+
| `triggers[].intent_category` | string | Intent label (for `intent` type) |
158+
| `triggers[].priority` | number | 0-100 priority score. Higher values take precedence. |
159+
160+
#### Parameter Fields
161+
162+
| Field | Type | Description |
163+
|-------|------|-------------|
164+
| `parameters[].name` | string | Parameter identifier |
165+
| `parameters[].type` | enum | `string`, `integer`, `boolean`, or `float` |
166+
| `parameters[].required` | boolean | Whether the parameter is required |
167+
| `parameters[].default` | any | Default value if not provided |
168+
| `parameters[].description` | string | Human-readable description |
169+
170+
#### Script Fields
171+
172+
| Field | Type | Default | Description |
173+
|-------|------|---------|-------------|
174+
| `scripts.enabled` | boolean | `true` | Master switch for all scripts in this skill |
175+
| `scripts.working_directory` | string | `./scripts` | Base directory for script files |
176+
| `scripts.definitions[].name` | string | | Script identifier (exposed as tool name) |
177+
| `scripts.definitions[].description` | string | | Tool description shown to the agent |
178+
| `scripts.definitions[].type` | enum | `python` | `python`, `shell`, or `bash` |
179+
| `scripts.definitions[].file` | string | | Script file path (relative to working_directory) |
180+
| `scripts.definitions[].inline` | string | | Inline script content (alternative to file) |
181+
| `scripts.definitions[].timeout` | number | `30` | Execution timeout in seconds |
182+
| `scripts.definitions[].working_directory` | string | | Override skill-level working_directory |
183+
| `scripts.definitions[].run_on_activation` | boolean | `false` | Auto-run when skill activates |
184+
| `scripts.definitions[].run_on_deactivation` | boolean | `false` | Auto-run when skill deactivates |
185+
186+
## Trigger System
187+
188+
Triggers determine when a skill should be automatically activated based on user input.
189+
190+
### Keyword Triggers
191+
192+
Match specific words in user input:
193+
194+
```yaml
195+
triggers:
196+
- type: keyword
197+
keywords:
198+
- uniswap
199+
- swap
200+
- defi
201+
priority: 80
202+
```
203+
204+
**Matching behavior**: Case-insensitive word boundary matching. "I want to swap tokens" matches `swap`.
205+
206+
### Pattern Triggers
207+
208+
Use regular expressions for complex matching:
209+
210+
```yaml
211+
triggers:
212+
- type: pattern
213+
patterns:
214+
- "(?i)swap.*for.*" # "swap ETH for USDC"
215+
- "(?i)liquidity.*pool" # "add liquidity to pool"
216+
priority: 70
217+
```
218+
219+
**Matching behavior**: Full regex support with flags (e.g., `(?i)` for case-insensitive).
220+
221+
### Intent Triggers
222+
223+
Use LLM classification for semantic matching:
224+
225+
```yaml
226+
triggers:
227+
- type: intent
228+
intent_category: defi_trading
229+
priority: 90
230+
```
231+
232+
**Matching behavior**: The agent's LLM classifies user intent and matches against the category.
233+
234+
### Priority Resolution
235+
236+
When multiple skills match, priority determines activation order:
237+
238+
1. Higher priority values win (0-100 scale)
239+
2. Equal priorities: first match wins
240+
3. `max_auto_skills` limits concurrent auto-activated skills
241+
242+
## Script Execution
243+
244+
Scripts are executable files that become agent tools when a skill is activated.
245+
246+
### Script Types
247+
248+
| Type | Interpreter | Use Case |
249+
|------|-------------|----------|
250+
| `python` | Python 3 | Complex logic, API calls, data processing |
251+
| `shell` | System shell | Simple commands, file operations |
252+
| `bash` | Bash | Bash-specific features, scripting |
253+
254+
### Input/Output Protocol
255+
256+
Scripts receive input via **stdin** and return output via **stdout**:
257+
258+
```python
259+
#!/usr/bin/env python3
260+
import sys
261+
import json
262+
263+
def main():
264+
# Read input from stdin
265+
input_data = sys.stdin.read().strip()
266+
267+
# Parse JSON input (optional)
268+
try:
269+
params = json.loads(input_data)
270+
except json.JSONDecodeError:
271+
params = {"query": input_data}
272+
273+
# Process and return result
274+
result = {"status": "success", "data": process(params)}
275+
276+
# Output JSON to stdout
277+
print(json.dumps(result, indent=2))
278+
279+
if __name__ == "__main__":
280+
main()
281+
```
282+
283+
### Lifecycle Scripts
284+
285+
Scripts can run automatically during skill lifecycle:
286+
287+
```yaml
288+
scripts:
289+
definitions:
290+
- name: setup
291+
type: python
292+
file: setup.py
293+
run_on_activation: true # Runs when skill activates
294+
295+
- name: cleanup
296+
type: bash
297+
inline: "rm -rf /tmp/cache_*"
298+
run_on_deactivation: true # Runs when skill deactivates
299+
```
300+
301+
## MCP vs Skills
302+
303+
SpoonOS supports both MCP-based and skill-based agents:
304+
305+
| Feature | MCP Tools | Skills |
306+
|---------|-----------|--------|
307+
| Tool source | External MCP servers | SKILL.md scripts |
308+
| Prompts | Manual configuration | Auto-injected from SKILL.md |
309+
| Auto-activation | No | Yes (via triggers) |
310+
| Portability | Requires MCP server setup | Copy folder |
311+
| Best for | External services (databases, APIs) | Self-contained capabilities |
312+
313+
**Choose MCP** when integrating external services that have MCP servers.
314+
315+
**Choose Skills** for portable, self-contained AI capabilities with custom prompts.
316+
317+
## Security Considerations
318+
319+
### Script Execution Risks
320+
321+
- Scripts run with your Python process permissions
322+
- No sandboxing by default—scripts have full system access
323+
- Input from the agent is passed directly to scripts
324+
325+
### Mitigation Strategies
326+
327+
1. **Disable scripts in production** if not needed:
328+
```python
329+
agent = SpoonReactSkill(scripts_enabled=False)
330+
```
331+
332+
2. **Validate inputs** in your scripts:
333+
```python
334+
def validate_input(data):
335+
if not isinstance(data, dict):
336+
raise ValueError("Invalid input format")
337+
# Additional validation...
338+
```
339+
340+
3. **Review third-party skills** before using them
341+
342+
4. **Use per-skill disable** for untrusted skills:
343+
```yaml
344+
scripts:
345+
enabled: false # Disable scripts for this skill
346+
```
347+
348+
## Web3 Skills Collection
349+
350+
The [spoon-awesome-skill](https://github.com/XSpoonAi/spoon-awesome-skill) repository provides production-ready skills:
351+
352+
| Skill | Description |
353+
|-------|-------------|
354+
| **defi** | DeFi protocol interactions (Uniswap, Aave, Compound) |
355+
| **onchain-analysis** | On-chain data analysis (Etherscan, gas tracking) |
356+
| **nft** | NFT market analysis (OpenSea, rarity calculations) |
357+
| **wallet** | Wallet operations and portfolio tracking |
358+
| **solana** | Solana ecosystem (Jupiter, Raydium) |
359+
| **neo** | Neo N3 ecosystem (NeoX, NeoFS) |
360+
361+
## Next Steps
362+
363+
- **[Building Skill Agents](/docs/how-to-guides/build-skill-agents)**: Step-by-step tutorial for building skill-powered agents
364+
- **[spoon-awesome-skill](https://github.com/XSpoonAi/spoon-awesome-skill)**: Ready-to-use Web3 skills
365+
- **[Vibe Coding](/docs/how-to-guides/vibe-coding)**: Rapid prototyping workflow with skills

0 commit comments

Comments
 (0)