skills.rest
botminter
botminterOFFICIAL
Explore all skills by this author →
WebsiteGitHub

workspace-doctor

Diagnose BotMinter workspace configuration, submodule, symlink, file, lock, and git-state issues.

18|4|Updated Feb 23, 2026
Search Tags:#git#troubleshooting#workspace#diagnostics#symlinks#submodule#botminter
One-click install
npx skills add https://github.com/botminter/botminter --skill workspace-doctor
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: workspace-doctor
Source: https://github.com/botminter/botminter/tree/main/minty/.claude/skills/workspace-doctor
Command: npx skills add https://github.com/botminter/botminter --skill workspace-doctor

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Detects common BotMinter workspace configuration and synchronization problems that prevent agents from running correctly or cause inconsistent behavior, and surfaces actionable fixes so operators can restore healthy workspaces quickly.

Core Features & Use Cases

  • Workspace provisioning checks: Verifies presence of the workspace marker and required files such as ralph.yml, CLAUDE.md, and PROMPT.md.
  • Repository and sync diagnostics: Identifies missing or stale team submodules, detached HEAD states, and uncommitted changes.
  • Runtime and link validation: Finds broken .claude/agents symlinks and stale Ralph lock files and reports appropriate remediation steps.
  • Use case: When an operator reports "my agent can't start" or "workspace sync failed", run this Skill to get a concise health table with OK/WARN/FAIL statuses and recommended CLI commands to fix the issues.

Quick Start

Run a workspace health check for a member or entire team to list marker, submodule, file, symlink, lock, and git issues and receive suggested CLI fixes.

Frequently Asked Questions about workspace-doctor

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I diagnose BotMinter workspace sync issues and broken symlinks?▼

Diagnose BotMinter workspace sync issues by running a health check that identifies broken .claude/agents symlinks, stale submodules, and missing files. The check returns a status table with OK/WARN/FAIL indicators and suggested CLI remediation commands to fix the detected problems.

What causes a BotMinter agent to fail to start in a team workspace?▼

A BotMinter agent fails to start when the workspace has missing required files like ralph.yml, CLAUDE.md, or PROMPT.md, or has stale Ralph lock files. Running workspace diagnostics surfaces these specific configuration and lock issues with actionable fixes to restore the environment.

How do I check for uncommitted changes and detached HEAD states across team workspaces?▼

Check for uncommitted changes and detached HEAD states across team workspaces by applying diagnostics to all team members. The health check reports git-state issues per member, identifying stale submodules and uncommitted changes while providing CLI commands to resolve them.

Can I run a pre-run validation on a single-member BotMinter workspace?▼

Yes, you can run a pre-run validation on a single-member BotMinter workspace. The diagnostics apply to individual members or entire teams, verifying workspace markers, submodule synchronization, symlink integrity, and lock states before agent execution.

How do I fix stale submodules and missing ralph.yml files in my workspace?▼

Fix stale submodules and missing ralph.yml files by following the suggested CLI remediation commands provided in the diagnostic report. The workspace health check identifies these specific issues and outputs the exact commands needed to restore proper configuration and synchronization.

Related Skills

Explore More Software Engineering Skills→
botminterbotminter
18

team-overview

List BotMinter teams, members, roles, workspaces, and running state from local configs.

Official
Intermediate
EdanStarfireEdanStarfire
15

git-state-validator

Validate Git repository state before branching, merging, or pulling.

Community
Basic
richfremrichfrem
5

plugin-installer

Deploy plugin components into the .agents/ store with environment symlinks.

Community
Advanced
open-haxopen-hax
6

git-safety-check

Check git branch, working tree, remotes, and submodules before destructive operations.

Official
Intermediate