19. Using In-Repository Diagnostic Skills with Agent Tools¶

This page documents how SimKit’s in-repository diagnostic Skills can be discovered, loaded, and kept synchronized when working with Hermes Agent, OpenClaw, Claude Code, or another coding agent.

The repository copy is the source of truth for project-specific procedures. Runtime agent skill libraries are convenience copies and must be refreshed when the files under skills/ change.

19.1. Repository layout¶

SimKit keeps project-owned Skills under:

skills/
├── README.md
└── software-development/
    ├── r1pro-hssd-joint-frame-overlays/
    │   └── SKILL.md
    ├── r1pro-hssd-segmentation-mask-overlays/
    │   └── SKILL.md
    ├── r1pro-hssd-fingertip-pad-overlays/
    │   └── SKILL.md
    └── r1pro-hssd-overlay-stats-analysis/
        └── SKILL.md

Each leaf directory is a single Skill. The SKILL.md file contains YAML frontmatter with the canonical skill name, description, version, tags, and related skills, followed by the actual operating procedure.

Current diagnostic Skills:

Skill name	Repository path	Use when
`r1pro-hssd-joint-frame-overlays`	`skills/software-development/r1pro-hssd-joint-frame-overlays/SKILL.md`	Validating same-camera joint, object, EEF, and gripper frame projections before interpreting visual evidence.
`r1pro-hssd-segmentation-mask-overlays`	`skills/software-development/r1pro-hssd-segmentation-mask-overlays/SKILL.md`	Rendering and checking SAPIEN robot/object segmentation-mask overlays and point-to-mask distances.
`r1pro-hssd-fingertip-pad-overlays`	`skills/software-development/r1pro-hssd-fingertip-pad-overlays/SKILL.md`	Debugging visible fingertips, finger-link pad clouds, collision boxes, and visual-vs-collision proxy alignment.
`r1pro-hssd-overlay-stats-analysis`	`skills/software-development/r1pro-hssd-overlay-stats-analysis/SKILL.md`	Turning `overlay_stats/frame_*.json` into force-chain, empty-close, planner-seed, and timeline evidence.

For broad R1 Pro manipulation debugging, first load the general r1pro-simulation-manipulation Skill if it is available in the agent runtime, then add one focused diagnostic Skill from the table above.

19.2. Discovery workflow¶

From the repository root, list available in-repo Skills with ordinary shell commands:

find skills -name SKILL.md -print | sort

Inspect the summary before loading a Skill:

sed -n '1,80p' skills/software-development/r1pro-hssd-overlay-stats-analysis/SKILL.md

When using an agent, prefer asking it to read skills/README.md and the exact SKILL.md file before it edits code or runs a diagnostic. Do not rely only on a stale runtime copy.

19.3. Loading with Hermes Agent¶

Hermes Agent can preload enabled Skills by name from its runtime skill library:

cd /root/.openclaw/workspace/simkit
hermes chat --skills r1pro-hssd-overlay-stats-analysis

Multiple Skills may be comma-separated or supplied by repeating the flag:

hermes chat \
  --skills r1pro-simulation-manipulation,r1pro-hssd-fingertip-pad-overlays

For one-shot or scripted runs, the top-level --skills option is also available:

hermes --skills r1pro-hssd-joint-frame-overlays \
  chat -q 'Read the repository Skill and diagnose why the gripper axes float in the latest debug video.'

Useful Hermes CLI checks:

# Show installed/enabled runtime Skills.
hermes skills list

# See supported preload flags.
hermes chat --help

# See available skill-management subcommands.
hermes skills --help

If a Skill exists only in this repository and not in the runtime list, manually synchronize it into the Hermes local skills directory or load it by prompt, as described below. hermes skills install is primarily for registry or direct SKILL.md URL installs; a checked-out in-repo Skill is safest to review and copy explicitly.

19.4. Manual loading by prompt¶

Manual prompt loading works with any agent that can read repository files. Use this pattern when the runtime does not automatically discover SimKit’s skills/ directory:

Before working, read and follow this in-repository Skill:
skills/software-development/r1pro-hssd-overlay-stats-analysis/SKILL.md

