RunMD
Flagged{"isSafe":false,"isSuspicious":true,"riskLevel":"high","findings":[{"category":"system_harm","severity":"high","description":"The skill executes arbitrary shell blocks from markdown (via runmd) which could allow attacker-provided code to perform destructive actions (e.g., rm -rf, modifying files, privilege escalation) or other harmful operations.","evidence":"The workflow is designed to detect and run code fences with languages: bash/sh/zsh/shell and executes 'runmd run <file.md>'. This enables execution of arbitrary shell commands found in markdown files."},{"category":"data_exfiltration","severity":"medium","description":"Code blocks could potentially exfiltrate data or credentials by using network tools or environment variables loaded from .env files.","evidence":"Environment Variables: runmd auto-loads .env files and substitutes ${VAR_NAME} in shell blocks before execution, potentially leaking secrets if blocks echo or transmit them."},{"category":"suspicious_url","severity":"low","description":"Present external URL to a repository (https://github.com/ojowalker77/runmd); while legitimate, external dependencies can be a vector for supply-chain issues if the tool is manipulated.","evidence":"https://github.com/ojowalker77/runmd"}],"summary":"The content defines a tool that executes user-provided shell code blocks from markdown files, which is inherently risky. It can lead to system harm and data exposure if used with untrusted markdown. It references loading environment variables and executing code blocks, and includes a non-suspicious external URL. Recommend strict sandboxing, allowlisting of safe commands, removal or hardening of .env loading, and restricting execution contexts in automation."}
npx machina-cli add skill ojowwalker77/Claude-Matrix/runmd --openclawRunMD
Execute shell code blocks from markdown files using runmd.
Usage
Parse user arguments: <file.md> [options]
- file: Path to a markdown file containing shell code blocks
- --headless: Run in non-interactive mode (default when invoked from here)
- --fail-fast: Stop on first block failure
- --blocks 0,2,5: Run only specific block indices (0-based)
Process
- Confirm
runmdis installed:which runmd || bun install -g runmd - If no file specified, search for markdown files with shell blocks:
Find *.md files, scan for ```bash/```sh/```zsh/```shell code fences - Show the user which shell blocks exist in the file (list them with indices)
- Execute:
runmd run <file.md> [--fail-fast] [--blocks <indices>] - Report results — pass/fail per block with exit codes
Shell Block Detection
Executable code fences use these languages:
Other code blocks (js, python, etc.) are display-only and not executed.
Environment Variables
runmd auto-loads .env files from the markdown file's directory. Variables referenced as ${VAR_NAME} in shell blocks are substituted before execution.
Modes
| Mode | Command | Use Case |
|---|---|---|
| Headless | runmd run <file> | CI/CD, automation, scripted execution |
| Interactive | runmd <file> | Manual exploration, editing, step-by-step |
Default to headless mode (runmd run) when executing from this skill. Suggest interactive mode if the user wants to explore or edit.
Notes
- Exit code 1 if any block fails in headless mode
--fail-faststops at the first failure instead of running all blocks--blocksaccepts comma-separated 0-based indices to run selectively
Source
git clone https://github.com/ojowwalker77/Claude-Matrix/blob/main/skills/runmd/SKILL.mdView on GitHub Overview
RunMD automates executing executable shell code blocks embedded in Markdown files using the runmd tool. This lets you treat Markdown playbooks as runnable scripts, with headless automation, selective block execution, and environment variable support.
How This Skill Works
The skill scans a Markdown file for executable fences (bash, sh, zsh, shell). It ensures runmd is installed, then runs the designated blocks via runmd run <file.md> with optional flags like --fail-fast and --blocks. It auto-loads .env files from the file's directory and reports per-block pass/fail results.
When to Use It
- You have a Markdown-based deployment or setup playbook with shell blocks and want to execute it in CI/CD.
- You need to run only specific blocks by index to test or debug parts of a Markdown document.
- You want non-interactive, script-driven execution by default (headless mode).
- You rely on environment variables defined in a nearby .env file before executing blocks.
- You want to distinguish executable code blocks (bash/sh/zsh/shell) from display-only blocks in a document.
Quick Start
- Step 1: Ensure runmd is installed (which runmd or bun install -g runmd).
- Step 2: Point to the Markdown file containing shell blocks, e.g. <file.md>.
- Step 3: Run: runmd run <file.md> [--fail-fast] [--blocks <indices>].
Best Practices
- Verify runmd is installed (e.g., which runmd or bun install -g runmd) before executing.
- Prefer --fail-fast in CI to stop on the first failing block for fast feedback.
- Use --blocks with a comma-separated list of 0-based indices to limit scope.
- Run in headless mode for automation; switch to interactive only when exploring or editing.
- Ensure only executable fences are present or clearly marked as code to avoid unexpected results.
Example Use Cases
- CI pipeline runs a Markdown-based deployment playbook containing bash blocks.
- QA workflow validates all executable code blocks in a documentation file to catch shell errors.
- Debugging a Markdown guide by running blocks 0 and 3 to isolate failures.
- New developer onboarding: execute setup steps from a README with shell blocks.
- Local development uses .env variables to configure scripts automatically during run.
