AGENTS.md · diff
git:20260608.5756988 to git:20260830.a009b78
33 added, 18 removed. Audit A to A.
# Agent Instructions: Skills Repo
This is the **source repository** for Claude Code and Codex skills. Skills are installed from here to `~/.agents/skills/` (the canonical universal path) and symlinked into `~/.claude/skills/` (Claude Code) via `npx skills`.
## Critical Rule: Never Edit Installed Files
**Installed skill files are build artifacts.** Do not modify them directly.
| Location | What it is | Editable? |
|----------|------------|-----------|
| `plugins/<skill>/` | Source of truth | YES, edit here |
| `~/.agents/skills/<skill>/` | Installed copy (canonical, read by Codex and other universal clients) | NO, reinstall to update |
| `~/.claude/skills/<skill>/` | Symlink into `~/.agents/skills/<skill>/` | NO, reinstall to update |
If you edit `~/.claude/skills/slipbox/SKILL.md` instead of `plugins/slipbox/SKILL.md`, your changes will be lost the next time the skill is installed and will never reach other machines.
## Workflow for Skill Changes
- 1. Edit files under `plugins/<skill>/`
- 2. Commit and push to `main`
- 3. Reinstall on each machine (always use `-g` for global install):
+ 1. Edit files under `plugins/<skill>/`.
+ 2. Run `./scripts/validate-skills.sh`.
+ 3. Commit and push to `main` when the requested workflow authorizes it.
+ 4. Reinstall on each machine (always use `-g` for global install):
```bash
npx skills add randroids-dojo/skills --skill <name> -y -g
```
> **Do not rely on `npx skills update`**: the installed skills have an empty `skillFolderHash` in `~/.agents/.skill-lock.json`, so the CLI cannot detect changes and will always report "All skills are up to date". Always use `npx skills add` to pull the latest.
## Repository Structure
```
plugins/
├── godot/
├── randroid/
- │ ├── SKILL.md # Randroid command namespace
- │ ├── commands/
- │ │ ├── loop.md # /randroid:loop
- │ │ └── address-pr-comments.md
+ │ ├── SKILL.md # Thin workflow router
+ │ ├── skills/ # Focused portable workflows
+ │ │ ├── randroid-loop/
+ │ │ ├── randroid-address-pr-comments/
+ │ │ ├── randroid-vibereview/
+ │ │ └── randroid-clean-slop/
+ │ ├── commands/ # Legacy Claude aliases
│ ├── hooks/
- │ └── scripts/
+ │ └── .claude-plugin/
├── slipbox/
- │ ├── SKILL.md # Full skill documentation and agent instructions
- │ └── commands/
- │ └── slipbox.md # Slash command quick reference
+ │ ├── SKILL.md # Concise portable entrypoint
+ │ └── references/ # Conditional detail
├── spiral/
├── task-tracking-dots/
└── unreal/
```
Each skill has:
- - `SKILL.md`: loaded when the skill is invoked; contains full docs and behavioral instructions for the agent
- - `commands/<name>.md`: loaded when the slash command is used; keep this concise
+ - `SKILL.md`: portable entrypoint using only Agent Skills specification frontmatter
+ - `agents/openai.yaml`: Codex display metadata and explicit default prompt
+ - `.claude-plugin/plugin.json`: Claude Code package metadata for top-level plugins
+ - optional `references/`, `scripts/`, and `assets/` loaded only when needed
+ - optional `commands/` and `hooks/` as Claude-only adapters; keep them thin
+ Install nested Randroid workflows with `--full-depth`, for example:
+
+ ```bash
+ npx skills add randroids-dojo/skills --skill randroid-loop --full-depth -y -g
+ ```
+
## Adding a New Skill
- 1. Create `plugins/<skill-name>/SKILL.md` with YAML frontmatter:
+ 1. Create `plugins/<skill-name>/SKILL.md` with portable YAML frontmatter:
```yaml
---
name: skill-name
- description: "One-line description used for skill discovery."
+ description: Performs a focused workflow. Use when the user asks for its concrete outcome.
---
```
- 2. Optionally add `commands/<skill-name>.md` for a slash command entry point
- 3. Update `README.md` skills table and `.claude-plugin/marketplace.json`
- 4. Commit and push
+ 2. Add `agents/openai.yaml` and `.claude-plugin/plugin.json`.
+ 3. Add at least two positive and two negative routing cases to `tests/trigger-cases.json`.
+ 4. Put detailed conditional material in `references/` and deterministic helpers in `scripts/`.
+ 5. Update `README.md` and `.claude-plugin/marketplace.json`.
+ 6. Add the catalog symlink: `ln -s ../../plugins/<skill-name> .agents/skills/<skill-name>` (the validator requires it).
+ 7. Run `./scripts/validate-skills.sh` before committing.