@prismer/runtime 2.0.8 → 2.2.63

package/built-in-skills/skill-creator/eval-viewer/generate_review.py

@@ -16,12 +16,8 @@ import argparse
 import base64
 import json
 import mimetypes
-import os
 import re
-import signal
-import subprocess
 import sys
-import time
 import webbrowser
 from functools import partial
 from http.server import HTTPServer, BaseHTTPRequestHandler
@@ -276,7 +272,8 @@ def generate_html(
     if benchmark:
         embedded["benchmark"] = benchmark
 
-    data_json = json.dumps(embedded)
+    # HTML parses closing script tags before JavaScript parses string literals.
+    data_json = json.dumps(embedded).replace('<', '\\u003c').replace('>', '\\u003e').replace('&', '\\u0026')
 
     return template.replace("/*__EMBEDDED_DATA__*/", f"const EMBEDDED_DATA = {data_json};")
 
@@ -285,26 +282,6 @@ def generate_html(
 # HTTP server (stdlib only, zero dependencies)
 # ---------------------------------------------------------------------------
 
-def _kill_port(port: int) -> None:
-    """Kill any process listening on the given port."""
-    try:
-        result = subprocess.run(
-            ["lsof", "-ti", f":{port}"],
-            capture_output=True, text=True, timeout=5,
-        )
-        for pid_str in result.stdout.strip().split("\n"):
-            if pid_str.strip():
-                try:
-                    os.kill(int(pid_str.strip()), signal.SIGTERM)
-                except (ProcessLookupError, ValueError):
-                    pass
-        if result.stdout.strip():
-            time.sleep(0.5)
-    except subprocess.TimeoutExpired:
-        pass
-    except FileNotFoundError:
-        print("Note: lsof not found, cannot check if port is in use", file=sys.stderr)
-
 class ReviewHandler(BaseHTTPRequestHandler):
     """Serves the review HTML and handles feedback saves.
 
@@ -360,12 +337,26 @@ class ReviewHandler(BaseHTTPRequestHandler):
 
     def do_POST(self) -> None:
         if self.path == "/api/feedback":
-            length = int(self.headers.get("Content-Length", 0))
+            origin = self.headers.get('Origin')
+            if origin and origin not in (f'http://localhost:{self.server.server_port}', f'http://127.0.0.1:{self.server.server_port}'):
+                self.send_error(403)
+                return
+            try:
+                length = int(self.headers.get('Content-Length', 0))
+            except ValueError:
+                self.send_error(400)
+                return
+            if not 0 < length <= 1024 * 1024:
+                self.send_error(413)
+                return
             body = self.rfile.read(length)
             try:
                 data = json.loads(body)
-                if not isinstance(data, dict) or "reviews" not in data:
-                    raise ValueError("Expected JSON object with 'reviews' key")
+                if (not isinstance(data, dict) or not isinstance(data.get('reviews'), list)
+                        or data.get('status') not in ('in_progress', 'complete')
+                        or any(not isinstance(r, dict) or not isinstance(r.get('run_id'), str)
+                               or not isinstance(r.get('feedback'), str) for r in data['reviews'])):
+                    raise ValueError('Invalid review payload')
                 self.feedback_path.write_text(json.dumps(data, indent=2) + "\n")
                 resp = b'{"ok":true}'
                 self.send_response(200)
@@ -435,14 +426,12 @@ def main() -> None:
         print(f"\n  Static viewer written to: {args.static}\n")
         sys.exit(0)
 
-    # Kill any existing process on the target port
     port = args.port
-    _kill_port(port)
     handler = partial(ReviewHandler, workspace, skill_name, feedback_path, previous, benchmark_path)
     try:
         server = HTTPServer(("127.0.0.1", port), handler)
     except OSError:
-        # Port still in use after kill attempt — find a free one
+        # Never signal an unrelated listener; let the OS select a free port.
         server = HTTPServer(("127.0.0.1", 0), handler)
         port = server.server_address[1]
 

package/built-in-skills/skill-creator/eval-viewer/viewer.html

@@ -652,19 +652,27 @@
     let feedbackMap = {};  // run_id -> feedback text
     let currentIndex = 0;
     let visitedRuns = new Set();
+    let reviewComplete = false;
+    let saveQueue = Promise.resolve();
+    function postFeedback(payload) {
+      saveQueue = saveQueue.catch(() => {}).then(async () => {
+        const response = await fetch('/api/feedback', {
+          method: 'POST', headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify(payload),
+        });
+        if (!response.ok) throw new Error('Feedback save failed');
+      });
+      return saveQueue;
+    }
 
     // ---- Init ----
     async function init() {
-      // Load saved feedback from server — but only if this isn't a fresh
-      // iteration (indicated by previous_feedback being present). When
-      // previous feedback exists, the feedback.json on disk is stale from
-      // the prior iteration and should not pre-fill the textareas.
-      const hasPrevious = Object.keys(EMBEDDED_DATA.previous_feedback || {}).length > 0
-        || Object.keys(EMBEDDED_DATA.previous_outputs || {}).length > 0;
-      if (!hasPrevious) {
+      // Current workspace feedback is distinct from previous-workspace context.
+      {
         try {
           const resp = await fetch("/api/feedback");
           const data = await resp.json();
+          reviewComplete = data.status === 'complete';
           if (data.reviews) {
             for (const r of data.reviews) feedbackMap[r.run_id] = r.feedback;
           }
@@ -678,6 +686,7 @@
       const textarea = document.getElementById("feedback");
       let saveTimeout = null;
       textarea.addEventListener("input", () => {
+        reviewComplete = false;
         clearTimeout(saveTimeout);
         document.getElementById("feedback-status").textContent = "";
         saveTimeout = setTimeout(() => saveCurrentFeedback(), 800);
@@ -803,6 +812,7 @@
           content.appendChild(img);
         } else if (file.type === "pdf") {
           const iframe = document.createElement("iframe");
+          iframe.setAttribute('sandbox', '');
           iframe.src = file.data_uri;
           content.appendChild(iframe);
         } else if (file.type === "xlsx") {
@@ -844,10 +854,18 @@
             container.appendChild(sheetLabel);
           }
 
-          const htmlStr = XLSX.utils.sheet_to_html(ws, { editable: false });
-          const wrapper = document.createElement("div");
-          wrapper.innerHTML = htmlStr;
-          container.appendChild(wrapper);
+          const table = document.createElement('table');
+          // Cell values and hyperlinks are untrusted; never insert workbook HTML.
+          for (const row of XLSX.utils.sheet_to_json(ws, { header: 1, defval: '' })) {
+            const tr = document.createElement('tr');
+            for (const value of row) {
+              const td = document.createElement('td');
+              td.textContent = String(value);
+              tr.appendChild(td);
+            }
+            table.appendChild(tr);
+          }
+          container.appendChild(table);
         }
       } catch (err) {
         container.textContent = "Error rendering spreadsheet: " + err.message;
@@ -963,6 +981,7 @@
           fc.appendChild(img);
         } else if (file.type === "pdf") {
           const iframe = document.createElement("iframe");
+          iframe.setAttribute('sandbox', '');
           iframe.src = file.data_uri;
           fc.appendChild(iframe);
         } else if (file.type === "xlsx") {
@@ -992,6 +1011,7 @@
 
     // ---- Feedback (saved to server -> feedback.json) ----
     function saveCurrentFeedback() {
+      if (reviewComplete) return;
       const run = EMBEDDED_DATA.runs[currentIndex];
       const text = document.getElementById("feedback").value;
 
@@ -1009,11 +1029,7 @@
         }
       }
 
-      fetch("/api/feedback", {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ reviews, status: "in_progress" }),
-      }).then(() => {
+      postFeedback({ reviews, status: 'in_progress' }).then(() => {
         document.getElementById("feedback-status").textContent = "Saved";
       }).catch(() => {
         // Static mode or server unavailable — no-op on auto-save,
@@ -1041,11 +1057,8 @@
         reviews.push({ run_id: r.id, feedback: feedbackMap[r.id] || "", timestamp: ts });
       }
       const payload = JSON.stringify({ reviews, status: "complete" }, null, 2);
-      fetch("/api/feedback", {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: payload,
-      }).then(() => {
+      reviewComplete = true;
+      postFeedback({ reviews, status: 'complete' }).then(() => {
         document.getElementById("done-overlay").classList.add("visible");
       }).catch(() => {
         // Server not available (static mode) — download as file
@@ -1061,8 +1074,7 @@
     }
 
     function closeDoneDialog() {
-      // Reset status back to in_progress
-      saveCurrentFeedback();
+      // Closing the acknowledgement does not reopen a completed review.
       document.getElementById("done-overlay").classList.remove("visible");
     }
 

package/built-in-skills/skill-creator/references/external-library-import.md

@@ -0,0 +1,110 @@
+# External skill-library import
+
+Use this workflow when the source is a repository or directory containing more
+than one skill, especially when the result will be wired into a role.
+
+## 1. Establish the authoritative source
+
+- Read the repository README, license, and AGENTS.md before changing anything.
+- Identify mirrors/translations and import only the source tree the repository
+  declares authoritative. Record the excluded mirrors in the final report.
+- Inventory directories containing a root `SKILL.md`; do not infer the count
+  from repository file totals.
+- Work from a temporary copy when normalization is genuinely required. Do not
+  edit the cloned authority merely to satisfy the platform parser.
+
+The Prismer bundle parser accepts ordinary YAML block scalars (`description: |`
+and `description: >`). The description quality floor is language-aware, so a
+concise CJK description need not be padded with filler. If validation rejects
+either shape, treat it as a CLI/runtime version-skew problem before rewriting
+the source.
+
+## 2. Run the deterministic import harness
+
+After choosing the authoritative tree, put configuration in the runtime
+environment and run one command:
+
+```bash
+node scripts/import-library.mjs --json
+```
+
+Required environment: `PRISMER_SKILL_LIBRARY_ROOT`. Optional:
+`PRISMER_SKILL_LIBRARY_EXCLUDE` (comma/newline-separated relative trees),
+`PRISMER_IMPORT_LEDGER`, `PRISMER_CLOUD_BIN`, `PRISMER_CLOUD_BASE`, and
+`PRISMER_ALLOW_REMOTE_WRITE=1` for an explicitly confirmed non-local target.
+Authentication remains in the Cloud CLI's injected environment/config; never
+put a token in arguments or source files.
+
+Use `--preflight-only` when only inventory/validation is requested. The harness:
+
+1. discovers root `SKILL.md` bundles under the selected tree;
+2. validates the entire set locally before the first create;
+3. rejects duplicate requested slugs, which usually means both an authority and
+   its mirror were selected;
+4. creates only unverified ledger rows and persists every server-returned slug;
+5. verifies private content through owner-scoped `cloud skill show --content`;
+6. emits `requiredSkills[]` from verified canonical slugs for `role-builder`.
+
+Do not publish the first item as an exploratory probe. A probe creates durable
+catalog state and is not a substitute for a read-only validator.
+
+If `cloud` exists but a documented command such as `skill create` is absent,
+report the installed CLI version and use the repository's current Cloud CLI
+build. Do not silently jump to a raw HTTP request or a bundled ingest script;
+that bypasses the exact auth/scope/readback path being verified. The portable
+script is only a fallback when the CLI binary itself is unavailable.
+
+## 3. Recovery and lower-level diagnosis
+
+On a transient failure, rerun the same command with the same
+`PRISMER_IMPORT_LEDGER`; verified rows are not recreated. If the selected files
+changed, the harness rejects the stale ledger before Cloud calls—use a new
+task-bound ledger after reviewing that change.
+
+Only diagnose a failed row with the lower-level primitives:
+
+```bash
+cloud skill validate <dir> --json
+cloud skill create <dir> --json
+cloud skill mine --json
+cloud skill show <returned-slug-or-id> --content --json
+```
+
+Community slugs may be prefixed by the server; never lowercase, prefix, or
+otherwise reconstruct them. A conflict alone is not proof of a complete or
+correct prior import.
+
+## 4. Verify the private domain correctly
+
+`cloud skill find` searches the public Marketplace and is expected not to show
+workspace-private skills. Verify authored skills through:
+
+```bash
+cloud skill mine --json
+cloud skill show <canonical-slug-or-id> --content --json
+```
+
+Every successful ledger row must round-trip. Do not create temporary catalog
+objects to discover response shape; use `--json` on the real create/readback.
+
+## 5. Hand canonical slugs to role-builder
+
+Generate `requiredSkills[]` only from successful ledger rows. Then use the
+`role-builder` workflow:
+
+```bash
+cloud role validate <role-dir> --json
+cloud role test <role-dir> --json
+cloud role create <role-dir> --json
+cloud role show <returned-slug-or-id> --json
+```
+
+`role test` is the read-only dependency proof. Do not apply the role merely to
+test resolution. Applying changes a live agent profile and requires the user's
+explicit target and intent; never use the currently executing agent as a probe.
+
+## Completion evidence
+
+Report selected/excluded source trees, validated/created/failed counts, the
+canonical slug ledger, role readback, and whether any apply was explicitly
+requested. A POST count or a list of requested names is not completion evidence.

package/built-in-skills/skill-creator/references/hermes-agent-skill-authoring/GUIDE.md

@@ -0,0 +1,220 @@
+---
+name: hermes-agent-skill-authoring
+description: "Author in-repo SKILL.md files: frontmatter and structure."
+version: 2.0.0
+author: Hermes Agent
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [skills, authoring, hermes-agent, conventions, skill-md]
+    related_skills: [requesting-code-review]
+---
+
+# Authoring Hermes-Agent Skills (in-repo)
+
+> Prismer adaptation: this reference describes Hermes-specific standards, not
+> the Prismer catalog schema. Resolve the actual repository root before using
+> any relative path. Hermes tools and directories apply only inside a verified
+> Hermes checkout. Never stage, commit, publish, or restore files automatically.
+> Preserve every pre-existing change. Usage-frequency thresholds below are
+> upstream guidance, not evidence for deleting existing Prismer skills.
+
+## 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 the available file-editing tool; stage only on explicit user request. `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]` |
+
+<!-- no-tmp: ok — names the anti-pattern skill authors must avoid -->
+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. run the generator in an isolated temporary checkout and copy only the intended generated files back after comparing with the current worktree; never restore unrelated changes; 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. **Review the scoped diff** on the active branch. Stage, commit, or open a PR only when the user explicitly requests that operation.
+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.
+- **Review before commit** — in-repo skills are source, not runtime state. Never commit automatically. Regenerate docs in an isolated checkout when frontmatter changes.
+
+## 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; the upstream 5+ sessions/month heuristic must not be treated as measured usage or used to delete existing 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
+- [ ] Scoped diff verified; any staging, commit, or PR explicitly authorized by the user

package/built-in-skills/skill-creator/references/hermes-agent-skill-authoring/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Nous Research
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.