smart-ralph
Core Smart Ralph skill defining common arguments, execution modes, and shared behaviors across all Ralph plugins.
Install / Use
npx skills add tzachbon/smart-ralph --skill smart-ralphInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Customer SupportSupported Platforms
Tags
Our assessment of smart-ralph
smart-ralph scores 84/100 on our quality scale, 258th of 319 Customer Support skills we index.
Its SKILL.md is 4.0 KB long, well organised into 18 sections with 4 code examples: a solid amount of guidance for an agent.
It has 550 GitHub stars, a meaningful sign that others use it.
Maintenance, license and trust
- The repository was last updated about 2 months ago, so smart-ralph is actively maintained.
- Our last check on 2026-11-06 found the source still online.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-10-15. Automated pattern scan on 2026-10-15. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
smart-ralph compared with similar skills
All 4 of these similar skills score higher than smart-ralph; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| smart-ralph (this skill)by tzachbon | 84 | 550 | 2mo ago | SKILL.md |
| x402by browser-use | 100 | 121.0k | 4d ago | SKILL.md |
| algorithmic-artby anthropics | 100 | 177.9k | 56d ago | SKILL.md |
| pptxby anthropics | 100 | 177.9k | 56d ago | SKILL.md |
| prospectingby coreyhaines31 | 100 | 60.1k | 6d ago | SKILL.md |
Frequently asked questions
- How do I install smart-ralph?
- Run
npx skills add tzachbon/smart-ralph --skill smart-ralph. The install tabs above show the steps for each supported agent. - Which AI agents does smart-ralph work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is smart-ralph safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is smart-ralph still maintained?
- The repository was last updated about 2 months ago, so smart-ralph is actively maintained.
Skill content
View source on GitHubname: smart-ralph description: Core Smart Ralph skill defining common arguments, execution modes, and shared behaviors across all Ralph plugins. version: 0.1.0
Smart Ralph
Core skill for all Ralph plugins. Defines common arguments, execution modes, and shared behaviors.
Common Arguments
All Ralph commands support these standard arguments:
| Argument | Short | Description | Default |
|----------|-------|-------------|---------|
| --quick | -q | Skip interactive phases, auto-generate artifacts, start execution immediately | false |
| --commit | -c | Commit and push spec/feature files after generation | true (normal), false (quick) |
| --no-commit | | Explicitly disable committing files | - |
| --max-task-iterations | -m | Max retries per failed task before stopping | 5 |
| --fresh | -f | Force new spec/feature, overwrite if exists | false |
Argument Parsing Rules
Priority Order (highest to lowest):
1. --no-commit (explicit disable)
2. --commit (explicit enable)
3. --quick mode default (false)
4. Normal mode default (true)
Parsing Logic
commitSpec = true // default
if "--no-commit" in args:
commitSpec = false
else if "--commit" in args:
commitSpec = true
else if "--quick" in args:
commitSpec = false // quick mode defaults to no commit
// else keep default (true)
Execution Modes
Normal Mode (Interactive)
- User reviews artifacts between phases
- Phase transitions require explicit commands
- Each phase sets
awaitingApproval: true - Commits spec files by default
Quick Mode (--quick)
- Skips all interactive prompts and interviews
- Auto-generates all artifacts in sequence
- Immediately starts execution after generation
- Does NOT commit by default (use
--committo override) - Still delegates to subagents (delegation is mandatory)
State File Structure
All Ralph plugins use a state file with common fields:
{
"phase": "research|requirements|design|tasks|execution",
"taskIndex": 0,
"totalTasks": 0,
"taskIteration": 1,
"maxTaskIterations": 5,
"awaitingApproval": false
}
Plugins may extend with additional fields.
Commit Behavior
When commitSpec is true:
- Stage spec/feature files after generation
- Commit with message:
chore(<plugin>): commit spec files before implementation - Push to current branch
When commitSpec is false:
- Files remain uncommitted
- User can manually commit later
Execution Loop (Self-Contained)
The execution loop is self-contained via the built-in stop-hook. No external plugins are required.
1. Coordinator outputs task delegation prompt
2. Stop-hook detects task completion signals
3. Stop-hook outputs continuation prompt for next task
4. Loop ends when coordinator outputs ALL_TASKS_COMPLETE
Coordinator Prompt
The implement command includes the coordinator prompt inline. The stop-hook (hooks/scripts/stop-watcher.sh) reads .speckit-state.json to determine continuation behavior.
Task Completion Protocol
Executor Signals
| Signal | Meaning |
|--------|---------|
| TASK_COMPLETE | Task finished successfully |
| VERIFICATION_PASS | Verification task passed |
| VERIFICATION_FAIL | Verification failed, needs retry |
Coordinator Signals
| Signal | Meaning |
|--------|---------|
| ALL_TASKS_COMPLETE | All tasks done, end loop |
Error Handling
Max Retries
When taskIteration exceeds maxTaskIterations:
- Output error with task index and attempt count
- Include last failure reason
- Suggest manual intervention
- Do NOT output ALL_TASKS_COMPLETE
- Do NOT continue execution
State Corruption
If state file missing or invalid:
- Output error with state file path
- Suggest re-running the implement command
- Do NOT continue execution
Branch Management
All Ralph plugins follow consistent branch strategy:
- Check current branch before starting
- If on default branch (main/master): prompt for branch strategy
- If on feature branch: offer to continue or create new
- Quick mode: auto-create branch, no prompts
Related Skills
x402
121.0kSet up Browser Use Cloud payments with x402 — pay per request from a crypto wallet (USDC on Base mainnet), no signup or API key.
algorithmic-art
177.9kCreating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems.
pptx
177.9kUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an em…
prospecting
60.1kWhen the user wants to find and qualify prospects for outbound, or asks who to target first, which signal to prioritize, or where to spot buyers with the problem: buying signals, enrichment, verification, account research.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
