run-shell
Execute shell commands for system operations, directory creation, and script execution. When you need to run system commands, execute scripts, install packages, or manage processes. Note - if commands fail consecutively, try different approaches.
Best use case
run-shell is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Execute shell commands for system operations, directory creation, and script execution. When you need to run system commands, execute scripts, install packages, or manage processes. Note - if commands fail consecutively, try different approaches.
Teams using run-shell should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/run-shell/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How run-shell Compares
| Feature / Agent | run-shell | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Execute shell commands for system operations, directory creation, and script execution. When you need to run system commands, execute scripts, install packages, or manage processes. Note - if commands fail consecutively, try different approaches.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# Run Shell
执行 Shell 命令。
## Parameters
| 参数 | 类型 | 必填 | 说明 |
|-----|------|-----|------|
| command | string | 是 | 要执行的 Shell 命令 |
| cwd | string | 否 | 工作目录（可选） |
| timeout | integer | 否 | 超时时间（秒），默认 60，范围 10-600 |
## Examples
**列出目录**:
```json
{"command": "ls -la"}
```
**安装依赖**:
```json
{"command": "pip install requests", "timeout": 300}
```
**在指定目录执行**:
```json
{"command": "npm install", "cwd": "/path/to/project"}
```
## Timeout Guidelines
- 简单命令: 30-60 秒
- 安装/下载: 300 秒
- 长时间任务: 根据需要设置更长时间
## Windows PowerShell 指引（重要）
### 转义保护
系统会自动将 PowerShell 命令通过 `-EncodedCommand`（Base64 UTF-16LE）编码执行，
避免 cmd.exe → PowerShell 的多层引号/特殊字符转义破坏。直接传入 PowerShell 命令即可。
### 何时使用 PowerShell vs Python 脚本
| 场景 | 推荐方式 | 原因 |
|------|----------|------|
| 简单系统查询（进程/服务/文件列表） | PowerShell cmdlet | `Get-Process`, `Get-ChildItem` 等一行搞定 |
| 复杂文本处理（正则、URL 提取、HTML/JSON 解析） | **Python 脚本** | 避免 PowerShell 正则 one-liner 的复杂性 |
| 批量文件操作（重命名、过滤、转换） | **Python 脚本** | 更可靠，不受 PowerShell 管道转义影响 |
| 网络下载/HTTP 请求 | **Python 脚本** | `requests`/`urllib` 比 `Invoke-WebRequest` 更灵活 |
### 推荐的 Python 脚本模式
对于复杂文本处理任务，**务必**使用 `write_file` + `run_shell` 组合：
```
步骤 1: write_file 写入 data/temp/task_xxx.py
步骤 2: run_shell "python data/temp/task_xxx.py"
```
**禁止**：在 `run_shell` 中写包含复杂正则的 PowerShell one-liner，例如：
```
# 禁止这种写法
powershell -Command "Get-Content file.html | Select-String -Pattern '(?<=src=\")[^\"]+' | ForEach-Object { $_.Matches.Value } | Sort-Object -Unique | Out-File urls.txt"
```
应改为写 Python 脚本：
```python
import re
from pathlib import Path
html = Path("file.html").read_text(encoding="utf-8")
urls = sorted(set(re.findall(r'src="([^"]+)"', html)))
Path("urls.txt").write_text("\n".join(urls), encoding="utf-8")
```
## Notes
- Windows 使用 PowerShell/cmd 命令（自动 EncodedCommand 编码）
- Linux/Mac 使用 bash 命令
- 如果命令连续失败，请尝试不同的命令或方法
- 失败时可调用 `get_session_logs` 查看详细日志
## Related Skills
- `write-file`: 写入文件
- `read-file`: 读取文件Related Skills
openakita/skills@yuque-skills
Manage Yuque (语雀) knowledge bases, documents, and team collaboration through API integration. Supports personal search, weekly reports, knowledge base management, document CRUD, and group collaboration workflows. Based on yuque/yuque-skills.
openakita/skills@youtube-summarizer
Summarize YouTube videos by extracting transcripts and generating structured notes. Use when the user wants to summarize a YouTube video, extract key points from a talk, create study notes from a lecture, or get timestamps for important moments. Supports multiple URL formats and languages.
openakita/skills@xlsx
Use this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.
openakita/skills@xiaohongshu-creator
Create engaging Xiaohongshu (RED/小红书) content including titles, body text, hashtags, and image style recommendations. Supports multiple content types such as product reviews, tutorials, lifestyle sharing, and shopping guides with platform-specific optimization.
openakita/skills@wechat-article
Create and format WeChat Official Account (公众号) articles with proper Markdown-to-WeChat HTML conversion, rich formatting, cover image guidance, and both API and manual publishing workflows.
openakita/skills@webapp-testing
Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.
openakita/skills@web-artifacts-builder
Suite of tools for creating elaborate, multi-component interactive HTML artifacts using modern frontend web technologies (React, Tailwind CSS, shadcn/ui). Use for complex artifacts requiring state management, routing, or shadcn/ui components - not for simple single-file HTML/JSX artifacts.
openakita/skills@video-downloader
Download YouTube videos with customizable quality and format options. Use this skill when the user asks to download, save, or grab YouTube videos. Supports various quality settings (best, 1080p, 720p, 480p, 360p), multiple formats (mp4, webm, mkv), and audio-only downloads as MP3.
openakita/skills@translate-pdf
Translate PDF documents while preserving original layout, styling, tables, images, and formatting. Supports Simplified Chinese, Traditional Chinese, English, Japanese, Korean, and more. Page-by-page translation with structure preservation.
openakita/skills@todoist-task
Manage Todoist tasks, projects, sections, labels, and filters via REST API v2. Supports task CRUD, due dates, priorities, recurring tasks, project organization, and advanced filtering. Based on doggy8088/agent-skills/todoist-api, using curl + jq.
openakita/skills@theme-factory
Toolkit for styling artifacts with a theme. These artifacts can be slides, docs, reportings, HTML landing pages, etc. There are 10 pre-set themes with colors/fonts that you can apply to any artifact that has been creating, or can generate a new theme on-the-fly.
write-file
Write content to file, creating new or overwriting existing. When you need to create new files, update file content, or save generated code/data.