fix(skills): align hermes-agent-skill-authoring with hardline authoring standards
The in-repo skill-authoring skill taught the validator's ceilings (1024-char descriptions, 'Use when ...' phrasing) instead of the repo's review standards, so agents following it produced skills that fail review: 240+ char descriptions, author 'Hermes Agent' with no human credit, no bundled-vs- optional decision, dangling related_skills, no platforms audit, no tests, no docs regen, and machine-local /home/bb/... paths baked into prose. Rewritten to teach the hardline standards from AGENTS.md: - description <= 60 chars, one sentence, ends with period - author credits the human contributor first - bundled vs optional tier decision (5+ sessions/month bar; default optional) - no router/index/hub skills - platforms: audited against actual scripts, POSIX-signal table - related_skills must resolve in-repo - Hermes-tool framing instead of raw shell prose - tests at tests/skills/ + docs regen with scope discipline - removed machine-local paths; validator limits marked as NOT the standard
This commit is contained in:
teknium1
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: hermes-agent-skill-authoring
|
||||
description: "Author in-repo SKILL.md files: frontmatter and structure."
|
||||
version: 1.1.0
|
||||
version: 2.0.0
|
||||
author: Hermes Agent
|
||||
license: MIT
|
||||
platforms: [linux, macos, windows]
|
||||
@@ -18,128 +18,144 @@ metadata:
|
||||
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.
|
||||
2. **In-repo (this skill is about this case):** `skills/<category>/<name>/SKILL.md` or `optional-skills/<category>/<name>/SKILL.md` inside the hermes-agent repo — committed, shipped with the package. Use `write_file` + `git add`. `skill_manage(action='create')` does NOT target this tree.
|
||||
|
||||
In-repo skills must meet the repo's **hardline authoring standards** (see AGENTS.md, "Skill authoring standards (HARDLINE)" — that section is the source of truth; this skill is the operational walkthrough). Reviewers reject PRs that violate them, so meeting them up front is cheaper than a salvage pass later.
|
||||
|
||||
## 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`)
|
||||
- You're editing an existing skill under `skills/` or `optional-skills/` (use `patch` for small edits, `write_file` for rewrites; `skill_manage` still works for patch on in-repo skills, but not for `create`)
|
||||
- Don't use for: personal skills in `~/.hermes/skills/` (just use `skill_manage`)
|
||||
|
||||
## Decide the Tier First: Bundled vs Optional
|
||||
|
||||
- **Bundled (`skills/<category>/`)** — daily-driver behavior, broadly useful across many user types, low footprint. Hard bar: you can say "a user will load this in 5+ sessions per month" with a straight face.
|
||||
- **Optional (`optional-skills/<category>/`)** — niche, vertical-specific (blockchain, gaming, finance, one app), recurring-job/task skills, or anything heavy. Installed via `hermes skills install official/<category>/<skill>`.
|
||||
|
||||
**When in doubt, optional.** Promoting later is easy; demoting is churn. "Would be useful to anyone who ever needs this" is an optional-tier argument, not a bundled one.
|
||||
|
||||
Pick the category by what the tool IS, not what it feels like (an AI-agent CLI goes in `autonomous-ai-agents/` even if it "feels productivity"). Confirm existing categories with `search_files(pattern='*', target='files', path='skills')` and don't invent new top-level categories casually.
|
||||
|
||||
**No router / index / hub skills.** A skill whose core content is a routing table pointing at sibling skills adds an indirection hop and duplicates the siblings' own `When to Use` triggers. If the skill would be empty without "load skill X instead" pointers, don't write it — the catalog and each sibling's triggers already do that job.
|
||||
|
||||
## Required Frontmatter
|
||||
|
||||
Source of truth: `tools/skill_manager_tool.py::_validate_frontmatter`. Hard requirements:
|
||||
Validator source of truth: `tools/skill_manager_tool.py::_validate_frontmatter`. Validator 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`).
|
||||
**Long descriptions are truncated to 57 chars + "..." in the system
|
||||
prompt skill index** (`extract_skill_description` in `agent/skill_utils.py`);
|
||||
longer text is visible via `skills_list()` and `skill_view()`.
|
||||
Front-load the trigger phrase.
|
||||
- `description` field present (validator ceiling 1024 chars — but see the repo hardline below, which is much stricter).
|
||||
- Non-empty body after the closing `---`.
|
||||
|
||||
Peer-matched shape used by every skill under `skills/software-development/`:
|
||||
Repo-standard shape (all fields expected, even where the validator doesn't enforce them):
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: my-skill-name # lowercase, hyphens, ≤64 chars (MAX_NAME_LENGTH)
|
||||
description: Use when <trigger>. <one-line behavior>. # first 57 chars shown in system prompt
|
||||
version: 1.1.0
|
||||
author: Hermes Agent
|
||||
description: Concise capability statement, under sixty chars.
|
||||
version: 0.1.0 # semver; new skills start at 0.1.0
|
||||
author: Real Name (github-handle), Hermes Agent
|
||||
license: MIT
|
||||
platforms: [linux, macos, windows] # audit, don't guess — see Platform Gating
|
||||
metadata:
|
||||
hermes:
|
||||
tags: [short, descriptive, tags]
|
||||
related_skills: [other-skill, another-skill]
|
||||
tags: [Short, Descriptive, Tags]
|
||||
related_skills: [other-in-repo-skill]
|
||||
---
|
||||
```
|
||||
|
||||
`version` / `author` / `license` / `metadata` are NOT enforced by the validator, but every peer has them — omit and your skill sticks out.
|
||||
### `description` rules (HARDLINE — the validator's 1024 is NOT the standard)
|
||||
|
||||
- **≤ 60 characters.** One sentence. Ends with a period.
|
||||
- State the capability, not the implementation, and don't repeat the skill name.
|
||||
- No marketing words ("powerful", "comprehensive", "seamless", "advanced").
|
||||
- The system prompt skill index truncates at 57 chars + "..." — the trigger/capability must be self-contained in that window.
|
||||
- If the description contains a `:`, wrap it in double quotes or YAML parses it as a mapping and the docs generator crashes. Quotes don't count toward the 60.
|
||||
|
||||
Good: `Track named companies for material news with cited digests.`
|
||||
Bad: `Use when a user asks to monitor named competitors or companies for product launches, pricing changes, funding, ...` (240 chars — rejected in review)
|
||||
|
||||
### `author` rules
|
||||
|
||||
- Credit the **human first**, then "Hermes Agent" as secondary collaborator: `Ben Barclay (benbarclay), Hermes Agent`.
|
||||
- Never `author: Hermes Agent` alone for contributed skills — credit the human, not the tool, even (especially) when an agent drafted the text.
|
||||
- Maintainer-authored skills: `Teknium (teknium1), Hermes Agent`.
|
||||
|
||||
### `related_skills` rules
|
||||
|
||||
- Every entry must resolve to an existing **in-repo** skill in the same tree state as your PR. Do not reference skills that were only planned, live in another PR, or exist only in `~/.hermes/skills/`.
|
||||
- Verify each entry: `search_files(pattern='<name>', target='files', path='skills')` (and `optional-skills/`).
|
||||
|
||||
## Platform Gating: audit, don't trust
|
||||
|
||||
`platforms:` gates loading by host OS. Set it from what the skill's prose and scripts actually invoke:
|
||||
|
||||
| Skill uses only… | `platforms:` |
|
||||
|---|---|
|
||||
| Hermes tools + stdlib Python + cross-platform CLIs | `[linux, macos, windows]` |
|
||||
| bash pipelines, `grep`/`awk`/`sed` chains, heredocs | `[linux, macos]` |
|
||||
| `osascript`, `defaults`, `pmset` | `[macos]` |
|
||||
| `apt`/`systemctl`/`/proc` | `[linux]` |
|
||||
|
||||
POSIX-only signals to search for in `scripts/`: `fcntl`, `termios`, `pty`, `os.fork`, `os.killpg`, `signal.SIGKILL`, `os.kill(pid, 0)` liveness checks, hardcoded `/tmp` `/proc` `/etc`. Default posture: fix cross-platform first (`tempfile.gettempdir()`, `pathlib.Path`, `psutil.pid_exists`); gate narrower only when the dependency is genuinely platform-bound, and say why in `## Pitfalls`.
|
||||
|
||||
## Size Limits
|
||||
|
||||
- Description: ≤ 1024 chars (enforced). **Long descriptions render as the first 57 chars
|
||||
plus "..." in the system prompt skill index;** the rest is visible via `skills_list()`
|
||||
and `skill_view()`.
|
||||
- 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.
|
||||
- Full SKILL.md: ≤ 100,000 chars enforced (`MAX_SKILL_CONTENT_CHARS`), but target **~100 lines for a simple skill, ~200 for a complex one**. Peer skills sit at 8-14k chars.
|
||||
- Bulky or branch-specific material goes in `references/*.md`, `templates/`, or `scripts/` — pointed to from SKILL.md, not inlined.
|
||||
- Don't expect the model to inline-write parsers or non-trivial logic every call — ship a helper script in `scripts/` and reference it by path.
|
||||
|
||||
## Body Structure (modern section order)
|
||||
|
||||
```
|
||||
# <Skill> Skill
|
||||
2-3 sentence intro: what it does, what it doesn't do, dependency stance.
|
||||
|
||||
## When to Use — bulleted triggers (+ "Don't use for:" counter-triggers)
|
||||
## Prerequisites — exact env vars, installs, API key sourcing
|
||||
## How to Run — canonical invocation through the `terminal` tool
|
||||
## Quick Reference — flat command list, no narration
|
||||
## Procedure — numbered steps, each with a checkable completion criterion
|
||||
## Pitfalls — known limits, things that look broken but aren't
|
||||
## Verification — how to prove the skill worked
|
||||
```
|
||||
|
||||
Not every section applies to every skill (a pure-procedure task skill may have no Quick Reference), but When to Use + actionable body + Pitfalls + Verification are the minimum. Cut marketing intros, "Setup Check" no-ops, and re-explanations of env vars already in Prerequisites.
|
||||
|
||||
### Reference Hermes tools, not raw shell
|
||||
|
||||
When the skill needs a capability, name the proper Hermes tool in backticks: `terminal`, `read_file`, `write_file`, `patch`, `search_files`, `web_search`, `web_extract`, `browser_navigate`, `vision_analyze`, `delegate_task`, `cronjob`. Do NOT name shell utilities the agent already has wrapped (`grep` → `search_files`, `cat` → `read_file`, `sed`/`awk` → `patch`, `find`/`ls` → `search_files target='files'`). A CLI-wrapper skill should frame invocations as `terminal(command="<tool> ...", timeout=...)` — bare shell prose ("run `foo --version`") is a review-blocking non-conformance. If the skill depends on an MCP server, name it and document setup in Prerequisites.
|
||||
|
||||
### Never use machine-local paths
|
||||
|
||||
Write repo-relative paths (`skills/...`, `tools/skill_manager_tool.py`). A `/home/<you>/...` path baked into a committed skill breaks for every other user and is an instant review flag.
|
||||
|
||||
## Writing Quality Principles
|
||||
|
||||
A skill exists to make the agent's process more predictable. Predictability does **not** mean identical output every run; it means the agent reliably follows the same useful discipline.
|
||||
A skill exists to make the agent's process more predictable — the agent reliably follows the same useful discipline.
|
||||
|
||||
Use these quality checks when writing or editing any skill:
|
||||
1. **Optimize for process predictability.** If a line does not change behavior, cut it.
|
||||
2. **Choose the right context load.** The description is paid for every turn; details go in the body or linked references.
|
||||
3. **End steps with completion criteria.** Checkable and, when it matters, exhaustive: "every modified file accounted for" beats "summarize changes."
|
||||
4. **Co-locate rules with the concept they govern.**
|
||||
5. **Use strong leading words** ("tight loop," "root cause," "regression test") over long repeated explanations.
|
||||
6. **Prune duplication and no-ops.** "Be careful" and "use best practices" don't change model behavior — replace with a checkable criterion or delete.
|
||||
|
||||
1. **Optimize for process predictability.** Ask: what behavior should change when this skill loads? If a line does not change behavior, cut it.
|
||||
2. **Choose the right context load.** A model-invoked Hermes skill pays for its description every turn. Keep descriptions focused on trigger classes and the skill's distinctive behavior. Put details in the body or linked references.
|
||||
3. **Use an information hierarchy.** Put always-needed steps in `SKILL.md`; put branch-specific or bulky reference material in `references/`, `templates/`, or `scripts/` and point to it only when needed.
|
||||
4. **End steps with completion criteria.** Each ordered step should say how the agent knows it is done. Good criteria are checkable and, when it matters, exhaustive: "every modified file accounted for" beats "summarize changes."
|
||||
5. **Co-locate rules with the concept they govern.** Avoid scattering one idea across the file. Keep definition, caveats, examples, and verification near each other.
|
||||
6. **Use strong leading words.** Prefer compact concepts the model already knows — e.g. "tight loop," "tracer bullet," "root cause," "regression test" — over long repeated explanations. A good leading word saves tokens and anchors behavior.
|
||||
7. **Prune duplication and no-ops.** Keep each meaning in one source of truth. Sentence by sentence, ask whether the sentence changes agent behavior versus the default. If not, delete it rather than polishing it.
|
||||
8. **Watch for premature completion.** If agents tend to rush a step, first sharpen that step's completion criterion. Split the sequence only when later steps distract from doing the current step well.
|
||||
## Tests and Docs (required for repo skills)
|
||||
|
||||
Common quality failures:
|
||||
|
||||
- **Premature completion** — the skill lets the agent move on before the work is genuinely done.
|
||||
- **Duplication** — the same rule appears in multiple places and drifts.
|
||||
- **Sediment** — stale lines remain because adding felt safer than deleting.
|
||||
- **Sprawl** — too much always-visible material; push branch-specific reference behind pointers.
|
||||
- **No-op prose** — generic advice the agent would already follow without the skill.
|
||||
|
||||
## 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`, `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.
|
||||
1. **Tests** live at `tests/skills/test_<skill>_skill.py` — stdlib + pytest + `unittest.mock` only, no live network. Run via `scripts/run_tests.sh tests/skills/test_<skill>_skill.py -q`. (The generic `tests/tools/test_skill_manager_tool.py` passing proves nothing about YOUR skill.)
|
||||
2. **Docs regen:** run `python3 website/scripts/generate-skill-docs.py`, then apply scope discipline — the generator rewrites EVERY auto-gen page. `git checkout --` everything that isn't yours; the final diff must show only your SKILL.md, your one per-skill docs page, a one-line catalog row, and a one-line `website/sidebars.ts` insertion (verify with `search_files(pattern='<your-slug>', path='website/sidebars.ts')` — exactly one hit, or the page is an orphan).
|
||||
3. **`.env.example`** (only if the skill needs new env vars): one clearly delimited commented block; touch nothing else in the file.
|
||||
|
||||
## 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`.
|
||||
1. **Survey peers** in the target category with `search_files(target='files')` and read 2-3 peer SKILL.md files to match tone and structure. Prefer extending an existing skill over creating a narrow sibling.
|
||||
2. **Decide tier and category** (see above). When in doubt, optional — and ask before pushing rather than defaulting.
|
||||
3. **Draft** with `write_file` to `skills/<category>/<name>/SKILL.md` (or `optional-skills/...`).
|
||||
4. **Validate locally**:
|
||||
```python
|
||||
import yaml, re, pathlib
|
||||
@@ -148,60 +164,49 @@ Pick the closest existing category. Don't invent new top-level categories casual
|
||||
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(fm["description"]) <= 60, f"description {len(fm['description'])} chars — hardline is 60"
|
||||
assert fm["description"].endswith(".")
|
||||
assert "platforms" in fm
|
||||
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.
|
||||
Also verify every `related_skills` entry exists in-repo.
|
||||
5. **Add tests + regen docs** (previous section).
|
||||
6. **Git add + commit** on the active branch; open a PR.
|
||||
7. **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.
|
||||
|
||||
## 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.
|
||||
- **Small fix:** `skill_manage(action='patch', ...)` works on in-repo skills, as does `patch`.
|
||||
- **Major rewrite:** `write_file` the whole SKILL.md.
|
||||
- **Supporting files:** `write_file` to `references/`, `templates/`, or `scripts/` under the skill dir.
|
||||
- **Always commit** — in-repo skills are source, not runtime state. Re-run the docs generator when frontmatter changed.
|
||||
|
||||
## 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 or trigger buried past char 57.** The system prompt
|
||||
skill index truncates long descriptions at 57 chars. Peer descriptions start
|
||||
with "Use when ..." and complete the trigger class within that window.
|
||||
- Good: `Use when debugging Hermes skill discovery failures.`
|
||||
- Bad: `This skill contains detailed guidance for agents working on Hermes skill discovery failures.`
|
||||
|
||||
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. **Letting skills accumulate sediment.** A skill should get shorter or sharper over time. When adding a rule, remove the old wording it replaces; don't layer advice forever.
|
||||
|
||||
8. **Writing no-op prose.** "Be careful," "be thorough," and "use best practices" rarely change model behavior. Replace with a checkable completion criterion or a stronger leading word.
|
||||
|
||||
9. **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.
|
||||
1. **Using `skill_manage(action='create')` for an in-repo skill.** It writes to `~/.hermes/skills/`, not the repo tree. Use `write_file`.
|
||||
2. **Trusting the validator's limits as the standard.** The validator allows 1024-char descriptions; review rejects anything over 60. The validator doesn't check `platforms:`, author format, tests, or docs — review does.
|
||||
3. **`author: Hermes Agent` on a contributed skill.** Credit the human first.
|
||||
4. **Leading whitespace before `---`.** Validation fails on any leading blank line or BOM.
|
||||
5. **Description too generic or trigger buried past char 57.**
|
||||
6. **`related_skills` pointing at skills that don't exist in-repo** (user-local, planned, or in a sibling PR).
|
||||
7. **Duplicating a peer.** Survey the category first; extend rather than sibling.
|
||||
8. **Skipping the docs generator or pushing its unrelated drift.** Both directions are wrong: no regen = orphan skill with no docs page; blind regen = a ballooned diff full of other skills' drift.
|
||||
9. **Expecting the current session to see the new skill.** The loader is initialized at session start.
|
||||
10. **Letting skills accumulate sediment.** When adding a rule, remove the old wording it replaces.
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
- [ ] File is at `skills/<category>/<name>/SKILL.md` (not in `~/.hermes/skills/`)
|
||||
- [ ] Tier decided deliberately (bundled bar: 5+ sessions/month; else `optional-skills/`)
|
||||
- [ ] File at `skills/<category>/<name>/SKILL.md` or `optional-skills/<category>/<name>/SKILL.md`
|
||||
- [ ] 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, trigger phrase self-contained within first 57 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`
|
||||
- [ ] `name`, `description`, `version`, `author`, `license`, `platforms`, `metadata.hermes.{tags, related_skills}` all present
|
||||
- [ ] Description ≤ 60 chars, one sentence, ends with a period, no marketing words
|
||||
- [ ] `author` credits the human contributor first
|
||||
- [ ] `platforms:` audited against actual prose/scripts, not copied from a sibling
|
||||
- [ ] Every `related_skills` entry resolves in-repo
|
||||
- [ ] Body follows the modern section order; commands framed through Hermes tools
|
||||
- [ ] No machine-local paths anywhere in the file
|
||||
- [ ] Each ordered step has a checkable completion criterion
|
||||
- [ ] Description is trigger-focused and avoids duplicated body content
|
||||
- [ ] Bulky or branch-specific reference is progressively disclosed in linked files
|
||||
- [ ] No-op prose and duplicated rules removed
|
||||
- [ ] `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
|
||||
- [ ] Tests at `tests/skills/test_<skill>_skill.py` pass under `scripts/run_tests.sh`
|
||||
- [ ] Docs regenerated with scope discipline; sidebar has exactly one entry for the slug
|
||||
- [ ] `git add` + commit on the intended branch; PR opened
|
||||
|
||||
Reference in New Issue
Block a user