ms-agent

---
name: ms-agent
version: 1.0.0
description: >-
  Access ms-agent's advanced AI capabilities via MCP tools: deep research,
  document research, financial research, code generation, video generation,
  web search (arxiv/exa/serpapi/tavily), LSP code validation (TypeScript/Python/Java),
  concurrent-safe file editing, and agent delegation. All project-level
  capabilities support async submit/check/get patterns. Use when the user
  asks to research a topic, analyze documents, generate code or videos,
  validate code, edit files, or delegate tasks. Requires ms-agent (pip install ms-agent).
metadata:
  nanobot:
    emoji: "🤖"
    requires:
      bins: ["python3"]
      env: []
  hermes:
    tags: [research, codegen, tools, mcp]
    category: ai-tools
---

# ms-agent Capability Gateway Skill

This is a **single skill package** (`name: ms-agent` in frontmatter) with
**9 capability reference modules** under `references/`. It connects you to the
**ms-agent Capability Gateway** — a unified interface to ms-agent's projects,
components, and atomic tools, exposed as MCP tools.

### Skill identity (`skill_id`)

When loaded by ms-agent's own SkillLoader, `skill_id` equals the directory
name:

| How loaded | Directory | `skill_id` |
|---|---|---|
| Host install (`examples/capability/*/install_skill.sh`) | host `skills/ms-agent/` | `ms-agent` |
| ms-agent itself (`scripts/install_into_ms_agent.sh`) | `$MS_AGENT_HOME/skills/ms-agent/` (default `~/.ms_agent/skills/ms-agent`) | `ms-agent` |
| Wheel / `pip install ms-agent` | `ms_agent/skills/ms-agent/` (built-in) | `ms-agent` |
| Repo folder loaded directly | `ms-agent-skills/` | `ms-agent-skills` |

The frontmatter `name: ms-agent` is the package identifier; `skill_id` follows
the filesystem directory name at load time.

## Setup

Verify ms-agent is installed:

```bash
python scripts/check_ms_agent.py
python scripts/validate_capability_index.py
```

To make this skill discoverable by ms-agent's own SkillCatalog:

```bash
./scripts/install_into_ms_agent.sh
```

The MCP server must be configured in your agent's config. Pick the section
that matches your agent host.

### nanobot config.json

```json
{
  "tools": {
    "mcpServers": {
      "ms-agent": {
        "command": "python3",
        "args": ["-m", "ms_agent.capabilities.mcp_server"],
        "env": {"PYTHONPATH": "/path/to/ms-agent"},
        "toolTimeout": 300,
        "enabledTools": ["*"]
      }
    }
  }
}
```

### OpenClaw openclaw.json

```json
{
  "mcp": {
    "servers": {
      "ms-agent": {
        "command": "/absolute/path/to/python",
        "args": ["-m", "ms_agent.capabilities.mcp_server"],
        "env": {"PYTHONPATH": "/path/to/ms-agent"}
      }
    }
  }
}
```

### Hermes Agent config.yaml

```yaml
mcp_servers:
  ms-agent:
    command: "python3"
    args: ["-m", "ms_agent.capabilities.mcp_server"]
    env:
      PYTHONPATH: "/path/to/ms-agent"
```

Once configured, all 30 capabilities below are available as MCP tools.
The tool prefix depends on your agent host:

| Agent | Tool name format | Example |
|-------|-----------------|---------|
| nanobot | `mcp_ms-agent_<tool>` | `mcp_ms-agent_web_search` |
| OpenClaw | `ms-agent_<tool>` | `ms-agent_web_search` |
| Hermes | `mcp_ms-agent_<tool>` | `mcp_ms-agent_web_search` |
| Cursor / Claude Desktop | `<tool>` (no prefix) | `web_search` |

## Capability Index

### Deep Research

| Tool | Type | Duration | Reference |
|------|------|----------|-----------|
| `submit_research_task` | async submit | seconds | [deep-research.md](references/deep-research.md) |
| `check_research_progress` | async poll | seconds | [deep-research.md](references/deep-research.md) |
| `get_research_report` | async result | seconds | [deep-research.md](references/deep-research.md) |
| `deep_research` | sync (blocks) | hours (20–60 min wall) | [deep-research.md](references/deep-research.md) |

### Document Research

| Tool | Type | Duration | Reference |
|------|------|----------|-----------|
| `submit_doc_research_task` | async submit | seconds | [doc-research.md](references/doc-research.md) |
| `check_doc_research_progress` | async poll | seconds | [doc-research.md](references/doc-research.md) |
| `get_doc_research_report` | async result | seconds | [doc-research.md](references/doc-research.md) |
| `doc_research` | sync (blocks) | minutes (5–20 min wall) | [doc-research.md](references/doc-research.md) |

### Financial Research

| Tool | Type | Duration | Reference |
|------|------|----------|-----------|
| `submit_fin_research_task` | async submit | seconds | [fin-research.md](references/fin-research.md) |
| `check_fin_research_progress` | async poll | seconds | [fin-research.md](references/fin-research.md) |
| `get_fin_research_report` | async result | seconds | [fin-research.md](references/fin-research.md) |
| `fin_research` | sync (blocks) | hours (20–60 min wall) | [fin-research.md](references/fin-research.md) |

