# 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.

## Repository layout

SimKit keeps project-owned Skills under:

```text
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.

## Discovery workflow

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

```bash
find skills -name SKILL.md -print | sort
```

Inspect the summary before loading a Skill:

```bash
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.

## Loading with Hermes Agent

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

```bash
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:

```bash
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:

```bash
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:

```bash
# 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.

## 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:

```text
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.

## Using with OpenClaw

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

```text
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:

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

## Using with Claude Code

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

```bash
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:

```text
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.

## Keeping runtime Skills synchronized

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

1. Edit the repository Skill under `skills/software-development/<skill-name>/SKILL.md`.
2. Review the diff in the repository.
3. Copy or sync the checked-in Skill into the agent runtime library used on that machine.
4. 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:

```bash
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:

```bash
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.

## 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.

## 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. |