From 411c117f86a23c43572c0498693691a9a4ea9497 Mon Sep 17 00:00:00 2001 From: gurvinder-dhillon Date: Tue, 7 Apr 2026 11:02:31 -0700 Subject: [PATCH 1/4] feat(skill-crystallizer): add proactive skill crystallization skill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Encodes the Hermes Agent behavioral pattern for Claude Code: proactively create skills from complex session learnings and immediately patch existing skills when they're found stale or wrong during use — without being asked. Includes references/skill-format-guide.md as a supporting file with the canonical SKILL.md format reference. Adds Hermes Agent attribution to THIRD_PARTY_LICENSES.md (MIT, Nous Research). Co-Authored-By: Claude Sonnet 4.6 --- THIRD_PARTY_LICENSES.md | 30 +++++ skills/skill-crystallizer/SKILL.md | 107 ++++++++++++++++++ .../references/skill-format-guide.md | 86 ++++++++++++++ 3 files changed, 223 insertions(+) create mode 100644 skills/skill-crystallizer/SKILL.md create mode 100644 skills/skill-crystallizer/references/skill-format-guide.md diff --git a/THIRD_PARTY_LICENSES.md b/THIRD_PARTY_LICENSES.md index f607725..560cc1d 100644 --- a/THIRD_PARTY_LICENSES.md +++ b/THIRD_PARTY_LICENSES.md @@ -27,3 +27,33 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +--- + +## skill-crystallizer skill + +**Source:** https://github.com/NousResearch/hermes-agent +**License:** MIT +**Copyright:** Copyright (c) 2025 Nous Research + +**Adapted content:** Crystallization trigger rules and timing guidance, adapted from +`SKILLS_GUIDANCE` (agent/prompt_builder.py) and `SKILL_MANAGE_SCHEMA` description +(tools/skill_manager_tool.py). + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/skills/skill-crystallizer/SKILL.md b/skills/skill-crystallizer/SKILL.md new file mode 100644 index 0000000..0ca72ad --- /dev/null +++ b/skills/skill-crystallizer/SKILL.md @@ -0,0 +1,107 @@ +--- +name: skill-crystallizer +description: > + Proactively create and improve skills from session learnings. Trigger automatically + after any complex task (5+ tool calls), tricky bug fix, corrected approach, or + non-obvious workflow discovery. Also trigger immediately when an existing skill is + found to be stale, incomplete, or wrong during use. +--- + +# Skill Crystallizer + +Turn session learnings into reusable skills — automatically, without being asked. + +## When to crystallize (create a new skill) + +Create a skill when ANY of these are true: + +- Task took **5+ tool calls** and produced a non-obvious workflow +- You overcame an **error through investigation** — future sessions will hit the same wall +- The **user corrected your approach** and the corrected version succeeded +- The user explicitly says **"save this"**, "remember this", "make a skill for this" +- You assembled a multi-step command, config, or pattern **from scratch** + +**Skip when:** the task was trivial, the answer was obvious, or it's unlikely to recur. + +## When to improve (patch an existing skill) + +Patch **immediately** — not after finishing the task — when you load a skill and: + +- A step **failed or had wrong syntax** +- You hit a **pitfall the skill doesn't warn about** +- The skill's **description doesn't match** how you actually used it +- **Commands are version-specific** and produced errors + +If you discovered something the skill missed, patch it before you finish the task. The moment passes. + +## Three decisions before writing + +### 1. Destination + +| Location | When to use | +|----------|-------------| +| `skills//` | General enough to share publicly via skills.sh | +| `.claude/skills//` | Personal, project-specific, or experimental | + +Default to `.claude/skills/` unless you're confident it's broadly reusable. + +### 2. Name + +Lowercase slug, hyphens only, max 64 characters. Describes the **task type**, not the outcome. + +- `git-rebase-interactive` ✓ +- `fixed-rebase-conflict-april` ✗ + +### 3. Description + +Must include trigger conditions first. Pattern: `Use when . .` + +The description is loaded into Claude's system prompt on every session — write it so Claude can self-trigger without being asked. + +## Writing the SKILL.md + +**Required frontmatter:** +```yaml +--- +name: your-skill-name +description: Use when . . +--- +``` + +**Body structure that works:** + +1. **When to use** — specific triggers, not broad categories +2. **Numbered steps** — exact commands, no hedging ("you might want to...") +3. **Pitfalls** — the errors you hit in this session +4. **Verification** — how to confirm it worked + +Load `references/skill-format-guide.md` for the full frontmatter schema and field options. + +**Supporting files** (use when body would exceed ~500 lines or needs structured reference material): + +- `references/` — documentation, API guides, large reference content +- `templates/` — boilerplate the skill produces +- `scripts/` — executable helpers Claude can run + +## Patching an existing skill + +1. **Read the existing SKILL.md first** — never patch blind +2. **Make targeted `Edit` calls** — don't rewrite the whole file +3. Add to the pitfalls section, fix a command, append a missing step +4. **Tell the user:** "I updated `` to add the pitfall we hit." + +## Quality gate + +Before writing, verify: + +- [ ] Description contains a clear trigger condition (`Use when...`) +- [ ] Every step has an exact command or concrete action +- [ ] Pitfalls section covers what actually went wrong in this session +- [ ] Skill is scoped to **one task type** — if it covers unrelated things, split it + +## Anti-patterns + +- **No session transcripts** — skills encode *how*, not *what happened* +- **No duplicates** — if an existing skill covers the same territory, patch it instead +- **No broad descriptions** — a description that triggers on everything helps no one +- **No deferred patching** — "I'll fix the skill later" means never diff --git a/skills/skill-crystallizer/references/skill-format-guide.md b/skills/skill-crystallizer/references/skill-format-guide.md new file mode 100644 index 0000000..f0f70db --- /dev/null +++ b/skills/skill-crystallizer/references/skill-format-guide.md @@ -0,0 +1,86 @@ +# SKILL.md Format Reference + +Canonical format for Claude Code skills (agentskills.io compatible). + +--- + +## Frontmatter schema + +```yaml +--- +name: skill-name # Required. Lowercase, hyphens, max 64 chars. +description: > # Required. Max 1024 chars. Include trigger conditions. + Use when . . +version: 1.0.0 # Optional. Semver. +author: Your Name # Optional. +license: MIT # Optional. +platforms: [macos, linux] # Optional. Restrict to OS. Omit = all platforms. + # Valid values: macos, linux, windows +metadata: # Optional. Arbitrary structured data. + hermes: + tags: [tag1, tag2] + related_skills: [other-skill] +--- +``` + +**Required fields:** `name` and `description` — the validator (`bash .github/scripts/validate.sh`) fails without them. + +**Description writing rules:** +- Start with the trigger: `Use when...` or `Trigger automatically when...` +- Be specific enough that Claude can self-activate without being asked +- Keep under 1024 characters (the validator doesn't check this but the skills runtime truncates) + +--- + +## Directory layout + +``` +skills/ + / + SKILL.md # Required — main instructions + README.md # Optional — human-readable guide + references/ # Optional — docs, API guides, large reference material + templates/ # Optional — boilerplate the skill produces + scripts/ # Optional — executable helpers + assets/ # Optional — images, data files + evals/ + evals.json # Optional — test cases for skill evaluation +``` + +--- + +## Where skills live + +| Location | Purpose | +|----------|---------| +| `skills//` | Publishable — distributed via skills.sh | +| `.claude/skills//` | Local — personal or project-specific | + +The validator syncs `skills/` → `.claude/skills/` as symlinks automatically. + +--- + +## Body conventions + +**Progressive disclosure** — Claude loads content in stages: +1. **Level 1 (always):** `name` + `description` from frontmatter (~100 tokens) +2. **Level 2 (on trigger):** Full `SKILL.md` body (<500 lines target) +3. **Level 3 (as needed):** Files in `references/`, `templates/`, etc. + +**Writing style:** +- Imperative form: "Read the file first." not "You should read the file." +- Explain the *why* behind rules, not just the rule itself +- Exact commands over descriptions: `` `git rebase -i HEAD~3` `` not "run a rebase" +- Pitfalls section: what went wrong during the session that generated this skill + +**Keep the body lean.** If SKILL.md would exceed ~500 lines, move reference material to `references/` and link to it. + +--- + +## Validation + +```bash +bash .github/scripts/validate.sh +``` + +Checks: `SKILL.md` exists, `name:` present, `description:` present. Creates `.claude/skills/` symlinks. From d84d69ba68c4b6de06eded45e9b8274630ba0928 Mon Sep 17 00:00:00 2001 From: gurvinder-dhillon Date: Tue, 7 Apr 2026 11:13:44 -0700 Subject: [PATCH 2/4] feat(skill-crystallizer): symlink skill into .claude/skills/ Co-Authored-By: Claude Sonnet 4.6 --- .claude/skills/skill-crystallizer | 1 + 1 file changed, 1 insertion(+) create mode 120000 .claude/skills/skill-crystallizer diff --git a/.claude/skills/skill-crystallizer b/.claude/skills/skill-crystallizer new file mode 120000 index 0000000..5dc1a57 --- /dev/null +++ b/.claude/skills/skill-crystallizer @@ -0,0 +1 @@ +../../skills/skill-crystallizer \ No newline at end of file From 081ad8b9f16fad72d381f12c15343d2b7ca73d6a Mon Sep 17 00:00:00 2001 From: gurvinder-dhillon Date: Tue, 7 Apr 2026 11:18:01 -0700 Subject: [PATCH 3/4] fix(skill-crystallizer): fix description per writing-skills CSO rules MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Start description with "Use when..." (not workflow summary) - Remove "what it does" from description pattern — trigger conditions only Co-Authored-By: Claude Sonnet 4.6 --- skills/skill-crystallizer/SKILL.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/skills/skill-crystallizer/SKILL.md b/skills/skill-crystallizer/SKILL.md index 0ca72ad..759be55 100644 --- a/skills/skill-crystallizer/SKILL.md +++ b/skills/skill-crystallizer/SKILL.md @@ -1,10 +1,9 @@ --- name: skill-crystallizer description: > - Proactively create and improve skills from session learnings. Trigger automatically - after any complex task (5+ tool calls), tricky bug fix, corrected approach, or - non-obvious workflow discovery. Also trigger immediately when an existing skill is - found to be stale, incomplete, or wrong during use. + Use when you've completed a complex task (5+ tool calls), overcome a tricky bug, + had your approach corrected by the user, or discovered a non-obvious workflow. + Also use when loading an existing skill that's stale, incomplete, or wrong. --- # Skill Crystallizer @@ -54,7 +53,7 @@ Lowercase slug, hyphens only, max 64 characters. Describes the **task type**, no ### 3. Description -Must include trigger conditions first. Pattern: `Use when . .` +Must include trigger conditions only. Pattern: `Use when .` The description is loaded into Claude's system prompt on every session — write it so Claude can self-trigger without being asked. @@ -64,7 +63,7 @@ The description is loaded into Claude's system prompt on every session — write ```yaml --- name: your-skill-name -description: Use when . . +description: Use when . --- ``` From 38bc32cd78a6dc316733cc5aa46e40cb857cf44e Mon Sep 17 00:00:00 2001 From: gurvinder-dhillon Date: Tue, 7 Apr 2026 12:15:53 -0700 Subject: [PATCH 4/4] fix(skill-creator): align description guidance with writing-skills CSO rules Replace "include what the skill does AND when to use" with trigger-conditions-only guidance. Adds the reason (Claude follows description instead of reading the body if it contains workflow summary) and redirects the "pushy" advice toward specific trigger conditions rather than process description. Co-Authored-By: Claude Sonnet 4.6 --- .agents/skills/skill-creator/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.agents/skills/skill-creator/SKILL.md b/.agents/skills/skill-creator/SKILL.md index 65b3a40..30d4963 100644 --- a/.agents/skills/skill-creator/SKILL.md +++ b/.agents/skills/skill-creator/SKILL.md @@ -64,7 +64,7 @@ Check available MCPs - if useful for research (searching docs, finding similar s Based on the user interview, fill in these components: - **name**: Skill identifier -- **description**: When to trigger, what it does. This is the primary triggering mechanism - include both what the skill does AND specific contexts for when to use it. All "when to use" info goes here, not in the body. Note: currently Claude has a tendency to "undertrigger" skills -- to not use them when they'd be useful. To combat this, please make the skill descriptions a little bit "pushy". So for instance, instead of "How to build a simple fast dashboard to display internal Anthropic data.", you might write "How to build a simple fast dashboard to display internal Anthropic data. Make sure to use this skill whenever the user mentions dashboards, data visualization, internal metrics, or wants to display any kind of company data, even if they don't explicitly ask for a 'dashboard.'" +- **description**: Trigger conditions only — start with "Use when..." and describe the situations, symptoms, and contexts that signal this skill applies. Never summarize what the skill does or its workflow; Claude may follow the description instead of reading the full body if it contains workflow details. To combat undertriggering, be specific and "pushy" about trigger conditions: enumerate concrete situations, edge cases, and synonyms rather than summarizing process. For example, instead of "Use when the user wants a dashboard", write "Use when the user mentions dashboards, data visualization, internal metrics, charts, or wants to display any kind of company data, even if they don't explicitly ask for a 'dashboard'." - **compatibility**: Required tools, dependencies (optional, rarely needed) - **the rest of the skill :)**