### Web Search

| Tool | Type | Duration | Reference |
|------|------|----------|-----------|
| `web_search` | sync | seconds | [web-search.md](references/web-search.md) |

### Code Generation

| Tool | Type | Duration | Reference |
|------|------|----------|-----------|
| `submit_code_genesis_task` | async submit | seconds | [code-genesis.md](references/code-genesis.md) |
| `check_code_genesis_progress` | async poll | seconds | [code-genesis.md](references/code-genesis.md) |
| `get_code_genesis_result` | async result | seconds | [code-genesis.md](references/code-genesis.md) |
| `code_genesis` | sync (blocks) | hours (10–30 min wall) | [code-genesis.md](references/code-genesis.md) |

### Video Generation

| Tool | Type | Duration | Reference |
|------|------|----------|-----------|
| `submit_video_generation_task` | async submit | seconds | [singularity-cinema.md](references/singularity-cinema.md) |
| `check_video_generation_progress` | async poll | seconds | [singularity-cinema.md](references/singularity-cinema.md) |
| `get_video_generation_result` | async result | seconds | [singularity-cinema.md](references/singularity-cinema.md) |
| `video_generation` | sync (blocks) | hours (~20 min wall) | [singularity-cinema.md](references/singularity-cinema.md) |

### Agent Delegation

| Tool | Type | Duration | Reference |
|------|------|----------|-----------|
| `delegate_task` | sync (blocks) | minutes | [agent-delegate.md](references/agent-delegate.md) |
| `submit_agent_task` | async submit | seconds | [agent-delegate.md](references/agent-delegate.md) |
| `check_agent_task` | async poll | seconds | [agent-delegate.md](references/agent-delegate.md) |
| `get_agent_result` | async result | seconds | [agent-delegate.md](references/agent-delegate.md) |
| `cancel_agent_task` | async cancel | seconds | [agent-delegate.md](references/agent-delegate.md) |

### Code Validation

| Tool | Type | Duration | Reference |
|------|------|----------|-----------|
| `lsp_check_directory` | full scan | minutes | [lsp-code-server.md](references/lsp-code-server.md) |
| `lsp_update_and_check` | incremental | seconds | [lsp-code-server.md](references/lsp-code-server.md) |

### File Editing

| Tool | Type | Duration | Reference |
|------|------|----------|-----------|
| `replace_file_contents` | content-match | seconds | [filesystem-tools.md](references/filesystem-tools.md) |
| `replace_file_lines` | line-range | seconds | [filesystem-tools.md](references/filesystem-tools.md) |

## Quick Decision Guide

```
User wants to...
│
├── Research a topic in depth (20-60 min)
│   └── submit_research_task → check_research_progress → get_research_report
│
├── Analyze documents or URLs (5-20 min)
│   └── submit_doc_research_task → check_doc_research_progress → get_doc_research_report
│
├── Financial analysis with data & sentiment (20-60 min)
│   └── submit_fin_research_task → check_fin_research_progress → get_fin_research_report
│
├── Search the web for quick info
│   └── web_search(query="...", engine_type="arxiv|exa|serpapi|tavily")
│
├── Generate a software project from requirements (10-30 min)
│   └── submit_code_genesis_task → check_code_genesis_progress → get_code_genesis_result
│
├── Generate a short video (~ 20 min)
│   └── submit_video_generation_task → check_video_generation_progress → get_video_generation_result
│
├── Delegate a complex multi-step task to an AI agent
│   ├── Short task (< 5 minutes) → delegate_task(query="...")
│   └── Long task → submit_agent_task → check_agent_task → get_agent_result
│
├── Validate code for errors
│   ├── Full project → lsp_check_directory(directory="src/", language="typescript")
│   └── Single file → lsp_update_and_check(file_path="...", content="...", language="...")
│
└── Edit a file precisely
    ├── Know exact text → replace_file_contents (concurrent-safe)
    └── Know line numbers → replace_file_lines
```

## Async Pattern

All project-level capabilities (deep research, doc research, financial
research, code generation, video generation, agent delegation) support an
async submit/check/get pattern. This does NOT block the agent — continue
handling other messages while the task runs in the background.

```
1. submit_*_task(...)      → returns task_id immediately
2. check_*_progress/task(task_id)   → poll status (repeat every few minutes)
3. get_*_result/report(task_id)     → retrieve final result when completed
4. cancel_*_task(task_id)  → cancel if no longer needed (agent delegation only)
```

**Warning — in-process task tracking:** `AsyncTaskManager` is **in-process
only**. Task IDs are lost if the MCP server process restarts, and orphaned
subprocesses may remain. Clients must keep the **same MCP server process** for
the full submit → check → get lifecycle.

Read the reference files for detailed SOP workflows for each capability.

More agent context in modelscope/ms-agent

14 other files this repository gives its agents.