first commit
This commit is contained in:
Hermes Agent
174
software-development/hermes-agent-skill-authoring/SKILL.md
Normal file
174
software-development/hermes-agent-skill-authoring/SKILL.md
Normal file
@@ -0,0 +1,174 @@
|
||||
---
|
||||
name: hermes-agent-skill-authoring
|
||||
description: "Author in-repo SKILL.md: frontmatter, validator, structure."
|
||||
version: 1.0.0
|
||||
author: Hermes Agent
|
||||
license: MIT
|
||||
metadata:
|
||||
hermes:
|
||||
tags: [skills, authoring, hermes-agent, conventions, skill-md]
|
||||
related_skills: [writing-plans, requesting-code-review]
|
||||
---
|
||||
|
||||
# Authoring Hermes-Agent Skills (in-repo)
|
||||
|
||||
## Overview
|
||||
|
||||
There are two places a SKILL.md can live:
|
||||
|
||||
1. **User-local:** `~/.hermes/skills/<maybe-category>/<name>/SKILL.md` — personal, not shared. Created via `skill_manage(action='create')`.
|
||||
2. **In-repo (this skill is about this case):** `/home/bb/hermes-agent/skills/<category>/<name>/SKILL.md` — committed, shipped with the package. Use `write_file` + `git add`. `skill_manage(action='create')` does NOT target this tree.
|
||||
|
||||
## When to Use
|
||||
|
||||
- User asks you to add a skill "in this branch / repo / commit"
|
||||
- You're committing a reusable workflow that should ship with hermes-agent
|
||||
- You're editing an existing skill under `/home/bb/hermes-agent/skills/` (use `patch` for small edits, `write_file` for rewrites; `skill_manage` still works for patch on in-repo skills, but not for `create`)
|
||||
|
||||
## Required Frontmatter
|
||||
|
||||
Source of truth: `tools/skill_manager_tool.py::_validate_frontmatter`. Hard requirements:
|
||||
|
||||
- Starts with `---` as the first bytes (no leading blank line).
|
||||
- Closes with `\n---\n` before the body.
|
||||
- Parses as a YAML mapping.
|
||||
- `name` field present.
|
||||
- `description` field present, ≤ **1024 chars** (`MAX_DESCRIPTION_LENGTH`).
|
||||
- Non-empty body after the closing `---`.
|
||||
|
||||
Peer-matched shape used by every skill under `skills/software-development/`:
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: my-skill-name # lowercase, hyphens, ≤64 chars (MAX_NAME_LENGTH)
|
||||
description: Use when <trigger>. <one-line behavior>.
|
||||
version: 1.0.0
|
||||
author: Hermes Agent
|
||||
license: MIT
|
||||
metadata:
|
||||
hermes:
|
||||
tags: [short, descriptive, tags]
|
||||
related_skills: [other-skill, another-skill]
|
||||
---
|
||||
```
|
||||
|
||||
`version` / `author` / `license` / `metadata` are NOT enforced by the validator, but every peer has them — omit and your skill sticks out.
|
||||
|
||||
## Size Limits
|
||||
|
||||
- Description: ≤ 1024 chars (enforced).
|
||||
- Full SKILL.md: ≤ 100,000 chars (enforced as `MAX_SKILL_CONTENT_CHARS`, ~36k tokens).
|
||||
- Peer skills in `software-development/` sit at **8-14k chars**. Aim for that range. If you're pushing past 20k, split into `references/*.md` and reference them from SKILL.md.
|
||||
|
||||
## Peer-Matched Structure
|
||||
|
||||
Every in-repo skill follows roughly:
|
||||
|
||||
```
|
||||
# <Title>
|
||||
|
||||
## Overview
|
||||
One or two paragraphs: what and why.
|
||||
|
||||
## When to Use
|
||||
- Bulleted triggers
|
||||
- "Don't use for:" counter-triggers
|
||||
|
||||
## <Topic sections specific to the skill>
|
||||
- Quick-reference tables are common
|
||||
- Code blocks with exact commands
|
||||
- Hermes-specific recipes (tests via scripts/run_tests.sh, ui-tui paths, etc.)
|
||||
|
||||
## Common Pitfalls
|
||||
Numbered list of mistakes and their fixes.
|
||||
|
||||
## Verification Checklist
|
||||
- [ ] Checkbox list of post-action verifications
|
||||
|
||||
## One-Shot Recipes (optional)
|
||||
Named scenarios → concrete command sequences.
|
||||
```
|
||||
|
||||
Not every section is mandatory, but `Overview` + `When to Use` + actionable body + pitfalls are the minimum for the skill to feel like a peer.
|
||||
|
||||
## Directory Placement
|
||||
|
||||
```
|
||||
skills/<category>/<skill-name>/SKILL.md
|
||||
```
|
||||
|
||||
Categories currently in repo (confirm with `ls skills/`): `autonomous-ai-agents`, `creative`, `data-science`, `devops`, `dogfood`, `email`, `gaming`, `github`, `leisure`, `mcp`, `media`, `mlops/*`, `note-taking`, `productivity`, `red-teaming`, `research`, `smart-home`, `social-media`, `software-development`.
|
||||
|
||||
Pick the closest existing category. Don't invent new top-level categories casually.
|
||||
|
||||
## Workflow
|
||||
|
||||
1. **Survey peers** in the target category:
|
||||
```
|
||||
ls skills/<category>/
|
||||
```
|
||||
Read 2-3 peer SKILL.md files to match tone and structure.
|
||||
2. **Check validator constraints** in `tools/skill_manager_tool.py` if unsure.
|
||||
3. **Draft** with `write_file` to `skills/<category>/<name>/SKILL.md`.
|
||||
4. **Validate locally**:
|
||||
```python
|
||||
import yaml, re, pathlib
|
||||
content = pathlib.Path("skills/<category>/<name>/SKILL.md").read_text()
|
||||
assert content.startswith("---")
|
||||
m = re.search(r'\n---\s*\n', content[3:])
|
||||
fm = yaml.safe_load(content[3:m.start()+3])
|
||||
assert "name" in fm and "description" in fm
|
||||
assert len(fm["description"]) <= 1024
|
||||
assert len(content) <= 100_000
|
||||
```
|
||||
5. **Git add + commit** on the active branch.
|
||||
6. **Note:** the CURRENT session's skill loader is cached — `skill_view` / `skills_list` will not see the new skill until a new session. This is expected, not a bug.
|
||||
|
||||
## Cross-Referencing Other Skills
|
||||
|
||||
`metadata.hermes.related_skills` unions both trees (`skills/` in-repo and `~/.hermes/skills/`) at load time. You CAN reference a user-local skill from an in-repo skill, but it won't resolve for other users who clone the repo fresh. Prefer referencing only in-repo skills from in-repo skills. If a frequently-referenced skill lives only in `~/.hermes/skills/`, consider promoting it to the repo.
|
||||
|
||||
## Editing Existing In-Repo Skills
|
||||
|
||||
- **Small fix (typo, added pitfall, tightened trigger):** `skill_manage(action='patch', name=..., old_string=..., new_string=...)` works fine on in-repo skills.
|
||||
- **Major rewrite:** `write_file` the whole SKILL.md. `skill_manage(action='edit')` also works but requires supplying the full new content.
|
||||
- **Adding supporting files:** `write_file` to `skills/<category>/<name>/references/<file>.md`, `templates/<file>`, or `scripts/<file>`. `skill_manage(action='write_file')` also works and enforces the references/templates/scripts/assets subdir allowlist.
|
||||
- **Always commit** the edit — in-repo skills are source, not runtime state.
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
1. **Using `skill_manage(action='create')` for an in-repo skill.** It writes to `~/.hermes/skills/`, not the repo tree. Use `write_file` for in-repo creation.
|
||||
|
||||
2. **Leading whitespace before `---`.** The validator checks `content.startswith("---")`; any leading blank line or BOM fails validation.
|
||||
|
||||
3. **Description too generic.** Peer descriptions start with "Use when ..." and describe the *trigger class*, not the one task. "Use when debugging X" > "Debug X".
|
||||
|
||||
4. **Forgetting the author/license/metadata block.** Not validator-enforced, but every peer has it; omitting makes the skill look half-finished.
|
||||
|
||||
5. **Writing a skill that duplicates a peer.** Before creating, `ls skills/<category>/` and open 2-3 peers. Prefer extending an existing skill to creating a narrow sibling.
|
||||
|
||||
6. **Expecting the current session to see the new skill.** It won't. The skill loader is initialized at session start. Verify in a fresh session or via `skill_view` using the exact path.
|
||||
|
||||
7. **Linking to skills that don't exist in-repo.** `related_skills: [some-user-local-skill]` works for you but breaks for other clones. Prefer only in-repo links.
|
||||
|
||||
8. **Merging skills that share output type but use different tech stacks.** Two skills producing the same output (e.g., .pptx) are NOT redundant if they use different implementations (Python vs Node.js). They're complementary — different dependency requirements, different failure modes. Only merge when both the function AND the implementation overlap. Example: `pptx-generator` (python-pptx) and `powerpoint` (pptxgenjs) coexist correctly.
|
||||
|
||||
9. **Adding competitive recommendations in descriptions.** Never write "use skill B instead" in skill A's description. Each skill should describe only its own capabilities. Cross-references create circular dependencies and confuse routing. Bad: "For multi-source search, prefer sn-search-academic." Good: Each skill describes its own triggers and boundaries independently.
|
||||
|
||||
10. **Exposing implementation details as routing signals.** Descriptions should use user-facing concepts, not internal tool names or API key names. Bad: "Requires SN_API_KEY via sn-image-base." Good: "Requires SenseNova API." Users say "make an infographic", not "call sn-image-generate".
|
||||
|
||||
11. **False negative overlap in skill pools.** When optimizing skill descriptions for routing (see reference: `references/skill-routing-optimization.md`), "overlap" means same function AND same implementation. Skills with same output but different approaches are complementary, not redundant. Deleting complementary skills reduces system resilience.
|
||||
|
||||
12. **Measuring skill usage accurately.** Session data lives in `.jsonl` files under `~/.hermes/sessions/` AND in SQLite at `~/.hermes/state.db` (table: `messages`). The `.json` files are request dumps with no message history. To find `skill_view` calls: search tool results in the DB for `{"success": true, "name": "...", "skill_dir": "..."}` patterns. Note: auto-loaded skills (via system prompt "MUST load") don't generate explicit `skill_view` calls, so usage counts are lower bounds.
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
- [ ] File is at `skills/<category>/<name>/SKILL.md` (not in `~/.hermes/skills/`)
|
||||
- [ ] Frontmatter starts at byte 0 with `---`, closes with `\n---\n`
|
||||
- [ ] `name`, `description`, `version`, `author`, `license`, `metadata.hermes.{tags, related_skills}` all present
|
||||
- [ ] Name ≤ 64 chars, lowercase + hyphens
|
||||
- [ ] Description ≤ 1024 chars and starts with "Use when ..."
|
||||
- [ ] Total file ≤ 100,000 chars (aim for 8-15k)
|
||||
- [ ] Structure: `# Title` → `## Overview` → `## When to Use` → body → `## Common Pitfalls` → `## Verification Checklist`
|
||||
- [ ] `related_skills` references resolve in-repo (or are explicitly OK to be user-local)
|
||||
- [ ] `git add skills/<category>/<name>/ && git commit` completed on the intended branch
|
||||
@@ -0,0 +1,93 @@
|
||||
# Skill Description Optimization for Routing
|
||||
|
||||
Based on [SkillRouter (arXiv:2603.22455)](https://arxiv.org/abs/2603.22455) methodology.
|
||||
|
||||
## Core Finding
|
||||
|
||||
In large, overlapping skill pools, **full skill text is the critical routing signal** — not just name + metadata. Hiding skill body causes 31-44pp drop in routing accuracy at 80K scale. For Hermes at ~120 skills, the impact is smaller but still meaningful for overlapping clusters.
|
||||
|
||||
## Description Writing Rules
|
||||
|
||||
### 1. Trigger Words (Required)
|
||||
Every description must include explicit trigger words — the exact phrases users would say.
|
||||
|
||||
```
|
||||
Bad: "Generates professional infographics."
|
||||
Good: "生成信息图。触发词：infographic、信息图、可视化、visual summary。"
|
||||
```
|
||||
|
||||
### 2. Negative Boundaries ("Don't use for")
|
||||
For skills in overlapping domains, specify what they DON'T cover.
|
||||
|
||||
```
|
||||
Good: "触发词：学术论文、文献调研。不用于：通用搜索（用 web_search）。"
|
||||
```
|
||||
|
||||
### 3. No Competitive Recommendations
|
||||
Never recommend skill B inside skill A's description.
|
||||
|
||||
```
|
||||
Bad: "For multi-source search, prefer sn-search-academic over arxiv."
|
||||
Good: Each skill describes itself independently.
|
||||
```
|
||||
|
||||
### 4. No Implementation Details
|
||||
Use user-facing concepts, not internal names.
|
||||
|
||||
```
|
||||
Bad: "Requires SN_API_KEY via sn-image-base's sn_agent_runner.py."
|
||||
Good: "Requires SenseNova API."
|
||||
```
|
||||
|
||||
### 5. Pipeline Relationships (for sub-skills)
|
||||
If a skill is part of a pipeline, label its stage.
|
||||
|
||||
```
|
||||
Good: "[sn-deep-research 子阶段] 按 plan.json 执行单维度搜索。"
|
||||
Good: "[sn-deep-research 最终阶段] 基于 synthesis.md 写最终报告。"
|
||||
```
|
||||
|
||||
### 6. Differentiation Over Function Listing
|
||||
When multiple skills serve similar goals, describe what makes THIS one distinct.
|
||||
|
||||
```
|
||||
Bad: "生成信息图" (both sn-infographic and baoyu-infographic say this)
|
||||
Good: sn-infographic: "87 种布局，支持多轮自动评审优化。"
|
||||
baoyu-infographic: "21 种布局，有用户交互确认流程。"
|
||||
```
|
||||
|
||||
## Overlap Detection
|
||||
|
||||
"Overlap" = same user intent AND same implementation approach. Two skills are **complementary** (keep both) when:
|
||||
- Same output type, different tech stack (Python vs Node.js)
|
||||
- Same domain, different complexity level (lightweight vs full-featured)
|
||||
- Same tool, different workflow (quick vs QA-heavy)
|
||||
|
||||
Examples of complementary pairs that should NOT be merged:
|
||||
- `pptx-generator` (python-pptx) + `powerpoint` (pptxgenjs)
|
||||
- `WeChat-article-reader` (Python/Markdown) + `wechat-article-extractor` (Node.js/JSON)
|
||||
|
||||
## Usage Measurement
|
||||
|
||||
To find which skills are actually used:
|
||||
1. Search `~/.hermes/state.db` → `messages` table for `skill_view` tool results
|
||||
2. Search `~/.hermes/sessions/*.jsonl` for `skill_view` function calls
|
||||
3. `.json` files in sessions/ are request dumps — no message history
|
||||
4. Auto-loaded skills (via system prompt matching) don't generate `skill_view` calls — counts are lower bounds
|
||||
|
||||
```sql
|
||||
-- Find skill_view results in SQLite
|
||||
SELECT content FROM messages
|
||||
WHERE role = 'tool'
|
||||
AND content LIKE '%"skill_dir"%'
|
||||
AND content LIKE '%"success": true%';
|
||||
```
|
||||
|
||||
## Pool Size vs Description Quality
|
||||
|
||||
At Hermes's current scale (~120 skills):
|
||||
- **Reducing pool size** (removing unused skills) has the highest impact
|
||||
- **Improving descriptions** helps for the remaining overlapping clusters
|
||||
- **Code-level changes** (prompt restructuring) are NOT worth the complexity
|
||||
|
||||
The optimal strategy: delete genuinely unused skills → fix descriptions for overlapping pairs → stop.
|
||||
Reference in New Issue
Block a user