better-dsh 0.2.4 → 0.2.5-a

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

@@ -0,0 +1,132 @@
+---
+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

@@ -0,0 +1,183 @@
+---
+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

@@ -0,0 +1,73 @@
+---
+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

@@ -0,0 +1,230 @@
+---
+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