| name | zx-markdown-scaffold |
| description | Generate executable zx Markdown scripts with inline documentation, proper globals, and ready-to-run code blocks. |
| license | MIT |
| compatibility | pi |
| metadata | {"audience":"developers","workflow":"automation"} |
zx Markdown Scaffold
Creates executable markdown scripts using Google's zx library. These scripts combine documentation with executable code blocks that can be run directly.
When to Use
- Creating automation scripts that need inline documentation
- Building reusable command-line tools
- Prototyping shell workflows with JavaScript/TypeScript
- Creating self-documenting build scripts
Usage
Invoke this skill with a description of the script you want to create:
"Create a zx markdown script that [description]"
The skill will generate:
- A
.md file with embedded executable code blocks
- Proper zx globals usage (no imports needed)
- Error handling and user feedback
- Documentation explaining the script
Lookout: the markdown file cannot contain a executable codeblock that references itself!
Script Structure
Generated scripts follow this pattern:
# Script Title
Description of what the script does.
## Usage
`zx script-name.md`
Prerequisites
What the user needs before running.
const result = await $`command`
echo(chalk.green("Done!"))
## Available Globals
When writing zx markdown scripts, these are available without imports:
- `$` - Execute shell commands
- `cd()` - Change directory
- `fetch()` - HTTP requests
- `question()` - Interactive prompts
- `echo()` - Print output
- `chalk` - Terminal colors
- `fs` - File system operations
- `path` - Path manipulation
- `glob` - File globbing
- `argv` - Command line arguments
- `stdin()` - Read from stdin
## Examples
### Basic file processor
```markdown
# File Processor
Processes files in a directory.
## Usage
`zx process-files.md ./input`
---
```js
const inputDir = argv._[0] || '.'
const files = await glob(`${inputDir}/*`)
for (const file of files) {
echo(chalk.blue(`Processing: ${file}`))
await $`wc -l ${file}`
}
### Interactive script
```markdown
# Project Setup
Sets up a new project interactively.
---
```js
const name = await question('Project name: ')
const type = await question('Type (node/python): ')
await $`mkdir -p ${name}`
cd(name)
if (type === 'node') {
await $`npm init -y`
} else {
await $`python -m venv venv`
}
echo(chalk.green(`Created ${name}`))
## Best Practices
1. **Use `echo()` not `console.log()`** - Works better with zx
2. **Prefer zx globals over Node imports** - `path`, `fs`, `chalk` are already available
3. **Use template literals with `$`** - `` await $`ls ${dir}` ``
4. **Handle errors with try/catch** - zx throws on non-zero exit codes by default
5. **Use `$.verbose = false`** to suppress command echoing
6. **Use `argv` for CLI arguments** - Access with `argv._[0]`, `argv.flag`
## Output
The skill creates a file named based on your description:
- Input: "script that backups files"
- Output: `./backup-files.md`
## Customization
After generation, you can modify:
- The documentation sections
- Add more code blocks (all `js`, `ts`, `bash` blocks execute)
- Change error handling
- Add configuration via YAML frontmatter
- Use `$({ quiet: true })` for silent command execution