Also read skills/README.md for the current SimKit Skill inventory.
Treat the repository file as authoritative over any built-in or previously installed copy.

For a long task, name the Skill in every subtask handoff so a delegated agent does not miss the context.

19.5. Using with OpenClaw¶

OpenClaw should be given the repository path and the specific Skill file in the task prompt. A typical prompt is:

Workdir: /root/.openclaw/workspace/simkit
Use the in-repository diagnostic Skill at:
skills/software-development/r1pro-hssd-fingertip-pad-overlays/SKILL.md

Read skills/README.md first. Then run only the diagnostics needed to decide whether the visible fingertip and pad-cloud evidence is reliable. Save any experiment summary under debug/<experiment_name>/experiment_summary.md.

Recommended OpenClaw practice:

Include the absolute workdir.
Include the relative SKILL.md path.
Tell the agent to read before acting.
Require a verification command and output in the final response.
For multi-agent work, repeat the Skill path in each delegated task.

19.6. Using with Claude Code¶

Claude Code does not need a Hermes runtime install if the prompt explicitly points at the file. Example:

cd /root/.openclaw/workspace/simkit
claude "Read skills/README.md and skills/software-development/r1pro-hssd-joint-frame-overlays/SKILL.md, then diagnose the current overlay projection issue. Use the Skill as the operating procedure and report exact commands/output."

For interactive sessions, paste a short instruction at the start:

Use SimKit's repository Skill as context:
skills/software-development/r1pro-hssd-segmentation-mask-overlays/SKILL.md
Read it now and follow its validation checklist before changing code.

If Claude Code has a project memory or instruction file configured, keep only stable routing instructions there, not copied Skill contents. The SKILL.md file should remain the canonical procedure.

19.7. Keeping runtime Skills synchronized¶

Use a review-then-copy workflow. Do not edit the runtime copy first.

Edit the repository Skill under skills/software-development/<skill-name>/SKILL.md.
Review the diff in the repository.
Copy or sync the checked-in Skill into the agent runtime library used on that machine.
Verify the runtime can see the same Skill name.

For Hermes Agent on this machine, local Skills are stored under ~/.hermes/skills/. A safe synchronization command is:

mkdir -p ~/.hermes/skills/software-development
rsync -a --delete \
  /root/.openclaw/workspace/simkit/skills/software-development/r1pro-hssd-overlay-stats-analysis/ \
  ~/.hermes/skills/software-development/r1pro-hssd-overlay-stats-analysis/
hermes skills list | grep r1pro-hssd-overlay-stats-analysis

To refresh all SimKit in-repo software-development Skills at once:

mkdir -p ~/.hermes/skills/software-development
rsync -a \
  /root/.openclaw/workspace/simkit/skills/software-development/ \
  ~/.hermes/skills/software-development/
hermes skills list | grep r1pro-hssd

For other agents, either point prompts at the repository files or copy the same leaf Skill directories into that agent’s documented local-skill location. Avoid maintaining divergent Markdown copies.

19.8. Versioning and maintenance rules¶

Keep each Skill focused on one diagnostic job.
Update skills/README.md whenever adding, renaming, or removing a Skill.
Increment the version: frontmatter when materially changing a procedure.
Keep commands copy-pasteable from /root/.openclaw/workspace/simkit unless the Skill says otherwise.
Prefer links or paths to shared scripts over duplicating large command explanations in multiple Skills.
In final agent reports, include which Skill file was read and whether it came from the repository or runtime library.

19.9. Troubleshooting¶

Symptom	Fix
Hermes says the Skill name is unknown	Run `hermes skills list`; then sync the repository Skill into `~/.hermes/skills/software-development/<skill-name>/` or load it by prompt.
Agent uses stale instructions	Tell it to read the repository `SKILL.md` and prefer that over runtime copies. Re-sync after repository edits.
OpenClaw or Claude Code ignores the procedure	Put the exact `SKILL.md` path in the first prompt and require the agent to summarize the checklist before acting.
Diagnostic conclusion is based only on a video	Load `r1pro-hssd-overlay-stats-analysis` and require JSON/force-chain evidence before planner or grasp-success claims.