[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7892DDKHT2T2PSFY0KZPRXM":3,"skill-same:01M7892DDKHT2T2PSFY0KZPRXM":62},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":41,"commitSha":42,"skillDirectory":43,"forksCount":14,"repositoryHtmlUrl":44,"repositoryHomepageUrl":6,"ownerHtmlUrl":45,"ownerBlogUrl":6,"ownerDescription":46,"updatedAt":47,"install":48,"resources":61},"01M7892DDKHT2T2PSFY0KZPRXM","hermes-agent-skill-authoring",null,"Author in-repo SKILL.md files: frontmatter and structure.","abdullibrahim733-pixel\u002FEagle","abdullibrahim733-pixel","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F230504522?v=4","01M787SK0DQR0H1K326DJT6EBK","ibrahim abdull","01M787SK1HWS9V959THKZM6N70",0,"MIT","https:\u002F\u002Fgithub.com\u002Fabdullibrahim733-pixel\u002FEagle\u002Fblob\u002Fmain\u002Fhermes-backup\u002Fprofiles\u002Fbrad_marketing\u002Fskills\u002Fsoftware-development\u002Fhermes-agent-skill-authoring\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: hermes-agent-skill-authoring\ndescription: \"Author in-repo SKILL.md files: frontmatter and structure.\"\nversion: 2.0.0\nauthor: Hermes Agent\nlicense: MIT\nplatforms: [linux, macos, windows]\nmetadata:\n  hermes:\n    tags: [skills, authoring, hermes-agent, conventions, skill-md]\n    related_skills: [plan, requesting-code-review]\n---\n\n# Authoring Hermes-Agent Skills (in-repo)\n\n## Overview\n\nThere are two places a SKILL.md can live:\n\n1. **User-local:** `~\u002F.hermes\u002Fskills\u002F\u003Cmaybe-category>\u002F\u003Cname>\u002FSKILL.md` — personal, not shared. Created via `skill_manage(action='create')`.\n2. **In-repo (this skill is about this case):** `skills\u002F\u003Ccategory>\u002F\u003Cname>\u002FSKILL.md` or `optional-skills\u002F\u003Ccategory>\u002F\u003Cname>\u002FSKILL.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.\n\nIn-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.\n\n## When to Use\n\n- User asks you to add a skill \"in this branch \u002F repo \u002F commit\"\n- You're committing a reusable workflow that should ship with hermes-agent\n- You're editing an existing skill under `skills\u002F` or `optional-skills\u002F` (use `patch` for small edits, `write_file` for rewrites; `skill_manage` still works for patch on in-repo skills, but not for `create`)\n- Don't use for: personal skills in `~\u002F.hermes\u002Fskills\u002F` (just use `skill_manage`)\n\n## Decide the Tier First: Bundled vs Optional\n\n- **Bundled (`skills\u002F\u003Ccategory>\u002F`)** — 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.\n- **Optional (`optional-skills\u002F\u003Ccategory>\u002F`)** — niche, vertical-specific (blockchain, gaming, finance, one app), recurring-job\u002Ftask skills, or anything heavy. Installed via `hermes skills install official\u002F\u003Ccategory>\u002F\u003Cskill>`.\n\n**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.\n\nPick the category by what the tool IS, not what it feels like (an AI-agent CLI goes in `autonomous-ai-agents\u002F` 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.\n\n**No router \u002F index \u002F 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.\n\n## Required Frontmatter\n\nValidator source of truth: `tools\u002Fskill_manager_tool.py::_validate_frontmatter`. Validator hard requirements:\n\n- Starts with `---` as the first bytes (no leading blank line).\n- Closes with `\\n---\\n` before the body.\n- Parses as a YAML mapping.\n- `name` field present.\n- `description` field present (validator ceiling 1024 chars — but see the repo hardline below, which is much stricter).\n- Non-empty body after the closing `---`.\n\nRepo-standard shape (all fields expected, even where the validator doesn't enforce them):\n\n```yaml\n---\nname: my-skill-name               # lowercase, hyphens, ≤64 chars (MAX_NAME_LENGTH)\ndescription: Concise capability statement, under sixty chars.\nversion: 0.1.0                    # semver; new skills start at 0.1.0\nauthor: Real Name (github-handle), Hermes Agent\nlicense: MIT\nplatforms: [linux, macos, windows]   # audit, don't guess — see Platform Gating\nmetadata:\n  hermes:\n    tags: [Short, Descriptive, Tags]\n    related_skills: [other-in-repo-skill]\n---\n```\n\n### `description` rules (HARDLINE — the validator's 1024 is NOT the standard)\n\n- **≤ 60 characters.** One sentence. Ends with a period.\n- State the capability, not the implementation, and don't repeat the skill name.\n- No marketing words (\"powerful\", \"comprehensive\", \"seamless\", \"advanced\").\n- The system prompt skill index truncates at 57 chars + \"...\" — the trigger\u002Fcapability must be self-contained in that window.\n- 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.\n\nGood: `Track named companies for material news with cited digests.`\nBad: `Use when a user asks to monitor named competitors or companies for product launches, pricing changes, funding, ...` (240 chars — rejected in review)\n\n### `author` rules\n\n- Credit the **human first**, then \"Hermes Agent\" as secondary collaborator: `Ben Barclay (benbarclay), Hermes Agent`.\n- Never `author: Hermes Agent` alone for contributed skills — credit the human, not the tool, even (especially) when an agent drafted the text.\n- Maintainer-authored skills: `Teknium (teknium1), Hermes Agent`.\n\n### `related_skills` rules\n\n- 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 `~\u002F.hermes\u002Fskills\u002F`.\n- Verify each entry: `search_files(pattern='\u003Cname>', target='files', path='skills')` (and `optional-skills\u002F`).\n\n## Platform Gating: audit, don't trust\n\n`platforms:` gates loading by host OS. Set it from what the skill's prose and scripts actually invoke:\n\n| Skill uses only… | `platforms:` |\n|---|---|\n| Hermes tools + stdlib Python + cross-platform CLIs | `[linux, macos, windows]` |\n| bash pipelines, `grep`\u002F`awk`\u002F`sed` chains, heredocs | `[linux, macos]` |\n| `osascript`, `defaults`, `pmset` | `[macos]` |\n| `apt`\u002F`systemctl`\u002F`\u002Fproc` | `[linux]` |\n\nPOSIX-only signals to search for in `scripts\u002F`: `fcntl`, `termios`, `pty`, `os.fork`, `os.killpg`, `signal.SIGKILL`, `os.kill(pid, 0)` liveness checks, hardcoded `\u002Ftmp` `\u002Fproc` `\u002Fetc`. 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`.\n\n## Size Limits\n\n- 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.\n- Bulky or branch-specific material goes in `references\u002F*.md`, `templates\u002F`, or `scripts\u002F` — pointed to from SKILL.md, not inlined.\n- Don't expect the model to inline-write parsers or non-trivial logic every call — ship a helper script in `scripts\u002F` and reference it by path.\n\n## Body Structure (modern section order)\n\n```\n# \u003CSkill> Skill\n2-3 sentence intro: what it does, what it doesn't do, dependency stance.\n\n## When to Use          — bulleted triggers (+ \"Don't use for:\" counter-triggers)\n## Prerequisites        — exact env vars, installs, API key sourcing\n## How to Run           — canonical invocation through the `terminal` tool\n## Quick Reference      — flat command list, no narration\n## Procedure            — numbered steps, each with a checkable completion criterion\n## Pitfalls             — known limits, things that look broken but aren't\n## Verification         — how to prove the skill worked\n```\n\nNot 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.\n\n### Reference Hermes tools, not raw shell\n\nWhen 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`\u002F`awk` → `patch`, `find`\u002F`ls` → `search_files target='files'`). A CLI-wrapper skill should frame invocations as `terminal(command=\"\u003Ctool> ...\", 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.\n\n### Never use machine-local paths\n\nWrite repo-relative paths (`skills\u002F...`, `tools\u002Fskill_manager_tool.py`). A `\u002Fhome\u002F\u003Cyou>\u002F...` path baked into a committed skill breaks for every other user and is an instant review flag.\n\n## Writing Quality Principles\n\nA skill exists to make the agent's process more predictable — the agent reliably follows the same useful discipline.\n\n1. **Optimize for process predictability.** If a line does not change behavior, cut it.\n2. **Choose the right context load.** The description is paid for every turn; details go in the body or linked references.\n3. **End steps with completion criteria.** Checkable and, when it matters, exhaustive: \"every modified file accounted for\" beats \"summarize changes.\"\n4. **Co-locate rules with the concept they govern.**\n5. **Use strong leading words** (\"tight loop,\" \"root cause,\" \"regression test\") over long repeated explanations.\n6. **Prune duplication and no-ops.** \"Be careful\" and \"use best practices\" don't change model behavior — replace with a checkable criterion or delete.\n\n## Tests and Docs (required for repo skills)\n\n1. **Tests** live at `tests\u002Fskills\u002Ftest_\u003Cskill>_skill.py` — stdlib + pytest + `unittest.mock` only, no live network. Run via `scripts\u002Frun_tests.sh tests\u002Fskills\u002Ftest_\u003Cskill>_skill.py -q`. (The generic `tests\u002Ftools\u002Ftest_skill_manager_tool.py` passing proves nothing about YOUR skill.)\n2. **Docs regen:** run `python website\u002Fscripts\u002Fgenerate-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\u002Fsidebars.ts` insertion (verify with `search_files(pattern='\u003Cyour-slug>', path='website\u002Fsidebars.ts')` — exactly one hit, or the page is an orphan).\n3. **`.env.example`** (only if the skill needs new env vars): one clearly delimited commented block; touch nothing else in the file.\n\n## Workflow\n\n1. **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.\n2. **Decide tier and category** (see above). When in doubt, optional — and ask before pushing rather than defaulting.\n3. **Draft** with `write_file` to `skills\u002F\u003Ccategory>\u002F\u003Cname>\u002FSKILL.md` (or `optional-skills\u002F...`).\n4. **Validate locally**:\n   ```python\n   import yaml, re, pathlib\n   content = pathlib.Path(\"skills\u002F\u003Ccategory>\u002F\u003Cname>\u002FSKILL.md\").read_text()\n   assert content.startswith(\"---\")\n   m = re.search(r'\\n---\\s*\\n', content[3:])\n   fm = yaml.safe_load(content[3:m.start()+3])\n   assert \"name\" in fm and \"description\" in fm\n   assert len(fm[\"description\"]) \u003C= 60, f\"description {len(fm['description'])} chars — hardline is 60\"\n   assert fm[\"description\"].endswith(\".\")\n   assert \"platforms\" in fm\n   assert len(content) \u003C= 100_000\n   ```\n   Also verify every `related_skills` entry exists in-repo.\n5. **Add tests + regen docs** (previous section).\n6. **Git add + commit** on the active branch; open a PR.\n7. **Note:** the CURRENT session's skill loader is cached — `skill_view` \u002F `skills_list` will not see the new skill until a new session. This is expected, not a bug.\n\n## Editing Existing In-Repo Skills\n\n- **Small fix:** `skill_manage(action='patch', ...)` works on in-repo skills, as does `patch`.\n- **Major rewrite:** `write_file` the whole SKILL.md.\n- **Supporting files:** `write_file` to `references\u002F`, `templates\u002F`, or `scripts\u002F` under the skill dir.\n- **Always commit** — in-repo skills are source, not runtime state. Re-run the docs generator when frontmatter changed.\n\n## Common Pitfalls\n\n1. **Using `skill_manage(action='create')` for an in-repo skill.** It writes to `~\u002F.hermes\u002Fskills\u002F`, not the repo tree. Use `write_file`.\n2. **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.\n3. **`author: Hermes Agent` on a contributed skill.** Credit the human first.\n4. **Leading whitespace before `---`.** Validation fails on any leading blank line or BOM.\n5. **Description too generic or trigger buried past char 57.**\n6. **`related_skills` pointing at skills that don't exist in-repo** (user-local, planned, or in a sibling PR).\n7. **Duplicating a peer.** Survey the category first; extend rather than sibling.\n8. **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.\n9. **Expecting the current session to see the new skill.** The loader is initialized at session start.\n10. **Letting skills accumulate sediment.** When adding a rule, remove the old wording it replaces.\n\n## Verification Checklist\n\n- [ ] Tier decided deliberately (bundled bar: 5+ sessions\u002Fmonth; else `optional-skills\u002F`)\n- [ ] File at `skills\u002F\u003Ccategory>\u002F\u003Cname>\u002FSKILL.md` or `optional-skills\u002F\u003Ccategory>\u002F\u003Cname>\u002FSKILL.md`\n- [ ] Frontmatter starts at byte 0 with `---`, closes with `\\n---\\n`\n- [ ] `name`, `description`, `version`, `author`, `license`, `platforms`, `metadata.hermes.{tags, related_skills}` all present\n- [ ] Description ≤ 60 chars, one sentence, ends with a period, no marketing words\n- [ ] `author` credits the human contributor first\n- [ ] `platforms:` audited against actual prose\u002Fscripts, not copied from a sibling\n- [ ] Every `related_skills` entry resolves in-repo\n- [ ] Body follows the modern section order; commands framed through Hermes tools\n- [ ] No machine-local paths anywhere in the file\n- [ ] Each ordered step has a checkable completion criterion\n- [ ] Tests at `tests\u002Fskills\u002Ftest_\u003Cskill>_skill.py` pass under `scripts\u002Frun_tests.sh`\n- [ ] Docs regenerated with scope discipline; sidebar has exactly one entry for the slug\n- [ ] `git add` + commit on the intended branch; PR opened\n","# Authoring Hermes-Agent Skills (in-repo)\n\n## Overview\n\nThere are two places a SKILL.md can live:\n\n1. **User-local:** `~\u002F.hermes\u002Fskills\u002F\u003Cmaybe-category>\u002F\u003Cname>\u002FSKILL.md` — personal, not shared. Created via `skill_manage(action='create')`.\n2. **In-repo (this skill is about this case):** `skills\u002F\u003Ccategory>\u002F\u003Cname>\u002FSKILL.md` or `optional-skills\u002F\u003Ccategory>\u002F\u003Cname>\u002FSKILL.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.\n\nIn-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.\n\n## When to Use\n\n- User asks you to add a skill \"in this branch \u002F repo \u002F commit\"\n- You're committing a reusable workflow that should ship with hermes-agent\n- You're editing an existing skill under `skills\u002F` or `optional-skills\u002F` (use `patch` for small edits, `write_file` for rewrites; `skill_manage` still works for patch on in-repo skills, but not for `create`)\n- Don't use for: personal skills in `~\u002F.hermes\u002Fskills\u002F` (just use `skill_manage`)\n\n## Decide the Tier First: Bundled vs Optional\n\n- **Bundled (`skills\u002F\u003Ccategory>\u002F`)** — 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.\n- **Optional (`optional-skills\u002F\u003Ccategory>\u002F`)** — niche, vertical-specific (blockchain, gaming, finance, one app), recurring-job\u002Ftask skills, or anything heavy. Installed via `hermes skills install official\u002F\u003Ccategory>\u002F\u003Cskill>`.\n\n**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.\n\nPick the category by what the tool IS, not what it feels like (an AI-agent CLI goes in `autonomous-ai-agents\u002F` 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.\n\n**No router \u002F index \u002F 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.\n\n## Required Frontmatter\n\nValidator source of truth: `tools\u002Fskill_manager_tool.py::_validate_frontmatter`. Validator hard requirements:\n\n- Starts with `---` as the first bytes (no leading blank line).\n- Closes with `\\n---\\n` before the body.\n- Parses as a YAML mapping.\n- `name` field present.\n- `description` field present (validator ceiling 1024 chars — but see the repo hardline below, which is much stricter).\n- Non-empty body after the closing `---`.\n\nRepo-standard shape (all fields expected, even where the validator doesn't enforce them):\n\n```yaml\n---\nname: my-skill-name               # lowercase, hyphens, ≤64 chars (MAX_NAME_LENGTH)\ndescription: Concise capability statement, under sixty chars.\nversion: 0.1.0                    # semver; new skills start at 0.1.0\nauthor: Real Name (github-handle), Hermes Agent\nlicense: MIT\nplatforms: [linux, macos, windows]   # audit, don't guess — see Platform Gating\nmetadata:\n  hermes:\n    tags: [Short, Descriptive, Tags]\n    related_skills: [other-in-repo-skill]\n---\n```\n\n### `description` rules (HARDLINE — the validator's 1024 is NOT the standard)\n\n- **≤ 60 characters.** One sentence. Ends with a period.\n- State the capability, not the implementation, and don't repeat the skill name.\n- No marketing words (\"powerful\", \"comprehensive\", \"seamless\", \"advanced\").\n- The system prompt skill index truncates at 57 chars + \"...\" — the trigger\u002Fcapability must be self-contained in that window.\n- 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.\n\nGood: `Track named companies for material news with cited digests.`\nBad: `Use when a user asks to monitor named competitors or companies for product launches, pricing changes, funding, ...` (240 chars — rejected in review)\n\n### `author` rules\n\n- Credit the **human first**, then \"Hermes Agent\" as secondary collaborator: `Ben Barclay (benbarclay), Hermes Agent`.\n- Never `author: Hermes Agent` alone for contributed skills — credit the human, not the tool, even (especially) when an agent drafted the text.\n- Maintainer-authored skills: `Teknium (teknium1), Hermes Agent`.\n\n### `related_skills` rules\n\n- 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 `~\u002F.hermes\u002Fskills\u002F`.\n- Verify each entry: `search_files(pattern='\u003Cname>', target='files', path='skills')` (and `optional-skills\u002F`).\n\n## Platform Gating: audit, don't trust\n\n`platforms:` gates loading by host OS. Set it from what the skill's prose and scripts actually invoke:\n\n| Skill uses only… | `platforms:` |\n|---|---|\n| Hermes tools + stdlib Python + cross-platform CLIs | `[linux, macos, windows]` |\n| bash pipelines, `grep`\u002F`awk`\u002F`sed` chains, heredocs | `[linux, macos]` |\n| `osascript`, `defaults`, `pmset` | `[macos]` |\n| `apt`\u002F`systemctl`\u002F`\u002Fproc` | `[linux]` |\n\nPOSIX-only signals to search for in `scripts\u002F`: `fcntl`, `termios`, `pty`, `os.fork`, `os.killpg`, `signal.SIGKILL`, `os.kill(pid, 0)` liveness checks, hardcoded `\u002Ftmp` `\u002Fproc` `\u002Fetc`. 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`.\n\n## Size Limits\n\n- 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.\n- Bulky or branch-specific material goes in `references\u002F*.md`, `templates\u002F`, or `scripts\u002F` — pointed to from SKILL.md, not inlined.\n- Don't expect the model to inline-write parsers or non-trivial logic every call — ship a helper script in `scripts\u002F` and reference it by path.\n\n## Body Structure (modern section order)\n\n```\n# \u003CSkill> Skill\n2-3 sentence intro: what it does, what it doesn't do, dependency stance.\n\n## When to Use          — bulleted triggers (+ \"Don't use for:\" counter-triggers)\n## Prerequisites        — exact env vars, installs, API key sourcing\n## How to Run           — canonical invocation through the `terminal` tool\n## Quick Reference      — flat command list, no narration\n## Procedure            — numbered steps, each with a checkable completion criterion\n## Pitfalls             — known limits, things that look broken but aren't\n## Verification         — how to prove the skill worked\n```\n\nNot 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.\n\n### Reference Hermes tools, not raw shell\n\nWhen 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`\u002F`awk` → `patch`, `find`\u002F`ls` → `search_files target='files'`). A CLI-wrapper skill should frame invocations as `terminal(command=\"\u003Ctool> ...\", 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.\n\n### Never use machine-local paths\n\nWrite repo-relative paths (`skills\u002F...`, `tools\u002Fskill_manager_tool.py`). A `\u002Fhome\u002F\u003Cyou>\u002F...` path baked into a committed skill breaks for every other user and is an instant review flag.\n\n## Writing Quality Principles\n\nA skill exists to make the agent's process more predictable — the agent reliably follows the same useful discipline.\n\n1. **Optimize for process predictability.** If a line does not change behavior, cut it.\n2. **Choose the right context load.** The description is paid for every turn; details go in the body or linked references.\n3. **End steps with completion criteria.** Checkable and, when it matters, exhaustive: \"every modified file accounted for\" beats \"summarize changes.\"\n4. **Co-locate rules with the concept they govern.**\n5. **Use strong leading words** (\"tight loop,\" \"root cause,\" \"regression test\") over long repeated explanations.\n6. **Prune duplication and no-ops.** \"Be careful\" and \"use best practices\" don't change model behavior — replace with a checkable criterion or delete.\n\n## Tests and Docs (required for repo skills)\n\n1. **Tests** live at `tests\u002Fskills\u002Ftest_\u003Cskill>_skill.py` — stdlib + pytest + `unittest.mock` only, no live network. Run via `scripts\u002Frun_tests.sh tests\u002Fskills\u002Ftest_\u003Cskill>_skill.py -q`. (The generic `tests\u002Ftools\u002Ftest_skill_manager_tool.py` passing proves nothing about YOUR skill.)\n2. **Docs regen:** run `python website\u002Fscripts\u002Fgenerate-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\u002Fsidebars.ts` insertion (verify with `search_files(pattern='\u003Cyour-slug>', path='website\u002Fsidebars.ts')` — exactly one hit, or the page is an orphan).\n3. **`.env.example`** (only if the skill needs new env vars): one clearly delimited commented block; touch nothing else in the file.\n\n## Workflow\n\n1. **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.\n2. **Decide tier and category** (see above). When in doubt, optional — and ask before pushing rather than defaulting.\n3. **Draft** with `write_file` to `skills\u002F\u003Ccategory>\u002F\u003Cname>\u002FSKILL.md` (or `optional-skills\u002F...`).\n4. **Validate locally**:\n   ```python\n   import yaml, re, pathlib\n   content = pathlib.Path(\"skills\u002F\u003Ccategory>\u002F\u003Cname>\u002FSKILL.md\").read_text()\n   assert content.startswith(\"---\")\n   m = re.search(r'\\n---\\s*\\n', content[3:])\n   fm = yaml.safe_load(content[3:m.start()+3])\n   assert \"name\" in fm and \"description\" in fm\n   assert len(fm[\"description\"]) \u003C= 60, f\"description {len(fm['description'])} chars — hardline is 60\"\n   assert fm[\"description\"].endswith(\".\")\n   assert \"platforms\" in fm\n   assert len(content) \u003C= 100_000\n   ```\n   Also verify every `related_skills` entry exists in-repo.\n5. **Add tests + regen docs** (previous section).\n6. **Git add + commit** on the active branch; open a PR.\n7. **Note:** the CURRENT session's skill loader is cached — `skill_view` \u002F `skills_list` will not see the new skill until a new session. This is expected, not a bug.\n\n## Editing Existing In-Repo Skills\n\n- **Small fix:** `skill_manage(action='patch', ...)` works on in-repo skills, as does `patch`.\n- **Major rewrite:** `write_file` the whole SKILL.md.\n- **Supporting files:** `write_file` to `references\u002F`, `templates\u002F`, or `scripts\u002F` under the skill dir.\n- **Always commit** — in-repo skills are source, not runtime state. Re-run the docs generator when frontmatter changed.\n\n## Common Pitfalls\n\n1. **Using `skill_manage(action='create')` for an in-repo skill.** It writes to `~\u002F.hermes\u002Fskills\u002F`, not the repo tree. Use `write_file`.\n2. **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.\n3. **`author: Hermes Agent` on a contributed skill.** Credit the human first.\n4. **Leading whitespace before `---`.** Validation fails on any leading blank line or BOM.\n5. **Description too generic or trigger buried past char 57.**\n6. **`related_skills` pointing at skills that don't exist in-repo** (user-local, planned, or in a sibling PR).\n7. **Duplicating a peer.** Survey the category first; extend rather than sibling.\n8. **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.\n9. **Expecting the current session to see the new skill.** The loader is initialized at session start.\n10. **Letting skills accumulate sediment.** When adding a rule, remove the old wording it replaces.\n\n## Verification Checklist\n\n- [ ] Tier decided deliberately (bundled bar: 5+ sessions\u002Fmonth; else `optional-skills\u002F`)\n- [ ] File at `skills\u002F\u003Ccategory>\u002F\u003Cname>\u002FSKILL.md` or `optional-skills\u002F\u003Ccategory>\u002F\u003Cname>\u002FSKILL.md`\n- [ ] Frontmatter starts at byte 0 with `---`, closes with `\\n---\\n`\n- [ ] `name`, `description`, `version`, `author`, `license`, `platforms`, `metadata.hermes.{tags, related_skills}` all present\n- [ ] Description ≤ 60 chars, one sentence, ends with a period, no marketing words\n- [ ] `author` credits the human contributor first\n- [ ] `platforms:` audited against actual prose\u002Fscripts, not copied from a sibling\n- [ ] Every `related_skills` entry resolves in-repo\n- [ ] Body follows the modern section order; commands framed through Hermes tools\n- [ ] No machine-local paths anywhere in the file\n- [ ] Each ordered step has a checkable completion criterion\n- [ ] Tests at `tests\u002Fskills\u002Ftest_\u003Cskill>_skill.py` pass under `scripts\u002Frun_tests.sh`\n- [ ] Docs regenerated with scope discipline; sidebar has exactly one entry for the slug\n- [ ] `git add` + commit on the intended branch; PR opened\n",{"name":5,"author":24,"license":15,"version":25,"metadata":26,"platforms":37,"description":7},"Hermes Agent","2.0.0",{"hermes":27},{"tags":28,"related_skills":34},[29,30,31,32,33],"skills","authoring","hermes-agent","conventions","skill-md",[35,36],"plan","requesting-code-review",[38,39,40],"linux","macos","windows","main","1f420fcb3f20524e8a830b9d010e0c0ee312d437","hermes-backup\u002Fprofiles\u002Fbrad_marketing\u002Fskills\u002Fsoftware-development\u002Fhermes-agent-skill-authoring","https:\u002F\u002Fgithub.com\u002Fabdullibrahim733-pixel\u002FEagle","https:\u002F\u002Fgithub.com\u002Fabdullibrahim733-pixel","I am a developer at UMG Africa and i have 2 years of software development also i engage with embedded softwares i am good in rust, cpp, python and kotlin","2026-08-16 18:04:02",{"source":8,"skillName":5,"commands":49,"prompt":59,"zipAvailable":60},[50,53,56],{"tool":51,"command":52},"npx","npx skills add abdullibrahim733-pixel\u002FEagle --skill hermes-agent-skill-authoring",{"tool":54,"command":55},"bunx","bunx skills add abdullibrahim733-pixel\u002FEagle --skill hermes-agent-skill-authoring",{"tool":57,"command":58},"pnpm","pnpm dlx skills add abdullibrahim733-pixel\u002FEagle --skill hermes-agent-skill-authoring","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fabdullibrahim733-pixel\u002FEagle\u002Fblob\u002Fmain\u002Fhermes-backup\u002Fprofiles\u002Fbrad_marketing\u002Fskills\u002Fsoftware-development\u002Fhermes-agent-skill-authoring\u002FSKILL.md",true,[],[63,70,77,84,91,98],{"skillNo":64,"name":65,"nameZh":6,"description":66,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":67,"categories":68,"keywords":69,"publishedAt":19},"01M78BBHAQCSZNG7HYMB97YG3Y","web-ui-verification","Verify web UIs via headless Chrome CDP, no vision needed.","https:\u002F\u002Fgithub.com\u002Fabdullibrahim733-pixel\u002FEagle\u002Fblob\u002Fmain\u002Fhermes-backup\u002Fskills\u002Fsoftware-development\u002Fweb-ui-verification\u002FSKILL.md",[],[],{"skillNo":71,"name":72,"nameZh":6,"description":73,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":74,"categories":75,"keywords":76,"publishedAt":19},"01M78BB60RHXBY2QV4TA9S917B","test-driven-development","TDD: enforce RED-GREEN-REFACTOR, tests before code.","https:\u002F\u002Fgithub.com\u002Fabdullibrahim733-pixel\u002FEagle\u002Fblob\u002Fmain\u002Fhermes-backup\u002Fskills\u002Fsoftware-development\u002Ftest-driven-development\u002FSKILL.md",[],[],{"skillNo":78,"name":79,"nameZh":6,"description":80,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":81,"categories":82,"keywords":83,"publishedAt":19},"01M78BB16QRJZA9P3TXN5SHCQH","systematic-debugging","4-phase root cause debugging: understand bugs before fixing.","https:\u002F\u002Fgithub.com\u002Fabdullibrahim733-pixel\u002FEagle\u002Fblob\u002Fmain\u002Fhermes-backup\u002Fskills\u002Fsoftware-development\u002Fsystematic-debugging\u002FSKILL.md",[],[],{"skillNo":85,"name":86,"nameZh":6,"description":87,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":88,"categories":89,"keywords":90,"publishedAt":19},"01M78BAY69B9JP3SK2NAF3EH2D","spike","Throwaway experiments to validate an idea before build.","https:\u002F\u002Fgithub.com\u002Fabdullibrahim733-pixel\u002FEagle\u002Fblob\u002Fmain\u002Fhermes-backup\u002Fskills\u002Fsoftware-development\u002Fspike\u002FSKILL.md",[],[],{"skillNo":92,"name":93,"nameZh":6,"description":94,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":95,"categories":96,"keywords":97,"publishedAt":19},"01M78BAVDMEBYN49PRDQ8QXTBJ","simplify-code","Parallel 4-agent cleanup of recent code changes.","https:\u002F\u002Fgithub.com\u002Fabdullibrahim733-pixel\u002FEagle\u002Fblob\u002Fmain\u002Fhermes-backup\u002Fskills\u002Fsoftware-development\u002Fsimplify-code\u002FSKILL.md",[],[],{"skillNo":99,"name":100,"nameZh":6,"description":101,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":102,"categories":103,"keywords":104,"publishedAt":19},"01M78BAE09PQ5RV5MSJN1S788A","scroll-driven-3d-websites","Scroll-scrubbed 3D promo sites (Three.js + GSAP).","https:\u002F\u002Fgithub.com\u002Fabdullibrahim733-pixel\u002FEagle\u002Fblob\u002Fmain\u002Fhermes-backup\u002Fskills\u002Fsoftware-development\u002Fscroll-driven-3d-websites\u002FSKILL.md",[],[]]