better-dsh 0.2.5 → 0.3.0-c

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/bundled/software-development/software-development-codebase-inspection.md

@@ -1,132 +0,0 @@
----
-title: "Codebase Inspection — Inspect codebases w/ pygount: LOC, languages, ratios"
-sidebar_label: "Codebase Inspection"
-description: "Inspect codebases w/ pygount: LOC, languages, ratios"
----
-
-{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
-
-# Codebase Inspection
-
-Inspect codebases w/ pygount: LOC, languages, ratios.
-
-## Skill metadata
-
-| | |
-|---|---|
-| Source | Bundled (installed by default) |
-| Path | `skills/software-development\codebase-inspection` |
-| Version | `1.0.0` |
-| Author | Hermes Agent |
-| License | MIT |
-| Platforms | linux, macos, windows |
-| Tags | `LOC`, `Code Analysis`, `pygount`, `Codebase`, `Metrics`, `Repository` |
-| Related skills | [`github`](/docs/user-guide/skills/bundled/software-development/software-development-github) |
-
-## Reference: full SKILL.md
-
-:::info
-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
-:::
-
-# Codebase Inspection with pygount
-
-Analyze repositories for lines of code, language breakdown, file counts, and code-vs-comment ratios using `pygount`.
-
-## When to Use
-
-- User asks for LOC (lines of code) count
-- User wants a language breakdown of a repo
-- User asks about codebase size or composition
-- User wants code-vs-comment ratios
-- General "how big is this repo" questions
-
-## Prerequisites
-
-```bash
-pip install --break-system-packages pygount 2>/dev/null || pip install pygount
-```
-
-## 1. Basic Summary (Most Common)
-
-Get a full language breakdown with file counts, code lines, and comment lines:
-
-```bash
-cd /path/to/repo
-pygount --format=summary \
-  --folders-to-skip=".git,node_modules,venv,.venv,__pycache__,.cache,dist,build,.next,.tox,.eggs,*.egg-info" \
-  .
-```
-
-**IMPORTANT:** Always use `--folders-to-skip` to exclude dependency/build directories, otherwise pygount will crawl them and take a very long time or hang.
-
-## 2. Common Folder Exclusions
-
-Adjust based on the project type:
-
-```bash
-# Python projects
---folders-to-skip=".git,venv,.venv,__pycache__,.cache,dist,build,.tox,.eggs,.mypy_cache"
-
-# JavaScript/TypeScript projects
---folders-to-skip=".git,node_modules,dist,build,.next,.cache,.turbo,coverage"
-
-# General catch-all
---folders-to-skip=".git,node_modules,venv,.venv,__pycache__,.cache,dist,build,.next,.tox,vendor,third_party"
-```
-
-## 3. Filter by Specific Language
-
-```bash
-# Only count Python files
-pygount --suffix=py --format=summary .
-
-# Only count Python and YAML
-pygount --suffix=py,yaml,yml --format=summary .
-```
-
-## 4. Detailed File-by-File Output
-
-```bash
-# Default format shows per-file breakdown
-pygount --folders-to-skip=".git,node_modules,venv" .
-
-# Sort by code lines (pipe through sort)
-pygount --folders-to-skip=".git,node_modules,venv" . | sort -t$'\t' -k1 -nr | head -20
-```
-
-## 5. Output Formats
-
-```bash
-# Summary table (default recommendation)
-pygount --format=summary .
-
-# JSON output for programmatic use
-pygount --format=json .
-
-# Pipe-friendly: Language, file count, code, docs, empty, string
-pygount --format=summary . 2>/dev/null
-```
-
-## 6. Interpreting Results
-
-The summary table columns:
-- **Language** — detected programming language
-- **Files** — number of files of that language
-- **Code** — lines of actual code (executable/declarative)
-- **Comment** — lines that are comments or documentation
-- **%** — percentage of total
-
-Special pseudo-languages:
-- `__empty__` — empty files
-- `__binary__` — binary files (images, compiled, etc.)
-- `__generated__` — auto-generated files (detected heuristically)
-- `__duplicate__` — files with identical content
-- `__unknown__` — unrecognized file types
-
-## Pitfalls
-
-1. **Always exclude .git, node_modules, venv** — without `--folders-to-skip`, pygount will crawl everything and may take minutes or hang on large dependency trees.
-2. **Markdown shows 0 code lines** — pygount classifies all Markdown content as comments, not code. This is expected behavior.
-3. **JSON files show low code counts** — pygount may count JSON lines conservatively. For accurate JSON line counts, use `wc -l` directly.
-4. **Large monorepos** — for very large repos, consider using `--suffix` to target specific languages rather than scanning everything.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/bundled/software-development/software-development-dogfood.md

@@ -1,183 +0,0 @@
----
-title: "Dogfood — Exploratory QA of web apps: find bugs, evidence, reports"
-sidebar_label: "Dogfood"
-description: "Exploratory QA of web apps: find bugs, evidence, reports"
----
-
-{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
-
-# Dogfood
-
-Exploratory QA of web apps: find bugs, evidence, reports.
-
-## Skill metadata
-
-| | |
-|---|---|
-| Source | Bundled (installed by default) |
-| Path | `skills/software-development\dogfood` |
-| Version | `1.0.0` |
-| Author | Teknium (teknium1), Hermes Agent |
-| License | MIT |
-| Platforms | linux, macos, windows |
-| Tags | `qa`, `testing`, `browser`, `web`, `dogfood` |
-
-## Reference: full SKILL.md
-
-:::info
-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
-:::
-
-# Dogfood: Systematic Web Application QA Testing
-
-## Overview
-
-This skill guides you through systematic exploratory QA testing of web applications using the browser toolset. You will navigate the application, interact with elements, capture evidence of issues, and produce a structured bug report.
-
-## Prerequisites
-
-- Browser toolset must be available (`browser_navigate`, `browser_snapshot`, `browser_click`, `browser_type`, `browser_vision`, `browser_console`, `browser_scroll`, `browser_back`, `browser_press`)
-- A target URL and testing scope from the user
-
-## Inputs
-
-The user provides:
-1. **Target URL** — the entry point for testing
-2. **Scope** — what areas/features to focus on (or "full site" for comprehensive testing)
-3. **Output directory** (optional) — where to save screenshots and the report (default: `./dogfood-output`)
-
-## Workflow
-
-Follow this 5-phase systematic workflow:
-
-### Phase 1: Plan
-
-1. Create the output directory structure:
-<!-- ascii-guard-ignore -->
-   ```
-   {output_dir}/
-   ├── screenshots/       # Evidence screenshots
-   └── report.md          # Final report (generated in Phase 5)
-   ```
-<!-- ascii-guard-ignore-end -->
-2. Identify the testing scope based on user input.
-3. Build a rough sitemap by planning which pages and features to test:
-   - Landing/home page
-   - Navigation links (header, footer, sidebar)
-   - Key user flows (sign up, login, search, checkout, etc.)
-   - Forms and interactive elements
-   - Edge cases (empty states, error pages, 404s)
-
-### Phase 2: Explore
-
-For each page or feature in your plan:
-
-1. **Navigate** to the page:
-   ```
-   browser_navigate(url="https://example.com/page")
-   ```
-
-2. **Take a snapshot** to understand the DOM structure:
-   ```
-   browser_snapshot()
-   ```
-
-3. **Check the console** for JavaScript errors:
-   ```
-   browser_console(clear=true)
-   ```
-   Do this after every navigation and after every significant interaction. Silent JS errors are high-value findings.
-
-4. **Take an annotated screenshot** to visually assess the page and identify interactive elements:
-   ```
-   browser_vision(question="Describe the page layout, identify any visual issues, broken elements, or accessibility concerns", annotate=true)
-   ```
-   The `annotate=true` flag overlays numbered `[N]` labels on interactive elements. Each `[N]` maps to ref `@eN` for subsequent browser commands.
-
-5. **Test interactive elements** systematically:
-   - Click buttons and links: `browser_click(ref="@eN")`
-   - Fill forms: `browser_type(ref="@eN", text="test input")`
-   - Test keyboard navigation: `browser_press(key="Tab")`, `browser_press(key="Enter")`
-   - Scroll through content: `browser_scroll(direction="down")`
-   - Test form validation with invalid inputs
-   - Test empty submissions
-
-6. **After each interaction**, check for:
-   - Console errors: `browser_console()`
-   - Visual changes: `browser_vision(question="What changed after the interaction?")`
-   - Expected vs actual behavior
-
-### Phase 3: Collect Evidence
-
-For every issue found:
-
-1. **Take a screenshot** showing the issue:
-   ```
-   browser_vision(question="Capture and describe the issue visible on this page", annotate=false)
-   ```
-   Save the `screenshot_path` from the response — you will reference it in the report.
-
-2. **Record the details**:
-   - URL where the issue occurs
-   - Steps to reproduce
-   - Expected behavior
-   - Actual behavior
-   - Console errors (if any)
-   - Screenshot path
-
-3. **Classify the issue** using the issue taxonomy (see `references/issue-taxonomy.md`):
-   - Severity: Critical / High / Medium / Low
-   - Category: Functional / Visual / Accessibility / Console / UX / Content
-
-### Phase 4: Categorize
-
-1. Review all collected issues.
-2. De-duplicate — merge issues that are the same bug manifesting in different places.
-3. Assign final severity and category to each issue.
-4. Sort by severity (Critical first, then High, Medium, Low).
-5. Count issues by severity and category for the executive summary.
-
-### Phase 5: Report
-
-Generate the final report using the template at `templates/dogfood-report-template.md`.
-
-The report must include:
-1. **Executive summary** with total issue count, breakdown by severity, and testing scope
-2. **Per-issue sections** with:
-   - Issue number and title
-   - Severity and category badges
-   - URL where observed
-   - Description of the issue
-   - Steps to reproduce
-   - Expected vs actual behavior
-   - Screenshot references (use `MEDIA:<screenshot_path>` for inline images)
-   - Console errors if relevant
-3. **Summary table** of all issues
-4. **Testing notes** — what was tested, what was not, any blockers
-
-Save the report to `{output_dir}/report.md`.
-
-## Tools Reference
-
-| Tool | Purpose |
-|------|---------|
-| `browser_navigate` | Go to a URL |
-| `browser_snapshot` | Get DOM text snapshot (accessibility tree) |
-| `browser_click` | Click an element by ref (`@eN`) or text |
-| `browser_type` | Type into an input field |
-| `browser_scroll` | Scroll up/down on the page |
-| `browser_back` | Go back in browser history |
-| `browser_press` | Press a keyboard key |
-| `browser_vision` | Screenshot + AI analysis; use `annotate=true` for element labels |
-| `browser_console` | Get JS console output and errors |
-
-## Tips
-
-- **Always check `browser_console()` after navigating and after significant interactions.** Silent JS errors are among the most valuable findings.
-- **Use `annotate=true` with `browser_vision`** when you need to reason about interactive element positions or when the snapshot refs are unclear.
-- **Test with both valid and invalid inputs** — form validation bugs are common.
-- **Scroll through long pages** — content below the fold may have rendering issues.
-- **Test navigation flows** — click through multi-step processes end-to-end.
-- **Check responsive behavior** by noting any layout issues visible in screenshots.
-- **Don't forget edge cases**: empty states, very long text, special characters, rapid clicking.
-- When reporting screenshots to the user, include `MEDIA:<screenshot_path>` so they can see the evidence inline.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/bundled/software-development/software-development-github.md

@@ -1,73 +0,0 @@
----
-title: "Github — GitHub via gh CLI: PRs, issues, reviews, repos, auth"
-sidebar_label: "Github"
-description: "GitHub via gh CLI: PRs, issues, reviews, repos, auth"
----
-
-{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
-
-# Github
-
-GitHub via gh CLI: PRs, issues, reviews, repos, auth.
-
-## Skill metadata
-
-| | |
-|---|---|
-| Source | Bundled (installed by default) |
-| Path | `skills/software-development\github` |
-| Version | `2.0.0` |
-| Author | Ben Barclay (benbarclay), Hermes Agent |
-| License | MIT |
-| Platforms | linux, macos, windows |
-| Tags | `github`, `gh`, `git`, `pull-requests`, `issues`, `code-review`, `repos`, `auth`, `ci` |
-| Related skills | [`codebase-inspection`](/docs/user-guide/skills/bundled/software-development/software-development-codebase-inspection), [`requesting-code-review`](/docs/user-guide/skills/bundled/software-development/software-development-requesting-code-review) |
-
-## Reference: full SKILL.md
-
-:::info
-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
-:::
-
-# GitHub
-
-Work GitHub end to end with the `gh` CLI (REST fallback where noted): auth,
-issues, the PR lifecycle, issue-to-PR delivery, code review, and repo
-management. This skill consolidates six former skills; each workflow lives
-complete in its reference file — ALWAYS read the matching reference before
-starting that workflow, the body below only routes.
-
-## Routing
-
-| Task | Read first |
-|---|---|
-| Auth broken / new machine / token or SSH setup / gh login | `references/auth.md` |
-| Create, triage, label, assign, close issues | `references/issues.md` |
-| Branch, commit, open PR, watch CI, merge | `references/pr-workflow.md` |
-| Carry an ISSUE to a verified PR (full delivery loop) | `references/issue-to-pr.md` |
-| Review someone's PR: diffs, inline comments, verdict | `references/code-review.md` |
-| Clone/create/fork repos, remotes, releases | `references/repo-management.md` |
-
-Supporting assets: `scripts/gh-env.sh` + `scripts/git-credential-token.py`
-(auth helpers), `templates/` (PR bodies, bug report, feature request),
-`references/ci-troubleshooting.md`, `references/conventional-commits.md`,
-`references/github-api-cheatsheet.md`, `references/review-output-template.md`.
-
-## Core discipline (applies to every workflow)
-
-- Preflight once per session: `gh auth status` — if it fails, go to
-  `references/auth.md` before anything else.
-- Prefer `gh` over raw REST; drop to `gh api` only for endpoints the
-  porcelain lacks (the cheatsheet lists them).
-- Never report CI green without checking `gh pr checks` yourself; never
-  claim merged without verifying `state,mergedAt`.
-- Read full context before writing: `gh issue view --comments` /
-  `gh pr view --comments` — decisions live in threads, not titles.
-- Sweep for duplicates before creating anything:
-  `gh pr list --search` / `gh issue list --search`.
-
-## Verification
-
-- The workflow's own reference file defines done for that task.
-- Cross-cutting: every claim about remote state (CI, merge, release,
-  issue state) is backed by a fresh `gh` read, never memory.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/bundled/software-development/software-development-hermes-agent-skill-authoring.md

@@ -1,230 +0,0 @@
----
-title: "Hermes Agent Skill Authoring — Author in-repo SKILL.md files: frontmatter and structure"
-sidebar_label: "Hermes Agent Skill Authoring"
-description: "Author in-repo SKILL.md files: frontmatter and structure"
----
-
-{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
-
-# Hermes Agent Skill Authoring
-
-Author in-repo SKILL.md files: frontmatter and structure.
-
-## Skill metadata
-
-| | |
-|---|---|
-| Source | Bundled (installed by default) |
-| Path | `skills/software-development\hermes-agent-skill-authoring` |
-| Version | `2.0.0` |
-| Author | Hermes Agent |
-| License | MIT |
-| Platforms | linux, macos, windows |
-| Tags | `skills`, `authoring`, `hermes-agent`, `conventions`, `skill-md` |
-| Related skills | [`requesting-code-review`](/docs/user-guide/skills/bundled/software-development/software-development-requesting-code-review) |
-
-## Reference: full SKILL.md
-
-:::info
-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
-:::
-
-# 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):** `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 `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
-
-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 (validator ceiling 1024 chars — but see the repo hardline below, which is much stricter).
-- Non-empty body after the closing `---`.
-
-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: 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-in-repo-skill]
----
-```
-
-### `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
-
-- 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 — the agent reliably follows the same useful discipline.
-
-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.
-
-## Tests and Docs (required for repo skills)
-
-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 `python 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 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
-   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"]) <= 60, f"description {len(fm['description'])} chars — hardline is 60"
-   assert fm["description"].endswith(".")
-   assert "platforms" in fm
-   assert len(content) <= 100_000
-   ```
-   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:** `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`.
-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
-
-- [ ] 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`, `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
-- [ ] 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