This skill should be used when the user needs to execute tasks through a complete automated workflow: understand natural language intent, dynamically generat...
---
name: universal-agent
author: 王教成 Wang Jiaocheng (波动几何)
description: >
This skill should be used when the user needs to execute tasks through a complete
automated workflow: understand natural language intent, dynamically generate commands
or Python scripts, auto-execute them via shell, and summarize results. This is a
minimal universal agent implementation based on "LLM brain + command executor limbs"
architecture. Use this when users say things like "help me do X automatically",
"generate code and run it", "universal agent", "execute task end-to-end", or when
tasks require dynamic code generation and execution with automatic error recovery.
---
# Universal Agent Skill
A minimal universal AI agent that automates end-to-end task execution: understand user intent in natural language, generate commands or scripts, execute them, analyze results, and self-recover from errors.
## Architecture
```
Natural Language Input
↓
┌─────────────┐
│ LLM (Brain) │ Understand intent, generate command/Python script
└──────┬──────┘
│ Auto-generate code/command
↓
┌─────────────────┐
│ Command Executor │ Execute any command, control software & hardware
│ (Limbs) │
└───────┬─────────┘
│ Actual execution
↓
Task Complete ✅
```
## File Structure
```
universal-agent/
├── SKILL.md # This file (skill definition)
├── scripts/
│ ├── universal_agent.py # Main program (complete standalone implementation)
│ └── config.json # Configuration file (fill in API key for standalone mode)
└── references/
└── README.md # Detailed usage documentation
```
## When to Use
Use this skill when:
- User describes a task in natural language that requires automated execution
- Task needs dynamic code generation (Python script) and immediate execution
- Task involves file operations, data processing, system administration, CLI tools, API calls
- User wants end-to-end automation without manual intervention
- Keywords: "万能agent", "universal agent", "自动执行", "动态生成代码", "生成并执行", "帮我做XX"
## How It Works
### Automated Workflow (4 Steps)
1. **Think** — LLM understands task, judges complexity, decides whether to generate a shell command or Python script
2. **Execute** — Auto-write file → Run command/script → Capture output
3. **Fix** — On error, LLM analyzes error, auto-fixes code, retries (up to 2 times)
4. **Summarize** — Translates technical output into human-friendly language
### Why It's "Universal"
| Capability | Description |
|------------|-------------|
| Shell Commands | File ops, process management, system admin |
| Python Scripts | Data processing, web scraping, ML, image processing |
| CLI Tools | git, docker, ffmpeg, aws, any CLI |
| Hardware Control | Serial/GPIO/network-controlled physical devices |
| API Calls | Any HTTP API |
**Command executor can run Python → Python can do anything → Agent can do anything**
## Usage Modes
This skill supports **three** distinct usage modes, each suited to different scenarios:
### Mode 1: Standalone (独立运行)
Run the bundled script directly as an independent program. The script handles everything internally — LLM calls, command execution, safety checks, retries, memory.
```bash
# Single task mode (needs API key)
python scripts/universal_agent.py --run "task description"
# Interactive mode
python scripts/universal_agent.py
# With environment variables
set LLM_API_KEY=sk-xxx && python scripts/universal_agent.py --run "任务"
```
**What works:** Safety ✅ | Auto-retry ✅ | Memory persistence ✅ | Needs API Key.
---
### Mode 2: Bridge Execution (桥接执行 — 推荐)
Execute the script with `--backend bridge`. The script's **brain is provided by the external Agent** that loaded this Skill, while the script itself handles **execution, safety, retry, and memory**. Any Agent with LLM + command execution can use this.
```bash
# Basic bridge execution
python scripts/universal_agent.py --backend bridge --run "任务描述"
# View full protocol spec
python scripts/universal_agent.py --bridge-info
```
**How it works — the Agent drives the script through environment variables:**
```
┌─────────────────────────────────────────────────────────────┐
│ Bridge Mode Flow │
├─────────────────────────────────────────────────────────────┤
│ │
│ ① User: "列出当前目录的文件" │
│ ↓ │
│ ② External Agent LLM → generates decision │
│ set UA_THINK={"type":"command","content":"dir /b"} │
│ ↓ │
│ ③ Agent executes: │
│ python ... --backend bridge --run "列出当前目录的文件" │
│ ↓ │
│ ④ Script reads UA_THINK → runs "dir /b" │
│ → safety check passes → captures output │
│ ↓ (if error) │
│ ⑤ Script requests fix via UA_DEBUG_AND_FIX env var │
│ ↓ │
│ ⑥ External Agent provides fixed code │
│ set UA_DEBUG_AND_FIX="fixed_command_or_script" │
│ ↓ │
│ ⑦ Script re-executes → success │
│ ↓ │
│ ⑧ Script reads UA_SUMMARIZE for final output │
│ → returns structured JSON result │
│ │
└─────────────────────────────────────────────────────────────┘
```
**Environment Variable Protocol:**
| Variable | When Used | Format |
|----------|----------|--------|
| `UA_THINK` | Step 1 — decision | JSON: `{"type":"command\|script","content":"...","explanation":"..."}` |
| `UA_GENERATE_SCRIPT` | If type=script and code needed | Complete Python source code |
| `UA_SUMMARIZE` | Final step — result summary | Natural language summary text |
| `UA_DEBUG_AND_FIX` | On error retry — fixed code | Fixed Python/shell code |
**What works:** Safety ✅ | Auto-retry ✅ | Memory persistence ✅ | **No API Key needed** (Agent provides LLM).
**Who can use this:** WorkBuddy, Cursor, Continue.dev, Aider, Cline, any AI IDE/tool with LLM + shell access.
---
### Mode 3: Inline Simulation (模拟执行)
The loaded Agent reads this SKILL.md, learns the architecture pattern, and **simulates the workflow using its own native capabilities** without executing the script at all. The script serves as a reference/teaching example only.
- Agent uses its own LLM instead of `LLMBrain`
- Agent uses its own `execute_command` instead of `UniversalExecutor`
- Agent does its own summarization
**What works:** Fastest ⚡ | No setup | **Safety ❌ Retry ❌ Memory ❌** (script features unused).
## Core Components
### `scripts/universal_agent.py` — Main Program
Four core classes implementing the full agent:
| Class | Role | Key Methods |
|-------|------|-------------|
| `LLMBrain` | Brain — HTTP LLM interface (Mode 1) | `think()`, `generate_script()`, `summarize()`, `debug_and_fix()` |
| `AgentBridge` | Brain — External Agent bridge (Mode 2) | `think()`, `generate_script()`, `summarize()`, `debug_and_fix()`, `set_response()` |
| `UniversalExecutor` | Limbs (command execution) | `execute()`, `_execute_command()`, `_execute_script()`, `_check_danger()` |
| `ContextManager` | Memory (state management) | `add_task_record()`, `get_context_string()`, `save()/load()` |
| `UniversalAgent` | Main orchestrator | `run()`, `chat()`, `batch_run()` |
See `references/README.md` for full API documentation and examples.
### Safety Mechanisms
The executor includes built-in danger detection:
| Level | Examples | Handling |
|-------|----------|----------|
| 🔴 High | `rm -rf /`, `format C:` | **Forced confirmation required** |
| 🟡 Medium | `pip uninstall`, `sudo` | Warning prompt |
| 🟢 Low | `ls`, `cat`, `python script.py` | Direct execution |
Danger patterns are defined in `HIGH_DANGER_PATTERNS` and `MEDIUM_DANGER_PATTERNS` within the script.
## Configuration
### Mode 1 (Standalone) — Needs API Key
**Option A — Config File:**
Edit `scripts/config.json` and fill in your API key.
**Option B — Environment Variables:**
```bash
set LLM_API_KEY=your-key-here
set LLM_MODEL=gpt-4o
set LLM_BASE_URL=https://api.openai.com/v1
```
**Option C — Local Ollama (Free):**
```bash
ollama run llama3
# Then select ollama_llama3 preset when starting the script
```
Configuration priority: Environment variables > config.json > Interactive input.
### Mode 2 (Bridge) — No API Key Needed
The external Agent provides all LLM capabilities. Configure only optional settings:
```bash
# Optional: change input source from env to file
set UA_INPUT_SOURCE=file
# Optional: skip safety confirmations (not recommended)
# Use --dangerous flag instead
```
### Mode 3 (Simulation) — No Configuration Needed
Agent uses its own native capabilities. Nothing to configure.
## Supported LLM Providers
| Provider | Models | base_url |
|----------|--------|----------|
| OpenAI | gpt-4o, gpt-4o-mini | https://api.openai.com/v1 |
| DeepSeek | deepseek-chat, deepseek-reasoner | https://api.deepseek.com |
| Qwen | qwen-max, qwen-turbo | https://dashscope.aliyuncs.com/compatible-mode/v1 |
| Zhipu GLM | glm-4-plus | https://open.bigmodel.cn/api/paas/v4 |
| Local Ollama | llama3, qwen2, any model | http://localhost:11434/v1 |
| Groq | llama-3.1-70b-versatile | https://api.groq.com/openai/v1 |
| Any OpenAI-compatible API | any | your-url |
## Platform Support
✅ **Cross-platform** — Windows, macOS, Linux:
| OS | Shell Backend |
|----|--------------|
| Windows | `cmd.exe /c` (with `CREATE_NO_WINDOW`) |
| macOS | `bash` (`shell=True`) |
| Linux | `bash` (`shell=True`) |
All file I/O uses UTF-8 encoding. Python script execution uses `sys.executable` for platform-agnostic invocation.
## Dependencies
✅ **Zero external dependencies** — Python standard library only:
- `os`, `sys` — System operations
- `subprocess` — Command execution
- `json`, `re` — JSON parsing and regex
- `time/datetime` — Time handling
- `urllib` — HTTP requests (fallback)
Optional:
- `requests` library — Better HTTP support (`pip install requests`)
## Free Options
1. **Ollama + local model** (completely free, unlimited, private)
2. **DeepSeek** (~¥1/million tokens, excellent cost-performance)
3. **Groq Cloud** (free tier available, ultra-fast inference)
don't have the plugin yet? install it then click "run inline in claude" again.