Skip to content

Commit 8a190b3

Browse files
AlexMikhalevAlexMikhalev
committed
docs(tinyclaw): add README and example skill files
Add comprehensive README.md for terraphim_tinyclaw: - Feature overview and installation - Skills system quick start guide - Configuration examples - Available tools documentation - Development and testing instructions Create 5 example skills in examples/skills/: - analyze-repo: Git repository analysis - research-topic: Web search and summarization - code-review: Automated code review - generate-docs: Documentation generation - security-scan: Basic security vulnerability scan Each example includes: - Complete JSON definition - Input/output documentation - Usage examples with CLI commands - Step-by-step breakdown Add examples/skills/README.md with: - Skill usage instructions - Creating custom skills guide - Variable substitution examples - Step type documentation - Storage location details
1 parent 4524d26 commit 8a190b3

7 files changed

Lines changed: 570 additions & 0 deletions

File tree

‎crates/terraphim_tinyclaw/README.md‎

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
# TinyClaw - Multi-channel AI Assistant
2+
3+
TinyClaw is a multi-channel AI assistant powered by Terraphim, supporting Telegram, Discord, CLI, and other messaging platforms.
4+
5+
## Features
6+
7+
- **Multi-Channel Support**: Interact via Telegram, Discord, CLI, or Matrix/WhatsApp (via bridge)
8+
- **Tool System**: Extensible tools for filesystem, web, shell, and code operations
9+
- **Skills System**: Create and execute reusable JSON-defined workflows
10+
- **Session Management**: Persistent conversation history
11+
- **Hybrid LLM Router**: Intelligent routing between local and cloud LLM providers
12+
13+
## Installation
14+
15+
```bash
16+
cargo install terraphim-tinyclaw
17+
```
18+
19+
## Usage
20+
21+
### CLI Mode
22+
23+
Run TinyClaw in interactive CLI mode:
24+
25+
```bash
26+
terraphim-tinyclaw agent --system-prompt /path/to/SYSTEM.md
27+
```
28+
29+
### Gateway Mode
30+
31+
Run as a gateway server with all enabled channels:
32+
33+
```bash
34+
terraphim-tinyclaw gateway
35+
```
36+
37+
## Skills System
38+
39+
Skills are JSON-defined workflows that combine tool calls, LLM prompts, and shell commands into reusable automation scripts.
40+
41+
### Quick Start
42+
43+
```bash
44+
# Save an example skill
45+
terraphim-tinyclaw skill save examples/skills/analyze-repo.json
46+
47+
# Run the skill
48+
terraphim-tinyclaw skill run analyze-repo repo_path=/path/to/repo
49+
50+
# List all skills
51+
terraphim-tinyclaw skill list
52+
```
53+
54+
### Creating Skills
55+
56+
Skills are defined as JSON files:
57+
58+
```json
59+
{
60+
"name": "my-skill",
61+
"version": "1.0.0",
62+
"description": "What this skill does",
63+
"author": "Your Name",
64+
"inputs": [
65+
{
66+
"name": "input_name",
67+
"description": "Input description",
68+
"required": true,
69+
"default": null
70+
}
71+
],
72+
"steps": [
73+
{
74+
"type": "tool",
75+
"tool": "shell",
76+
"args": {
77+
"command": "echo {input_name}"
78+
}
79+
}
80+
]
81+
}
82+
```
83+
84+
See [examples/skills/](examples/skills/) for complete examples.
85+
86+
### Skill Commands
87+
88+
- `skill save <path>` - Save a skill from JSON file
89+
- `skill load <name>` - Display skill details
90+
- `skill list` - List all saved skills
91+
- `skill run <name> [key=value...]` - Execute a skill
92+
- `skill cancel` - Cancel running skill
93+
94+
### Skill Storage
95+
96+
Skills are stored in:
97+
- Linux/macOS: `~/.config/terraphim/skills/`
98+
- Windows: `%APPDATA%\terraphim\skills\`
99+
100+
## Configuration
101+
102+
Configuration is loaded from `~/.config/terraphim/tinyclaw.toml`:
103+
104+
```toml
105+
[agent]
106+
workspace = "/path/to/workspace"
107+
max_iterations = 10
108+
109+
[llm.proxy]
110+
base_url = "https://api.openai.com/v1"
111+
api_key = "${OPENAI_API_KEY}"
112+
model = "gpt-4"
113+
114+
[channels.telegram]
115+
token = "${TELEGRAM_BOT_TOKEN}"
116+
allow_from = ["@yourusername"]
117+
118+
[channels.discord]
119+
token = "${DISCORD_BOT_TOKEN}"
120+
allow_from = ["your_user_id"]
121+
```
122+
123+
## Available Tools
124+
125+
- **filesystem**: Read, write, and list files
126+
- **shell**: Execute shell commands (with safety guards)
127+
- **edit**: Search and replace in files
128+
- **web_search**: Search the web
129+
- **web_fetch**: Fetch web pages
130+
- **voice_transcribe**: Transcribe voice messages (requires `voice` feature)
131+
132+
## Development
133+
134+
### Running Tests
135+
136+
```bash
137+
# Unit tests
138+
cargo test -p terraphim_tinyclaw
139+
140+
# Integration tests
141+
cargo test -p terraphim_tinyclaw --test skills_integration
142+
143+
# All tests
144+
cargo test -p terraphim_tinyclaw --all
145+
```
146+
147+
### Adding New Skills
148+
149+
1. Create a JSON file in `examples/skills/`
150+
2. Test locally: `terraphim-tinyclaw skill save your-skill.json`
151+
3. Run: `terraphim-tinyclaw skill run your-skill key=value`
152+
153+
### Architecture
154+
155+
See [docs/plans/tinyclaw-phase2-design.md](../docs/plans/tinyclaw-phase2-design.md) for detailed architecture.
156+
157+
## License
158+
159+
MIT OR Apache-2.0

‎crates/terraphim_tinyclaw/examples/skills/README.md‎

Lines changed: 206 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,206 @@
1+
# TinyClaw Skill Examples
2+
3+
This directory contains example skill definitions for TinyClaw.
4+
5+
## What are Skills?
6+
7+
Skills are JSON-defined workflows that combine multiple steps (tool calls, LLM prompts, shell commands) into reusable automation scripts.
8+
9+
## Available Examples
10+
11+
### analyze-repo
12+
Analyze a git repository structure and provide insights.
13+
14+
```bash
15+
terraphim-tinyclaw skill save examples/skills/analyze-repo.json
16+
terraphim-tinyclaw skill run analyze-repo repo_path=/path/to/repo analysis_type=structure
17+
```
18+
19+
**Inputs:**
20+
- `repo_path` (required): Path to the git repository
21+
- `analysis_type` (optional): Type of analysis - structure, dependencies, or complexity
22+
23+
**Steps:**
24+
1. Get recent git commits
25+
2. List repository structure
26+
3. LLM analysis with context
27+
28+
### research-topic
29+
Research a topic using web search and summarize findings.
30+
31+
```bash
32+
terraphim-tinyclaw skill save examples/skills/research-topic.json
33+
terraphim-tinyclaw skill run research-topic topic="Rust programming" num_results=5
34+
```
35+
36+
**Inputs:**
37+
- `topic` (required): Topic to research
38+
- `num_results` (optional): Number of search results to analyze (default: 5)
39+
40+
**Steps:**
41+
1. Web search for topic
42+
2. LLM analysis of results
43+
3. Log completion timestamp
44+
45+
### code-review
46+
Perform automated code review on a file or directory.
47+
48+
```bash
49+
terraphim-tinyclaw skill save examples/skills/code-review.json
50+
terraphim-tinyclaw skill run code-review target_path=./src/main.rs language=rust
51+
```
52+
53+
**Inputs:**
54+
- `target_path` (required): Path to file or directory to review
55+
- `language` (optional): Programming language (default: auto-detect)
56+
57+
**Steps:**
58+
1. Read target file(s)
59+
2. LLM code review with quality assessment
60+
61+
### generate-docs
62+
Generate documentation for a codebase.
63+
64+
```bash
65+
terraphim-tinyclaw skill save examples/skills/generate-docs.json
66+
terraphim-tinyclaw skill run generate-docs source_path=./src output_path=./docs
67+
```
68+
69+
**Inputs:**
70+
- `source_path` (required): Path to source code directory
71+
- `output_path` (optional): Where to save documentation (default: ./docs/generated)
72+
73+
**Steps:**
74+
1. List source directory structure
75+
2. LLM generates documentation outline
76+
3. Create output directory
77+
4. Write README.md
78+
79+
### security-scan
80+
Basic security scan of files for common vulnerabilities.
81+
82+
```bash
83+
terraphim-tinyclaw skill save examples/skills/security-scan.json
84+
terraphim-tinyclaw skill run security-scan scan_path=./src severity=medium
85+
```
86+
87+
**Inputs:**
88+
- `scan_path` (required): Path to scan for security issues
89+
- `severity` (optional): Minimum severity to report (default: medium)
90+
91+
**Steps:**
92+
1. Find source files
93+
2. Search for potential secrets/credentials
94+
3. LLM security analysis
95+
96+
## Creating Your Own Skills
97+
98+
### Skill Structure
99+
100+
```json
101+
{
102+
"name": "skill-name",
103+
"version": "1.0.0",
104+
"description": "What this skill does",
105+
"author": "Your Name",
106+
"inputs": [
107+
{
108+
"name": "input_name",
109+
"description": "What this input is for",
110+
"required": true,
111+
"default": null
112+
}
113+
],
114+
"steps": [
115+
{
116+
"type": "tool|llm|shell",
117+
...
118+
}
119+
]
120+
}
121+
```
122+
123+
### Step Types
124+
125+
#### Tool Step
126+
```json
127+
{
128+
"type": "tool",
129+
"tool": "tool_name",
130+
"args": {
131+
"param": "value"
132+
}
133+
}
134+
```
135+
136+
Available tools:
137+
- `shell`: Execute shell commands
138+
- `filesystem`: Read/write/list files
139+
- `web_search`: Search the web
140+
- `web_fetch`: Fetch web pages
141+
- `edit`: Edit files with search/replace
142+
143+
#### LLM Step
144+
```json
145+
{
146+
"type": "llm",
147+
"prompt": "Your prompt here with {input_variable}",
148+
"use_context": true
149+
}
150+
```
151+
152+
#### Shell Step
153+
```json
154+
{
155+
"type": "shell",
156+
"command": "echo {variable}",
157+
"working_dir": "/optional/path"
158+
}
159+
```
160+
161+
### Variable Substitution
162+
163+
Use `{variable_name}` syntax to substitute input values:
164+
165+
```json
166+
{
167+
"inputs": [
168+
{"name": "project_name", "required": true}
169+
],
170+
"steps": [
171+
{
172+
"type": "shell",
173+
"command": "mkdir {project_name}"
174+
}
175+
]
176+
}
177+
```
178+
179+
### Using Skills
180+
181+
```bash
182+
# Save a skill
183+
terraphim-tinyclaw skill save path/to/skill.json
184+
185+
# List all skills
186+
terraphim-tinyclaw skill list
187+
188+
# Load and view a skill
189+
terraphim-tinyclaw skill load skill-name
190+
191+
# Run a skill with inputs
192+
terraphim-tinyclaw skill run skill-name key1=value1 key2=value2
193+
194+
# Cancel a running skill
195+
terraphim-tinyclaw skill cancel
196+
```
197+
198+
## Storage Location
199+
200+
Skills are stored in:
201+
- Linux/macOS: `~/.config/terraphim/skills/`
202+
- Windows: `%APPDATA%\terraphim\skills\`
203+
204+
## More Information
205+
206+
See the [TinyClaw documentation](../../docs/) for detailed usage instructions.

0 commit comments

Comments
 (0)