From e372d4366cd0c761b4d50bf3a4276a7201e3794b Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 18 Feb 2026 08:40:42 +0000 Subject: [PATCH 1/5] docs: add implementation plan for agent skills format update Plan to audit and update all .claude/skills/ entries to fully conform with Anthropic's official Claude agent skills specification. https://claude.ai/code/session_018kX6oYeZXi2UvasxbwzC24 --- .../2026-02-18-update-agent-skills-format.md | 365 ++++++++++++++++++ 1 file changed, 365 insertions(+) create mode 100644 docs/plans/2026-02-18-update-agent-skills-format.md diff --git a/docs/plans/2026-02-18-update-agent-skills-format.md b/docs/plans/2026-02-18-update-agent-skills-format.md new file mode 100644 index 0000000..202a9ab --- /dev/null +++ b/docs/plans/2026-02-18-update-agent-skills-format.md @@ -0,0 +1,365 @@ +# Update Agent Skills Format Implementation Plan + +> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. + +**Goal:** Update all `.claude/skills/` entries to fully conform to Anthropic's official Claude agent skills specification. + +**Architecture:** Each skill lives in a dedicated folder (`skill-name/`) containing `SKILL.md` with YAML frontmatter (`name` + `description`) plus optional resource files. The current structure is almost compliant — the main issues are a non-conforming `brainstorming` description and a missing `session-start-hook` skill folder. + +**Tech Stack:** Plain markdown, YAML frontmatter, Git + +--- + +## Background: Official Claude Agent Skills Spec + +From https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview: + +**Required structure:** +``` +.claude/skills/ + skill-name/ ← folder named with lowercase letters, numbers, hyphens + SKILL.md ← required; YAML frontmatter + body + supporting-file.* ← optional resource files +``` + +**Required SKILL.md frontmatter:** +```yaml +--- +name: skill-name # lowercase letters, numbers, hyphens only; max 64 chars; no reserved words +description: Use when... # max 1024 chars; no XML tags; describes WHEN to use, not HOW +--- +``` + +**Three-level loading:** +1. **Metadata** — `name` + `description` always in system prompt (~100 tokens each) +2. **Instructions** — SKILL.md body loaded when skill is triggered (<5k tokens) +3. **Resources** — additional files loaded on demand (no practical token limit) + +--- + +## Audit: Current State + +| Skill | Folder | SKILL.md | Frontmatter | Description format | Status | +|-------|--------|----------|-------------|-------------------|--------| +| `brainstorming` | ✅ | ✅ | ✅ | ❌ Starts with "You MUST use this..." not "Use when..." | **FIX NEEDED** | +| `dispatching-parallel-agents` | ✅ | ✅ | ✅ | ✅ "Use when facing 2+ independent tasks..." | OK | +| `executing-plans` | ✅ | ✅ | ✅ | needs verify | verify | +| `finishing-a-development-branch` | ✅ | ✅ | ✅ | needs verify | verify | +| `receiving-code-review` | ✅ | ✅ | ✅ | needs verify | verify | +| `requesting-code-review` | ✅ | ✅ | ✅ | needs verify | verify | +| `subagent-driven-development` | ✅ | ✅ | ✅ | needs verify | verify | +| `systematic-debugging` | ✅ | ✅ | ✅ | ✅ "Use when encountering any bug..." | OK | +| `test-driven-development` | ✅ | ✅ | ✅ | ✅ "Use when implementing any feature..." | OK | +| `using-git-worktrees` | ✅ | ✅ | ✅ | needs verify | verify | +| `using-superpowers` | ✅ | ✅ | ✅ | needs verify | verify | +| `verification-before-completion` | ✅ | ✅ | ✅ | ✅ "Use when about to claim work is complete..." | OK | +| `writing-plans` | ✅ | ✅ | ✅ | needs verify | verify | +| `writing-skills` | ✅ | ✅ | ✅ | needs verify | verify | +| `session-start-hook` | ❌ **MISSING** | ❌ | ❌ | — | **CREATE** | + +--- + +## Task 1: Set up git branch + +**Files:** None (git operations only) + +**Step 1: Verify you're on the correct branch** + +```bash +git branch +``` +Expected: `* claude/update-agent-skills-format-YAcbJ` + +**Step 2: If not on branch, switch to it** + +```bash +git checkout claude/update-agent-skills-format-YAcbJ +``` + +--- + +## Task 2: Full compliance audit of all SKILL.md frontmatter + +Audit every `SKILL.md` against the spec before making changes. Check: +- `name` field: lowercase letters, numbers, hyphens only; max 64 chars +- `description` field: non-empty; max 1024 chars; no XML tags; starts with "Use when..." +- No extra frontmatter fields beyond `name` and `description` + +**Files:** +- Read: `.claude/skills/*/SKILL.md` (all 14 skill folders) + +**Step 1: Read each remaining unverified SKILL.md** + +Read the following files (frontmatter only — first 10 lines): +- `.claude/skills/executing-plans/SKILL.md` +- `.claude/skills/finishing-a-development-branch/SKILL.md` +- `.claude/skills/receiving-code-review/SKILL.md` +- `.claude/skills/requesting-code-review/SKILL.md` +- `.claude/skills/subagent-driven-development/SKILL.md` +- `.claude/skills/using-git-worktrees/SKILL.md` +- `.claude/skills/using-superpowers/SKILL.md` +- `.claude/skills/writing-plans/SKILL.md` +- `.claude/skills/writing-skills/SKILL.md` + +**Step 2: Record any violations** + +For each file, note: +- Does description start with "Use when..."? (if not, flag it) +- Is description under 1024 chars? (if not, flag it) +- Are there any XML tags in frontmatter? (if yes, flag it) +- Are there extra frontmatter fields beyond `name`/`description`? (if yes, flag it) + +**Step 3: Commit audit notes (optional)** + +No code changes yet — this is a read-only discovery step. + +--- + +## Task 3: Fix `brainstorming` description + +The `brainstorming/SKILL.md` description currently starts with "You MUST use this before any creative work..." which violates the spec (must start with "Use when...") and the internal writing-skills guideline (description must NEVER summarize workflow). + +**Files:** +- Modify: `.claude/skills/brainstorming/SKILL.md` (line 3) + +**Step 1: Read the current description** + +Read `.claude/skills/brainstorming/SKILL.md` lines 1-5. + +**Step 2: Replace the description** + +Change: +```yaml +description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation." +``` + +To (triggering conditions only, no workflow summary, starts with "Use when..."): +```yaml +description: "Use when starting any creative work — creating features, building components, adding functionality, or modifying behavior — before any implementation or planning" +``` + +This: +- Starts with "Use when..." ✅ +- Describes triggering conditions, not workflow ✅ +- Under 1024 chars ✅ +- No XML tags ✅ +- Third person ✅ + +**Step 3: Verify the edit** + +Read `.claude/skills/brainstorming/SKILL.md` lines 1-5 and confirm the change looks correct. + +**Step 4: Commit** + +```bash +git add .claude/skills/brainstorming/SKILL.md +git commit -m "fix: update brainstorming skill description to comply with Claude skills spec + +Description now starts with 'Use when...' and describes triggering +conditions only, not workflow — per Anthropic skills spec and +writing-skills CSO guidelines." +``` + +--- + +## Task 4: Fix any additional violations found in Task 2 + +Apply the same pattern as Task 3 for any other skills flagged during the audit. + +For each violation: + +**Step 1: Read the current SKILL.md** + +**Step 2: Fix the specific violation** + +Common fixes: +- Description doesn't start with "Use when...": Rephrase to start with "Use when [specific triggering conditions]" +- Description summarizes workflow: Remove workflow descriptions, keep only triggering conditions +- Extra frontmatter fields: Remove any fields other than `name` and `description` +- Description over 1024 chars: Trim to most important triggering conditions + +**Step 3: Verify the edit** + +**Step 4: Commit per skill fixed** + +```bash +git add .claude/skills//SKILL.md +git commit -m "fix: update skill description to comply with Claude skills spec" +``` + +--- + +## Task 5: Create `session-start-hook` skill folder + +The `session-start-hook` skill appears in the system-reminder's available skills list but has no folder in `.claude/skills/`. Create it following the official spec. + +**Files:** +- Create: `.claude/skills/session-start-hook/SKILL.md` + +**Step 1: Create the folder and SKILL.md** + +Create `.claude/skills/session-start-hook/SKILL.md` with content: + +```markdown +--- +name: session-start-hook +description: Use when the user wants to set up a repository for Claude Code on the web, or create a SessionStart hook to ensure their project can run tests and linters during web sessions +--- + +# Session Start Hook + +## Overview + +A SessionStart hook runs automatically when Claude Code starts a new session. Use it to ensure the development environment is ready: tests pass, linters are clean, dependencies are installed. + +## When to Use + +- User wants to set up their repo for Claude Code on the web +- User wants tests or linters to run automatically at session start +- User needs environment validation before coding begins + +## Quick Start + +Add a `hooks` section to `.claude/settings.json`: + +```json +{ + "hooks": { + "SessionStart": [ + { + "matcher": "", + "hooks": [ + { + "type": "command", + "command": "your-check-command-here" + } + ] + } + ] + } +} +``` + +## Common Patterns + +| Goal | Command | +|------|---------| +| Run tests | `cargo test` / `npm test` / `pytest` | +| Lint check | `cargo clippy` / `eslint .` | +| Format check | `cargo fmt --check` / `prettier --check .` | +| Install deps | `npm install` / `cargo fetch` | +| Multiple checks | Chain with `&&` | + +## Example: RustBot Session Start Hook + +```json +{ + "hooks": { + "SessionStart": [ + { + "matcher": "", + "hooks": [ + { + "type": "command", + "command": "cargo check && cargo fmt --all -- --check && cargo clippy -- -D warnings" + } + ] + } + ] + } +} +``` + +## Notes + +- Hook failures are surfaced to Claude at session start +- Keep hooks fast (< 30 seconds) to avoid slow session startup +- Use `--check` flags for formatters/linters rather than auto-fixing +``` + +**Step 2: Verify the file was created** + +Read `.claude/skills/session-start-hook/SKILL.md` and confirm content looks correct. + +**Step 3: Commit** + +```bash +git add .claude/skills/session-start-hook/SKILL.md +git commit -m "feat: add session-start-hook skill folder per Claude agent skills spec + +Creates the missing session-start-hook skill with SKILL.md following +the official Claude agent skills format (folder + YAML frontmatter)." +``` + +--- + +## Task 6: Verify overall structure compliance + +Do a final check that all skills now comply with the official spec. + +**Step 1: List all skills and their SKILL.md files** + +```bash +find .claude/skills -name "SKILL.md" | sort +``` + +Expected: One `SKILL.md` per skill folder, including the new `session-start-hook`. + +**Step 2: Check all name fields** + +```bash +grep -h "^name:" .claude/skills/*/SKILL.md | sort +``` + +Verify: all names use only lowercase letters, numbers, hyphens; max 64 chars. + +**Step 3: Check all description fields start with "Use when" or acceptable variants** + +```bash +grep -h "^description:" .claude/skills/*/SKILL.md +``` + +Review each line. + +**Step 4: Confirm no extra frontmatter fields** + +```bash +grep -h "^\w" .claude/skills/*/SKILL.md | grep -v "^name:\|^description:\|^---\|^#" +``` + +Expected: No output (no unexpected top-level YAML keys). + +--- + +## Task 7: Push to remote + +**Step 1: Push the branch** + +```bash +git push -u origin claude/update-agent-skills-format-YAcbJ +``` + +If push fails due to network error, retry with exponential backoff (wait 2s, 4s, 8s, 16s between attempts). + +**Step 2: Verify push succeeded** + +```bash +git log --oneline origin/claude/update-agent-skills-format-YAcbJ..HEAD +``` + +Expected: Empty output (local and remote are in sync). + +--- + +## Summary of Changes + +| Task | Change | Files Affected | +|------|--------|---------------| +| 2 | Audit all 14 skill SKILL.md files | Read-only | +| 3 | Fix `brainstorming` description | `.claude/skills/brainstorming/SKILL.md` | +| 4 | Fix any additional violations found | `.claude/skills//SKILL.md` (TBD) | +| 5 | Create `session-start-hook` skill | `.claude/skills/session-start-hook/SKILL.md` (new) | +| 6 | Verify full compliance | Read-only | +| 7 | Push to remote | Git remote | + +**No application code is modified.** All changes are in `.claude/skills/` only. From 5d903158c8c5037b61e5ccb7ac86c379871c83f6 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 18 Feb 2026 08:49:54 +0000 Subject: [PATCH 2/5] docs: update skills format plan to include RustBot bot skills migration Expands the plan to cover both skill directories: - skills/ (RustBot bot skills): convert flat .md files to folder/SKILL.md format - .claude/skills/ (Claude Code skills): fix compliance issues Also documents how src/skills/loader.rs already supports folder format. https://claude.ai/code/session_018kX6oYeZXi2UvasxbwzC24 --- .../2026-02-18-update-agent-skills-format.md | 399 ++++++++++-------- 1 file changed, 217 insertions(+), 182 deletions(-) diff --git a/docs/plans/2026-02-18-update-agent-skills-format.md b/docs/plans/2026-02-18-update-agent-skills-format.md index 202a9ab..bf8089c 100644 --- a/docs/plans/2026-02-18-update-agent-skills-format.md +++ b/docs/plans/2026-02-18-update-agent-skills-format.md @@ -2,11 +2,12 @@ > **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. -**Goal:** Update all `.claude/skills/` entries to fully conform to Anthropic's official Claude agent skills specification. +**Goal:** Update **two** skill directories to fully conform to Anthropic's official Claude agent skills specification: -**Architecture:** Each skill lives in a dedicated folder (`skill-name/`) containing `SKILL.md` with YAML frontmatter (`name` + `description`) plus optional resource files. The current structure is almost compliant — the main issues are a non-conforming `brainstorming` description and a missing `session-start-hook` skill folder. +1. **`skills/`** — RustBot's own bot skills (loaded into the Telegram bot's LLM system prompt by `src/skills/loader.rs`). Currently uses flat `.md` files → convert to `skill-name/SKILL.md` folder format. +2. **`.claude/skills/`** — Claude Code development skills (used by Claude when working on this project). Already uses folder format but has minor compliance issues to fix. -**Tech Stack:** Plain markdown, YAML frontmatter, Git +**Tech Stack:** Plain markdown, YAML frontmatter, Rust (no code changes needed — loader already supports folder format), Git --- @@ -16,7 +17,7 @@ From https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview: **Required structure:** ``` -.claude/skills/ +skills/ skill-name/ ← folder named with lowercase letters, numbers, hyphens SKILL.md ← required; YAML frontmatter + body supporting-file.* ← optional resource files @@ -25,180 +26,260 @@ From https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview: **Required SKILL.md frontmatter:** ```yaml --- -name: skill-name # lowercase letters, numbers, hyphens only; max 64 chars; no reserved words -description: Use when... # max 1024 chars; no XML tags; describes WHEN to use, not HOW +name: skill-name # lowercase letters, numbers, hyphens only; max 64 chars +description: Use when... # max 1024 chars; no XML tags; triggering conditions only --- ``` -**Three-level loading:** -1. **Metadata** — `name` + `description` always in system prompt (~100 tokens each) -2. **Instructions** — SKILL.md body loaded when skill is triggered (<5k tokens) -3. **Resources** — additional files loaded on demand (no practical token limit) - --- -## Audit: Current State - -| Skill | Folder | SKILL.md | Frontmatter | Description format | Status | -|-------|--------|----------|-------------|-------------------|--------| -| `brainstorming` | ✅ | ✅ | ✅ | ❌ Starts with "You MUST use this..." not "Use when..." | **FIX NEEDED** | -| `dispatching-parallel-agents` | ✅ | ✅ | ✅ | ✅ "Use when facing 2+ independent tasks..." | OK | -| `executing-plans` | ✅ | ✅ | ✅ | needs verify | verify | -| `finishing-a-development-branch` | ✅ | ✅ | ✅ | needs verify | verify | -| `receiving-code-review` | ✅ | ✅ | ✅ | needs verify | verify | -| `requesting-code-review` | ✅ | ✅ | ✅ | needs verify | verify | -| `subagent-driven-development` | ✅ | ✅ | ✅ | needs verify | verify | -| `systematic-debugging` | ✅ | ✅ | ✅ | ✅ "Use when encountering any bug..." | OK | -| `test-driven-development` | ✅ | ✅ | ✅ | ✅ "Use when implementing any feature..." | OK | -| `using-git-worktrees` | ✅ | ✅ | ✅ | needs verify | verify | -| `using-superpowers` | ✅ | ✅ | ✅ | needs verify | verify | -| `verification-before-completion` | ✅ | ✅ | ✅ | ✅ "Use when about to claim work is complete..." | OK | -| `writing-plans` | ✅ | ✅ | ✅ | needs verify | verify | -| `writing-skills` | ✅ | ✅ | ✅ | needs verify | verify | -| `session-start-hook` | ❌ **MISSING** | ❌ | ❌ | — | **CREATE** | +## Part A: RustBot Bot Skills (`skills/`) + +### How RustBot Skills Work + +`src/skills/loader.rs` loads skills from the directory configured in `config.toml` (`[skills] directory = "skills"`). `src/skills/mod.rs` builds a context string from them, injected into the LLM system prompt as: + +``` +## Skill: + +``` + +The loader **already supports both formats**: +- `skills/my-skill.md` — flat file (current, to be replaced) +- `skills/my-skill/SKILL.md` — folder format (target) + +RustBot skills also support an optional `tags` field in frontmatter (RustBot extension, not in Claude spec). + +### Current State Audit + +| Skill file | Format | Issue | +|-----------|--------|-------| +| `skills/coding-assistant.md` | ❌ flat `.md` | Must convert to folder | +| `skills/memory-manager.md` | ❌ flat `.md` | Must convert to folder | --- -## Task 1: Set up git branch +### Task A1: Convert `coding-assistant` to folder format + +**Files:** +- Create: `skills/coding-assistant/SKILL.md` +- Delete: `skills/coding-assistant.md` + +**Step 1: Read current file** + +Read `skills/coding-assistant.md` to confirm full content. -**Files:** None (git operations only) +**Step 2: Create folder and SKILL.md** -**Step 1: Verify you're on the correct branch** +Create `skills/coding-assistant/SKILL.md` with identical content to `skills/coding-assistant.md`. + +**Step 3: Delete the flat file** ```bash -git branch +rm skills/coding-assistant.md ``` -Expected: `* claude/update-agent-skills-format-YAcbJ` -**Step 2: If not on branch, switch to it** +**Step 4: Verify** ```bash -git checkout claude/update-agent-skills-format-YAcbJ +ls skills/coding-assistant/ +cat skills/coding-assistant/SKILL.md ``` ---- +Expected: folder exists, SKILL.md has same frontmatter and body as the original file. + +**Step 5: Commit** + +```bash +git add skills/coding-assistant/SKILL.md +git rm skills/coding-assistant.md +git commit -m "refactor: convert coding-assistant skill to folder format + +Moves skills/coding-assistant.md to skills/coding-assistant/SKILL.md +to match Claude agent skills spec (folder + SKILL.md structure)." +``` -## Task 2: Full compliance audit of all SKILL.md frontmatter +--- -Audit every `SKILL.md` against the spec before making changes. Check: -- `name` field: lowercase letters, numbers, hyphens only; max 64 chars -- `description` field: non-empty; max 1024 chars; no XML tags; starts with "Use when..." -- No extra frontmatter fields beyond `name` and `description` +### Task A2: Convert `memory-manager` to folder format **Files:** -- Read: `.claude/skills/*/SKILL.md` (all 14 skill folders) +- Create: `skills/memory-manager/SKILL.md` +- Delete: `skills/memory-manager.md` -**Step 1: Read each remaining unverified SKILL.md** +**Step 1: Read current file** -Read the following files (frontmatter only — first 10 lines): -- `.claude/skills/executing-plans/SKILL.md` -- `.claude/skills/finishing-a-development-branch/SKILL.md` -- `.claude/skills/receiving-code-review/SKILL.md` -- `.claude/skills/requesting-code-review/SKILL.md` -- `.claude/skills/subagent-driven-development/SKILL.md` -- `.claude/skills/using-git-worktrees/SKILL.md` -- `.claude/skills/using-superpowers/SKILL.md` -- `.claude/skills/writing-plans/SKILL.md` -- `.claude/skills/writing-skills/SKILL.md` +Read `skills/memory-manager.md` to confirm full content. + +**Step 2: Create folder and SKILL.md** + +Create `skills/memory-manager/SKILL.md` with identical content to `skills/memory-manager.md`. + +**Step 3: Delete the flat file** + +```bash +rm skills/memory-manager.md +``` -**Step 2: Record any violations** +**Step 4: Verify** -For each file, note: -- Does description start with "Use when..."? (if not, flag it) -- Is description under 1024 chars? (if not, flag it) -- Are there any XML tags in frontmatter? (if yes, flag it) -- Are there extra frontmatter fields beyond `name`/`description`? (if yes, flag it) +```bash +ls skills/memory-manager/ +cat skills/memory-manager/SKILL.md +``` -**Step 3: Commit audit notes (optional)** +Expected: folder exists, SKILL.md has same frontmatter and body as the original file. + +**Step 5: Commit** + +```bash +git add skills/memory-manager/SKILL.md +git rm skills/memory-manager.md +git commit -m "refactor: convert memory-manager skill to folder format -No code changes yet — this is a read-only discovery step. +Moves skills/memory-manager.md to skills/memory-manager/SKILL.md +to match Claude agent skills spec (folder + SKILL.md structure)." +``` --- -## Task 3: Fix `brainstorming` description +### Task A3: Update CLAUDE.md — document new skills format -The `brainstorming/SKILL.md` description currently starts with "You MUST use this before any creative work..." which violates the spec (must start with "Use when...") and the internal writing-skills guideline (description must NEVER summarize workflow). +The `CLAUDE.md` section on skills must reflect the folder-based format so future contributors know the correct structure. **Files:** -- Modify: `.claude/skills/brainstorming/SKILL.md` (line 3) +- Modify: `CLAUDE.md` -**Step 1: Read the current description** +**Step 1: Find the skills section in CLAUDE.md** -Read `.claude/skills/brainstorming/SKILL.md` lines 1-5. +Search for the skills-related documentation (look for "skill" mentions). -**Step 2: Replace the description** +**Step 2: Update or add skills directory documentation** + +Under the Architecture section or a dedicated Skills section, document: + +```markdown +## Bot Skills (`skills/`) + +Skills are natural-language instruction files loaded at startup and injected into the +LLM's system prompt. Each skill lives in its own folder: -Change: -```yaml -description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation." +``` +skills/ + skill-name/ + SKILL.md # Required: YAML frontmatter + instruction body + supporting-file.* # Optional: templates, examples, reference docs ``` -To (triggering conditions only, no workflow summary, starts with "Use when..."): +**SKILL.md frontmatter:** ```yaml -description: "Use when starting any creative work — creating features, building components, adding functionality, or modifying behavior — before any implementation or planning" +--- +name: skill-name # lowercase letters, numbers, hyphens only +description: Brief description of what this skill does +tags: [tag1, tag2] # optional: for organization +--- ``` -This: -- Starts with "Use when..." ✅ -- Describes triggering conditions, not workflow ✅ -- Under 1024 chars ✅ -- No XML tags ✅ -- Third person ✅ +To add a new skill: create a `skills//` folder with `SKILL.md`. +``` -**Step 3: Verify the edit** +**Step 3: Verify the edit looks correct** -Read `.claude/skills/brainstorming/SKILL.md` lines 1-5 and confirm the change looks correct. +Read the updated section in CLAUDE.md. **Step 4: Commit** ```bash -git add .claude/skills/brainstorming/SKILL.md -git commit -m "fix: update brainstorming skill description to comply with Claude skills spec - -Description now starts with 'Use when...' and describes triggering -conditions only, not workflow — per Anthropic skills spec and -writing-skills CSO guidelines." +git add CLAUDE.md +git commit -m "docs: update CLAUDE.md to document folder-based skills format" ``` --- -## Task 4: Fix any additional violations found in Task 2 +## Part B: Claude Code Skills (`.claude/skills/`) + +These are used by Claude Code when developing RustBot, not by the bot itself. + +### Current State Audit + +| Skill | Folder | SKILL.md | Description format | Status | +|-------|--------|----------|--------------------|--------| +| `brainstorming` | ✅ | ✅ | ❌ Starts with "You MUST use this..." | **FIX** | +| `dispatching-parallel-agents` | ✅ | ✅ | ✅ "Use when facing 2+..." | OK | +| `executing-plans` | ✅ | ✅ | needs verify | verify | +| `finishing-a-development-branch` | ✅ | ✅ | needs verify | verify | +| `receiving-code-review` | ✅ | ✅ | needs verify | verify | +| `requesting-code-review` | ✅ | ✅ | needs verify | verify | +| `subagent-driven-development` | ✅ | ✅ | needs verify | verify | +| `systematic-debugging` | ✅ | ✅ | ✅ "Use when encountering any bug..." | OK | +| `test-driven-development` | ✅ | ✅ | ✅ "Use when implementing any feature..." | OK | +| `using-git-worktrees` | ✅ | ✅ | needs verify | verify | +| `using-superpowers` | ✅ | ✅ | needs verify | verify | +| `verification-before-completion` | ✅ | ✅ | ✅ "Use when about to claim work..." | OK | +| `writing-plans` | ✅ | ✅ | needs verify | verify | +| `writing-skills` | ✅ | ✅ | needs verify | verify | +| `session-start-hook` | ❌ **MISSING** | ❌ | — | **CREATE** | -Apply the same pattern as Task 3 for any other skills flagged during the audit. +--- + +### Task B1: Audit remaining `.claude/skills/` SKILL.md files -For each violation: +Read frontmatter of all unverified skills (first 5 lines each). Flag any that: +- Description doesn't start with "Use when..." +- Description exceeds 1024 chars +- Description contains XML tags +- Frontmatter has fields other than `name` and `description` + +**Files to read:** +- `.claude/skills/executing-plans/SKILL.md` +- `.claude/skills/finishing-a-development-branch/SKILL.md` +- `.claude/skills/receiving-code-review/SKILL.md` +- `.claude/skills/requesting-code-review/SKILL.md` +- `.claude/skills/subagent-driven-development/SKILL.md` +- `.claude/skills/using-git-worktrees/SKILL.md` +- `.claude/skills/using-superpowers/SKILL.md` +- `.claude/skills/writing-plans/SKILL.md` +- `.claude/skills/writing-skills/SKILL.md` -**Step 1: Read the current SKILL.md** +--- -**Step 2: Fix the specific violation** +### Task B2: Fix `brainstorming` description -Common fixes: -- Description doesn't start with "Use when...": Rephrase to start with "Use when [specific triggering conditions]" -- Description summarizes workflow: Remove workflow descriptions, keep only triggering conditions -- Extra frontmatter fields: Remove any fields other than `name` and `description` -- Description over 1024 chars: Trim to most important triggering conditions +**Files:** `.claude/skills/brainstorming/SKILL.md` (line 3) -**Step 3: Verify the edit** +Current (violates spec — summarizes workflow, doesn't start with "Use when..."): +```yaml +description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation." +``` -**Step 4: Commit per skill fixed** +Replace with (triggering conditions only): +```yaml +description: "Use when starting any creative work — creating features, building components, adding functionality, or modifying behavior — before any implementation or planning" +``` +**Commit:** ```bash -git add .claude/skills//SKILL.md -git commit -m "fix: update skill description to comply with Claude skills spec" +git add .claude/skills/brainstorming/SKILL.md +git commit -m "fix: update brainstorming skill description to comply with Claude skills spec" ``` --- -## Task 5: Create `session-start-hook` skill folder +### Task B3: Fix any additional violations found in Task B1 -The `session-start-hook` skill appears in the system-reminder's available skills list but has no folder in `.claude/skills/`. Create it following the official spec. +For each flagged skill, apply same fix as B2: rephrase description to "Use when [triggering conditions]", remove extra frontmatter fields. -**Files:** -- Create: `.claude/skills/session-start-hook/SKILL.md` +Commit each fix separately: +```bash +git add .claude/skills//SKILL.md +git commit -m "fix: update skill description to comply with Claude skills spec" +``` -**Step 1: Create the folder and SKILL.md** +--- -Create `.claude/skills/session-start-hook/SKILL.md` with content: +### Task B4: Create missing `session-start-hook` skill folder + +**Files:** Create `.claude/skills/session-start-hook/SKILL.md` ```markdown --- @@ -228,12 +309,7 @@ Add a `hooks` section to `.claude/settings.json`: "SessionStart": [ { "matcher": "", - "hooks": [ - { - "type": "command", - "command": "your-check-command-here" - } - ] + "hooks": [{"type": "command", "command": "your-check-command-here"}] } ] } @@ -247,10 +323,9 @@ Add a `hooks` section to `.claude/settings.json`: | Run tests | `cargo test` / `npm test` / `pytest` | | Lint check | `cargo clippy` / `eslint .` | | Format check | `cargo fmt --check` / `prettier --check .` | -| Install deps | `npm install` / `cargo fetch` | | Multiple checks | Chain with `&&` | -## Example: RustBot Session Start Hook +## Example: RustBot ```json { @@ -258,12 +333,10 @@ Add a `hooks` section to `.claude/settings.json`: "SessionStart": [ { "matcher": "", - "hooks": [ - { - "type": "command", - "command": "cargo check && cargo fmt --all -- --check && cargo clippy -- -D warnings" - } - ] + "hooks": [{ + "type": "command", + "command": "cargo check && cargo fmt --all -- --check && cargo clippy -- -D warnings" + }] } ] } @@ -273,93 +346,55 @@ Add a `hooks` section to `.claude/settings.json`: ## Notes - Hook failures are surfaced to Claude at session start -- Keep hooks fast (< 30 seconds) to avoid slow session startup -- Use `--check` flags for formatters/linters rather than auto-fixing +- Keep hooks fast (< 30 seconds) +- Use `--check` flags for linters/formatters, not auto-fix ``` -**Step 2: Verify the file was created** - -Read `.claude/skills/session-start-hook/SKILL.md` and confirm content looks correct. - -**Step 3: Commit** - +**Commit:** ```bash git add .claude/skills/session-start-hook/SKILL.md -git commit -m "feat: add session-start-hook skill folder per Claude agent skills spec - -Creates the missing session-start-hook skill with SKILL.md following -the official Claude agent skills format (folder + YAML frontmatter)." +git commit -m "feat: add session-start-hook skill per Claude agent skills spec" ``` --- -## Task 6: Verify overall structure compliance - -Do a final check that all skills now comply with the official spec. - -**Step 1: List all skills and their SKILL.md files** +### Task B5: Final compliance verification ```bash +# All skill folders have SKILL.md find .claude/skills -name "SKILL.md" | sort -``` - -Expected: One `SKILL.md` per skill folder, including the new `session-start-hook`. -**Step 2: Check all name fields** - -```bash +# All names are valid grep -h "^name:" .claude/skills/*/SKILL.md | sort -``` - -Verify: all names use only lowercase letters, numbers, hyphens; max 64 chars. - -**Step 3: Check all description fields start with "Use when" or acceptable variants** -```bash +# All descriptions grep -h "^description:" .claude/skills/*/SKILL.md ``` -Review each line. - -**Step 4: Confirm no extra frontmatter fields** - -```bash -grep -h "^\w" .claude/skills/*/SKILL.md | grep -v "^name:\|^description:\|^---\|^#" -``` - -Expected: No output (no unexpected top-level YAML keys). - --- -## Task 7: Push to remote - -**Step 1: Push the branch** +## Task C: Push to remote ```bash git push -u origin claude/update-agent-skills-format-YAcbJ ``` -If push fails due to network error, retry with exponential backoff (wait 2s, 4s, 8s, 16s between attempts). - -**Step 2: Verify push succeeded** - -```bash -git log --oneline origin/claude/update-agent-skills-format-YAcbJ..HEAD -``` - -Expected: Empty output (local and remote are in sync). +Retry up to 4 times with exponential backoff (2s, 4s, 8s, 16s) on network failure. --- -## Summary of Changes +## Summary of All Changes | Task | Change | Files Affected | |------|--------|---------------| -| 2 | Audit all 14 skill SKILL.md files | Read-only | -| 3 | Fix `brainstorming` description | `.claude/skills/brainstorming/SKILL.md` | -| 4 | Fix any additional violations found | `.claude/skills//SKILL.md` (TBD) | -| 5 | Create `session-start-hook` skill | `.claude/skills/session-start-hook/SKILL.md` (new) | -| 6 | Verify full compliance | Read-only | -| 7 | Push to remote | Git remote | - -**No application code is modified.** All changes are in `.claude/skills/` only. +| A1 | `coding-assistant.md` → `coding-assistant/SKILL.md` | `skills/coding-assistant/SKILL.md` (new), `skills/coding-assistant.md` (deleted) | +| A2 | `memory-manager.md` → `memory-manager/SKILL.md` | `skills/memory-manager/SKILL.md` (new), `skills/memory-manager.md` (deleted) | +| A3 | Document skills format in CLAUDE.md | `CLAUDE.md` | +| B1 | Audit `.claude/skills/` frontmatter | Read-only | +| B2 | Fix `brainstorming` description | `.claude/skills/brainstorming/SKILL.md` | +| B3 | Fix additional violations (TBD) | `.claude/skills//SKILL.md` | +| B4 | Create `session-start-hook` skill | `.claude/skills/session-start-hook/SKILL.md` (new) | +| B5 | Final verification | Read-only | +| C | Push to remote | Git remote | + +**No Rust source code is modified.** The loader already supports folder format. From 751c1ba4779d95ed37a2eb4fb1d7d7110e50afca Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 18 Feb 2026 08:54:32 +0000 Subject: [PATCH 3/5] refactor: convert coding-assistant skill to folder format Moves skills/coding-assistant.md to skills/coding-assistant/SKILL.md to match Claude agent skills spec (folder + SKILL.md structure). https://claude.ai/code/session_018kX6oYeZXi2UvasxbwzC24 --- skills/{coding-assistant.md => coding-assistant/SKILL.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename skills/{coding-assistant.md => coding-assistant/SKILL.md} (100%) diff --git a/skills/coding-assistant.md b/skills/coding-assistant/SKILL.md similarity index 100% rename from skills/coding-assistant.md rename to skills/coding-assistant/SKILL.md From 8a8e310940babf0a6256344b3c1dc53787e202d0 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 18 Feb 2026 08:54:58 +0000 Subject: [PATCH 4/5] refactor: convert memory-manager skill to folder format Moves skills/memory-manager.md to skills/memory-manager/SKILL.md to match Claude agent skills spec (folder + SKILL.md structure). https://claude.ai/code/session_018kX6oYeZXi2UvasxbwzC24 --- skills/{memory-manager.md => memory-manager/SKILL.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename skills/{memory-manager.md => memory-manager/SKILL.md} (100%) diff --git a/skills/memory-manager.md b/skills/memory-manager/SKILL.md similarity index 100% rename from skills/memory-manager.md rename to skills/memory-manager/SKILL.md From dbd7e9c136cc7ff79420e12d023524224a3a2904 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 18 Feb 2026 08:55:44 +0000 Subject: [PATCH 5/5] docs: update CLAUDE.md to document folder-based skills format Adds "Adding a new bot skill" section to Common Tasks describing the skill-name/SKILL.md folder structure per Claude agent skills spec. https://claude.ai/code/session_018kX6oYeZXi2UvasxbwzC24 --- CLAUDE.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 5c90691..072f665 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -154,6 +154,30 @@ Update `default_model()` in `src/config.rs`. Users can also override this in the Add a `[[mcp_servers]]` block to `config.toml` with `name`, `command`, `args`, and optional `env` fields. See `config.example.toml` for examples. +### Adding a new bot skill + +Bot skills are natural-language instructions loaded at startup and injected into the LLM's system prompt. Each skill must be in its own folder following the Claude agent skills format: + +``` +skills/ + skill-name/ + SKILL.md # Required: YAML frontmatter + instruction body + supporting-file.* # Optional: templates, examples, reference docs +``` + +**SKILL.md frontmatter:** +```yaml +--- +name: skill-name # lowercase letters, numbers, hyphens only +description: Brief description of what this skill does +tags: [tag1, tag2] # optional: for organization +--- +``` + +1. Create `skills//SKILL.md` with frontmatter and instruction body +2. The skill is auto-loaded at startup — no code changes needed +3. Configure the skills directory in `config.toml`: `[skills] directory = "skills"` + ## Files Not to Commit - `config.toml` - Contains API keys and tokens