skill-learning/skill-learning/SKILL.md

skill-learning/SKILL.md (3173 bytes)
1 ---
2 name: skill-learning
3 description: Turn hard-won experience into reusable skills, Hermes Agent style. Use at the end of a task that took many steps, hit errors before it worked, or got a correction from the user; and whenever a skill you followed turned out wrong or outdated. Creates a new SKILL.md or patches an existing one so the next session does the job faster.
4 ---
5 
6 # Skill learning
7 
8 Hermes Agent (Nous Research) improves itself in a closed loop: after hard work
9 it writes a skill, and when a skill fails in use it fixes the skill. This skill
10 gives the same loop to every AI on this machine.
11 
12 ## When to run
13 
14 Run this check at the end of a task, after the work is verified and committed.
15 Save a skill only if one of these is true:
16 
17 1. The task took about 5 or more tool calls and the steps will come back.
18 2. You hit errors or dead ends, then found the path that works.
19 3. The user corrected your approach.
20 4. You found a non-obvious workflow, command sequence, or tool quirk.
21 5. You followed an existing skill and it was wrong, incomplete, or outdated.
22 
23 Skip it if none is true. Most tasks need no skill. Never save a one-off
24 answer, project facts that the code already shows, or a step a permission
25 check denied.
26 
27 ## Patch before you create
28 
29 1. List the skill folders (see "Where skills live") and read the names and
30    descriptions.
31 2. If a skill covers the topic, patch it: fix the wrong step, add the gotcha,
32    update the command. Keep the rest.
33 3. Only if nothing covers it, create a new skill.
34 
35 ## Write the skill
36 
37 Folder: `<skills folder>/<kebab-case-name>/SKILL.md`. Format:
38 
39 ```markdown
40 ---
41 name: <kebab-case-name>
42 description: <what it does and WHEN to use it, with the trigger words a future
43   request would contain. One or two sentences.>
44 ---
45 
46 # <Title>
47 
48 ## When to use
49 ## Steps            (numbered, with the exact commands that worked)
50 ## Gotchas          (the errors you hit and how you got past them)
51 ## Verify           (the command that proves it worked)
52 ```
53 
54 Rules for the content:
55 
56 - Write steps that worked, not steps you tried. Keep it under about 150 lines.
57 - Use exact commands, paths, and flags. Refer to code by symbol name, not by
58   line number.
59 - No secrets, tokens, keys, passwords, or personal data. Use environment
60   variable names instead.
61 - A skill never weakens a rule in CLAUDE.md, AGENTS.md,
62   copilot-instructions.md, or GEMINI.md. If a skill and a rule conflict, the
63   rule wins; fix the skill.
64 - Write in plain English: short sentences, active voice.
65 
66 ## Where skills live
67 
68 Each AI reads its own folder. Write the skill to your own folder, then copy
69 the same `<name>/` folder to the other folders on this computer, so all AIs
70 learn it:
71 
72 | AI | Skills folder |
73 |---|---|
74 | Claude Code | `~/.claude/skills/` |
75 | Codex | `~/.codex/skills/` |
76 | Copilot CLI | `~/.copilot/skills/` |
77 | Antigravity | `~/.gemini/skills/` and `~/.gemini/antigravity/skills/` |
78 
79 If a skill is specific to one AI's tools, keep it only in that AI's folder.
80 
81 ## Finish
82 
83 1. Commit the new or patched skill in each config folder that changed (each
84    is a git repo), then push.
85 2. Tell the user in one line: the skill name, created or patched, and why.