agent-skill-code-runner

Code Runner Agent Skill

An Agent Skill that enables AI agents to run code snippets in 35+ programming languages. Works with GitHub Copilot, Claude Code, and other skills-compatible agents.

Features

• 🚀 35+ Languages: JavaScript, Python, TypeScript, Java, C/C++, Go, Rust, Ruby, PHP, and many more
• ⚡ Interpreted & Compiled: Supports both interpreted languages and compiled languages (C, C++, Java, Rust)
• ⏱️ Timeout Handling: Configurable timeout to prevent infinite loops (default: 30 seconds)
• 🔧 Cross-Platform: Works on Windows, macOS, and Linux
• 📦 Zero Dependencies: Pure Node.js implementation, no npm install required

Supported Languages

Installation

Option 1: Copy to Your Project

Copy the .github/skills/code-runner directory to your project:

your-project/
└── .github/
    └── skills/
        └── code-runner/
            ├── SKILL.md
            ├── scripts/
            │   └── run-code.cjs
            └── references/
                └── LANGUAGES.md

Option 2: Clone This Repository

git clone https://github.com/user/agent-skill-code-runner.git
cd agent-skill-code-runner

Usage

With AI Agents (GitHub Copilot, Claude, etc.)

Once installed, the skill is automatically discovered by compatible AI agents. Simply ask:

• "Run this Python code: print('Hello, World!')"
• "Execute the JavaScript: console.log(5 + 3)"
• "Test this Go function..."

The agent will use the skill's instructions and runner script to execute the code.

Direct Script Usage

You can also run the script directly:

Recommended (stdin - avoids escaping issues):

echo "<code>" | node .github/skills/code-runner/scripts/run-code.cjs <language>

Alternative (CLI argument - for simple code only):

node .github/skills/code-runner/scripts/run-code.cjs <language> "<code>"

Examples:

# JavaScript (stdin)
echo "console.log('Hello, World!')" | node scripts/run-code.cjs javascript

# Python (stdin)
echo "print('Hello, World!')" | node scripts/run-code.cjs python

# Go (stdin - handles quotes perfectly)
echo 'package main; import "fmt"; func main() { fmt.Println("Hello!") }' | node scripts/run-code.cjs go

# Multi-line Java (PowerShell inline here-string)
@"
public class Test {
    public static void main(String[] args) {
        System.out.println("Hello from Java!");
    }
}
"@ | node scripts/run-code.cjs java

# Simple code via CLI argument
node scripts/run-code.cjs javascript "console.log(5 + 3)"

# With custom timeout (in milliseconds)
echo "import time; time.sleep(5); print('Done')" | node scripts/run-code.cjs python --timeout 10000

Prerequisites

The script requires the appropriate interpreter or compiler for each language to be installed and available in your PATH:

See references/LANGUAGES.md for the complete list.

How It Works

1. Skill Discovery: AI agents read the SKILL.md file to understand what the skill does
2. Activation: When a user asks to run code, the agent activates the skill
3. Execution: The agent uses scripts/run-code.cjs to:
   • Create a temporary file with the code
   • Execute it with the appropriate interpreter/compiler
   • Return stdout/stderr to the user
4. Cleanup: Temporary files are automatically deleted

Security Considerations

⚠️ Warning: Running arbitrary code can be dangerous. The skill includes guidance for agents to:

• Review code before execution
• Be cautious with file system access, network requests, and system commands
• Confirm execution with users when appropriate

For untrusted code, consider running in a sandboxed environment (Docker, VM, etc.).

Troubleshooting

Escaping Issues (Java, quotes, special characters)

Problem: Code with quotes or special characters fails with "illegal escape character" or similar errors.

Solution: Use stdin instead of CLI arguments:

# ✓ Good (stdin)
echo "System.out.println(\"Hello\");" | node run-code.cjs java

# ✗ Bad (CLI argument - escaping nightmare)
node run-code.cjs java "System.out.println(\"Hello\");"

For AI Agents: Always use stdin when calling the script to avoid shell escaping issues across different platforms.

Language Not Found

Problem: Command not found error

Solution: Install the required interpreter/compiler and ensure it's in your PATH:

# Check if installed
python --version
java -version
node --version

Project Structure

.github/skills/code-runner/
├── SKILL.md                 # Skill definition and instructions
├── scripts/
│   └── run-code.cjs          # Code execution script (CommonJS)
└── references/
    └── LANGUAGES.md         # Detailed language reference

Agent Skills Specification

This skill follows the Agent Skills open standard:

• name: code-runner
• description: Run code snippets in 30+ programming languages
• location: .github/skills/code-runner/

Compatible with:

• GitHub Copilot (VS Code, CLI, Coding Agent)
• Claude Code
• Cursor
• Other skills-compatible agents

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Adding a New Language

1. Add the language config to languageConfig in scripts/run-code.cjs
2. Update the language table in SKILL.md
3. Add detailed info in references/LANGUAGES.md

License

MIT License - see LICENSE for details.

Related Projects

• vscode-code-runner - VS Code extension for running code
• mcp-server-code-runner - MCP Server for code execution
• Agent Skills - Open standard for AI agent capabilities