SkillAgentSearch skills...

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-ralph

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

84/100

Supported Platforms

Universal

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.

Substance
26/30
Structure
20/20
Description
12/15
Adoption
12/20
Freshness
15/15

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 found

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.

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.

SkillScoreStarsUpdatedFormat
smart-ralph (this skill)by tzachbon845502mo agoSKILL.md
x402by browser-use100121.0k4d agoSKILL.md
algorithmic-artby anthropics100177.9k56d agoSKILL.md
pptxby anthropics100177.9k56d agoSKILL.md
prospectingby coreyhaines3110060.1k6d agoSKILL.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.

name: 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 --commit to 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:

  1. Stage spec/feature files after generation
  2. Commit with message: chore(<plugin>): commit spec files before implementation
  3. 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:

  1. Output error with task index and attempt count
  2. Include last failure reason
  3. Suggest manual intervention
  4. Do NOT output ALL_TASKS_COMPLETE
  5. Do NOT continue execution

State Corruption

If state file missing or invalid:

  1. Output error with state file path
  2. Suggest re-running the implement command
  3. Do NOT continue execution

Branch Management

All Ralph plugins follow consistent branch strategy:

  1. Check current branch before starting
  2. If on default branch (main/master): prompt for branch strategy
  3. If on feature branch: offer to continue or create new
  4. Quick mode: auto-create branch, no prompts

Related Skills

View on GitHub
GitHub Stars550
CategoryCustomer
Updated2mo ago
Forks48

Languages

Shell

Trust signals

100/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

No cautions
smart-ralph — Universal Skill: Install & Safety Check | SkillAgent