Commit Graph

204 Commits

Author SHA1 Message Date
teknium1 2a7ed25db8 feat(skills): cover all Hermes browser pathways in har-derived-api-client
Adds scripts/har_capture_cdp.py for browsers reached over CDP -- cloud
backends (Browserbase, Browser-Use, Firecrawl), Camofox-with-CDP, and any
/browser connect endpoint. record_har_path only works on a locally-owned
Playwright context, so the CDP capturer attaches via connect_over_cdp() and
assembles the HAR from page request/response events instead, leaving the
attached browser open (it doesn't own it).

- SKILL.md: pathway->capturer routing table, CDP prerequisites, pitfalls for
  wrong-capturer/empty-HAR, headless-UA weakness, and no-close-on-attach
- Validated live: attached to an external CDP Chrome, drove DuckDuckGo
  autocomplete, derived the /ac/ endpoint, replayed it browserless
- tests: assert CDP capturer attaches (not launches) and that the skill
  documents every browser backend
2026-08-12 16:11:51 -07:00
teknium1 c558e3520a feat(skills): add har-derived-api-client optional skill
Record a site's XHR into a HAR with Playwright, derive its private JSON API,
and call it directly over plain HTTP instead of browser-controlling the page
every time. Credit: trick by Jared Longster, popularized by Dax (thdxr).

- scripts/har_capture.py: Playwright HAR recorder with scripted --action steps
  and embedded response bodies
- scripts/har_to_client.py: distills the HAR to endpoints (method/path template
  /params/body/response) plus User-Agent+cookie+auth replay hints
- Validated live: derived + replayed the Algolia HN-search POST API and the
  Wikipedia rest.php search-title GET, both browserless
- tests exercise the real derivation logic on a synthetic HAR fixture

optional-skills placement: heavy Playwright dependency, niche use case.
2026-08-12 16:11:51 -07:00
Teknium 4a2198bf51
fix: Windows MCP PATHEXT resolution + python3 -> python in cross-platform skills (#84429)
Two Windows agent-loop friction fixes:

1. tools/mcp_tool.py (#56536): shutil.which(cmd, path=env_path) reads
   executable extensions from the PARENT process PATHEXT, not the MCP
   subprocess env — a stdio MCP config supplying both PATH and PATHEXT
   could fail to resolve a command its own env can locate, and startup
   then got a bare command name. On Windows, when the first which() call
   misses and the config env carries PATHEXT (any key casing), retry the
   resolution with the config's PATHEXT temporarily applied.

2. skills/ + optional-skills/ (#50606): 42 SKILL.md files that declare
   platforms: [.., windows] used python3 in their command examples.
   python3 does not exist on native Windows (the toolchain probe in the
   system prompt reports python3=missing), so every copy-pasted example
   burned a failed agent turn before self-correction. Replaced the
   command word python3 -> python (python3-config / python3.x version
   strings untouched). python is the spelling that exists in every
   Hermes-managed environment (Windows native, uv-managed venvs on all
   three OSes); agents on POSIX hosts additionally see the probed
   toolchain line and adapt either way.
2026-08-12 02:43:28 -07:00
Hermes Agent bdbdfead04
fix(security): remove blender MCP catalog entry and skill after upstream compromise
The upstream ahujasid/blender-mcp and ahujasid/ableton-mcp GitHub repos
were hijacked on 2026-08-08: the maintainer (@sidahuj) publicly reported
his account was compromised and ownership stripped, and both repos now
redirect to an attacker-controlled org (MCPBlender, created the same
day, pushing new commits since).

Although our catalog pinned blender-mcp==1.6.4 from PyPI (pre-compromise,
sha256 verified unchanged), the server is only half the bridge: the
manifest's post-install instructions and the optional skill directed
users to download addon.py — arbitrary Python executed inside Blender —
from the now-compromised GitHub repo (the raw URL currently 404s, and
the addon ships in no PyPI artifact). There is no trustworthy source
for the addon half, so the entry cannot be installed safely end-to-end.

Removing the catalog entry and skill entirely until the maintainer
confirms account recovery; re-adding is a follow-up PR once upstream
is verified clean.

- optional-mcps/blender/: removed
- optional-skills/creative/blender-mcp/: removed
- docs: catalog rows, sidebar entry, skill pages (en + zh-Hans) removed
- cross-references in unreal-mcp and kanban-video-orchestrator cleaned
2026-08-10 12:12:11 -07:00
Teknium 3e05d7abf1
fix(skills): trim ast-grep description to the 60-char hardline
test_authoring_standards.py::test_description_hardline red on main since
461c493972 landed with a 383-char description. The trimmed detail is all
preserved in the SKILL.md body (When-to-use, decision tree, search_files
comparison). Unbreaks every open PR's slice 4.
2026-08-09 14:55:28 -07:00
Teknium 461c493972 Port from code-yeongyu/oh-my-openagent: ast-grep structural search/codemod optional skill
Vendors the ast-grep skill from oh-my-openagent's shared-skills bundle
(upstream code-yeongyu/ast-grep-skill @ 3148c69, MIT) into
optional-skills/software-development/ast-grep with Hermes conventions:

- SKILL.md rewritten with Hermes frontmatter (platforms, tags, category)
  and Hermes tool routing (search_files instead of raw rg, terminal for
  sg invocations, patch-vs-ast-grep division of labor)
- scripts/ast_grep_helper.py: fixed argparse so trailing paths after an
  optional flag parse (parse_known_args + fold extras into paths);
  upstream errored 'unrecognized arguments: .' on the documented
  'search PATTERN --lang js .' form
- 7 reference docs, install.sh/install.ps1 (pinned-release GitHub
  fallback), smoke tests carried over verbatim

E2E validated: install (github method, ast-grep 0.45.0), doctor,
search, validate (regex rejection), replace dry-run + apply two-pass,
scan with YAML rule, tests/smoke.sh 15/15 pass.
2026-08-09 14:40:15 -07:00
teknium1 55982159dd feat(tests): CI-enforce skill authoring standards; clear all remaining debt
New tests/skills/test_authoring_standards.py parametrizes every bundled +
optional SKILL.md (1148 checks) against the mechanically-verifiable subset
of the hardline standards:
- required frontmatter fields (name/description/version/author/license/
  platforms) + tags
- frontmatter name == directory name
- description <= 60 chars, ends with period, no marketing words
- related_skills resolve in-repo
- no machine-local paths
- <= 100k chars
Grandfather dict for legacy debt ships EMPTY — all pre-existing violations
fixed in this PR:

- 13 frontmatter names canonicalized to their directory names (the install
  identifier); all related_skills references updated (comfyui -> stable-
  diffusion). Fixes the class behind PR #42788's report; also fixes
  here.now's invalid dot-name.
- optional-skills/devops/cli -> inference-sh-cli (dir was the generic
  'cli'; fm name was right) incl. docs pages (en + zh-Hans), catalog row,
  sidebar entry.
- pytorch-fsdp: 157k generated 'Quick Reference' dump moved to
  references/common-patterns.md; SKILL.md 159k -> 2.5k with a pointer.
- research-paper-writing: 31.7k Phase 5 drafting section moved to
  references/phase5-paper-drafting.md; SKILL.md 103k -> 71k.

Docs regenerated with scope discipline.
2026-08-08 15:43:00 -07:00
teknium1 1c9433897c chore(skills): standards sweep — bring 42 bundled/optional skills up to hardline
Audited all 191 in-repo skills (77 bundled, 114 optional) against the
authoring standards (AGENTS.md hardline + PR #80800). Fixed 42:

- 8 overlong descriptions rewritten to <= 60 chars, one sentence, period
  (one-three-one-rule 525ch, drug-discovery 405ch, web-pentest 358ch,
  fitness-nutrition 352ch, neuroskill-bci 332ch, oss-forensics 320ch,
  computer-use 307ch, memento-flashcards 252ch)
- 24 skills with missing frontmatter fields: author (credited from git
  history: f-trycua, SHL0MS, teyrebaz33, haileymarshall, FurkanL0,
  teknium1), license, version, platforms, tags
- 7 machine-local paths scrubbed (/home/bb, /home/user, /home/ubuntu ->
  portable placeholders)
- 11 marketing-word intros reworded (Comprehensive/state-of-the-art)
- docs catalogs + per-skill pages regenerated, scope-disciplined

Deferred (not in this PR):
- 14 frontmatter/dir name mismatches — open PR #42788 already proposes
  the dir-rename approach for 4 of them; resolve there as one class
- 2 skills over 100k chars (pytorch-fsdp 159k, research-paper-writing
  103k) — need content splits into references/, separate PRs
- comfyui dangling related_skill resolves after the name-mismatch class
2026-08-08 15:27:29 -07:00
teknium1 91a545ab1e chore(skills/social-media-content-calendar): tighten to hardline standards, ship optional
- description 210 -> 57 chars; author credits Ben Barclay (benbarclay) first
- optional-skills/creative/ (marketing vertical, narrowest audience of
  the batch)
- dropped phantom 'image-generation-workflow' ref; visuals via the
  image_generate tool
- honest handoff language: platforms without connectors end at approved
  drafts marked handed-off, never claimed as published
- tests (10) incl. phantom-ref and honest-handoff guards
- docs regen scoped: per-skill page + one catalog row + one sidebar line
2026-08-08 12:05:19 -07:00
Teknium 2b48ba0249 fix: clean up SkillEvaluator Tier 1 security findings in bundled skills
Findings from scanning skills/ + optional-skills/ with NVIDIA
SkillEvaluator's deterministic Tier 1 checks (PII/secrets, unicode
smuggling, script lint):

- pixel-art, pokemon-player: remove hardcoded /home/teknium/ personal
  paths (use ~ / portable phrasing); pokemon-player no longer claims
  machine-specific state as fact
- kanban-video-orchestrator: replace <path> angle-bracket token in
  frontmatter credits (flagged as XML-in-frontmatter prompt injection)
- comfyui, hermes-agent, unsloth, 1password, actual-setup: rephrase
  placeholder secrets so they no longer pattern-match real credentials
  (your-* placeholder convention, comment markers, {env:...} form)
- docker-management, pytorch-lightning: drop user:pass@ from example
  connection strings (env/secret-manager guidance instead)
- evm: break up Keccak round constant that Luhn-validates as a credit
  card number (digit-group underscores, value unchanged)

All targeted skills now pass pii+unicode+lint 3/3 except unsloth, which
retains scanner false positives only (Colab notebook IDs read as Bitcoin
addresses; an email inside a quoted upstream system prompt).
2026-08-08 10:45:21 -07:00
teknium1 78bc9acdf1 chore(skills/document-to-action-items): promote to bundled tier
Fleet audit showed these task skills are commonly needed across users;
shipping bundled per Teknium's direction. Docs and tests follow the
bundled paths.
2026-08-07 10:35:42 -07:00
teknium1 7b8d0d800c chore(skills/document-to-action-items): tighten to hardline standards, move to optional
- description 214 -> 59 chars
- author credits Ben Barclay (benbarclay) first
- moved skills/productivity -> optional-skills/productivity (not a daily driver)
- dropped dangling 'linear' related_skills entry; prose points at approved destinations
- framed steps through Hermes tools (read_file, web_extract, xlsx, notion)
- trimmed template safety/verification boilerplate to doc-specific rules
- modern section order (When to Use / Procedure / Pitfalls / Verification)
- tests at tests/skills/test_document_to_action_items_skill.py (8 passing)
- docs regen scoped: per-skill page + one catalog row + one sidebar line
2026-08-07 10:35:42 -07:00
teknium1 0957277f2f refactor(skills): move polymarket to optional-skills/finance
Per the 'when in doubt, optional' rule — niche prediction-market data
skill that sees no regular use; belongs alongside stocks in the finance
optional category rather than the default bundle.

Install via: hermes skills install official/finance/polymarket
2026-08-06 11:30:58 -07:00
Teknium 5aa798fecc feat(skills): actual-setup optional skill + provider docs
- optional-skills/devops/actual-setup: field-tested setup skill contributed
  by shl0ms, updated for the first-class 'actual' provider (the original
  targeted a custom-provider config that now collides with the built-in name)
- docs: providers.md section + tables, environment-variables.md, quickstart.md
- tests/skills: frontmatter + first-class-provider conformance checks
2026-08-05 14:08:32 -07:00
kshitijk4poor 0a62610f10 fix(cli): swallow fsync errors in the openclaw EXDEV fallback
Exact parity with utils.atomic_replace: its target fsync is wrapped in
try/except OSError. A failed fsync after a successful copy must not
surface the already-completed write as an error (Windows can raise on
fsync of a read-only handle).
2026-08-02 14:55:32 +05:30
kshitijk4poor 9d6ef41a53 refactor(cli): review follow-ups for the config.yaml import guard
- agent_import.dump_yaml_file now calls utils.atomic_yaml_write instead
  of hand-rolling safe_dump + atomic_write_text — same temp+fsync+atomic
  rename and symlink preservation, plus mode/owner preservation a
  0600-secured config.yaml needs
- openclaw script: the EXDEV/EBUSY copy fallback gains copystat + target
  fsync so the docstring's 'mirrors utils.atomic_replace' durability
  claim is true on cross-device deployments
- trim load_yaml_file's docstring to the behavior contract
2026-08-02 14:55:32 +05:30
briandevans e75336d597 fix(cli): preserve symlinked config.yaml in the migration script's atomic write
The inlined temp-file + os.replace in openclaw_to_hermes.dump_yaml_file
replaced a symlinked config.yaml with a regular file, silently detaching
managed deployments that symlink ~/.hermes/config.yaml into a dotfiles repo or
profile package. The bare path.write_text it replaced followed the link, and
utils.atomic_replace -- which the hermes_cli twin reaches through
atomic_write_text -- resolves the link for exactly this reason (#16743).

Mirror that here: resolve the symlink before creating the temp file so the
rename lands on the real file, and fall back to copyfile on EXDEV/EBUSY now
that the target can live on another device. Covered by a regression test that
fails when the resolution is removed.

Also guard the permission-denied test for Windows: os.geteuid does not exist
there and chmod-based denial is unreliable, so skip on non-POSIX.
2026-08-02 14:55:32 +05:30
briandevans 981a598646 fix(cli): stop hermes import-agent from destroying an unreadable config.yaml
agent_import.py carries a private load_yaml_file/dump_yaml_file pair that
returned {} for an absent file AND for a present file it could not read or
parse. Three importers -- import_permission_allowlist, import_permission_denylist
and import_mcp_servers -- read config.yaml through it, merge one section into
the result, and write the whole mapping straight back. So a YAML syntax error,
a permission problem or a broken mount meant the importer replaced every
setting the user had with only the one to three keys it merged, and still
reported the item as "imported". The write was a bare path.write_text(), so an
interrupted import truncated the file instead.

Distinguish the two cases at the read. Absent, or present but empty, still
yields {} so first-time creation works. Present but unreadable, unparseable, or
not a mapping raises ConfigReadError; the three sites funnel through a new
load_target_config() that records the refusal as a per-item error and leaves the
file byte-identical. Dry-run refuses too, rather than previewing an "imported"
that would destroy the config. dump_yaml_file now writes through
utils.atomic_write_text, which the module already imports and uses for the
memory store.

This is the invariant hermes_cli/config.py already enforces for its own writers
via require_readable_config_before_write / atomic_config_write, whose docstring
names this exact root cause and calls itself "the single chokepoint every
config-update path should use". agent_import.py has its own helper pair and so
was never covered; it was the last config.yaml writer without the guard.

The identical helper pair lives in openclaw_to_hermes.py, the script this module
was ported from, where twelve config.yaml read-modify-write sites share the same
defect; fixed there too. Its refusal is recorded at the run_if_selected dispatch
point, which flips the existing _config_apply_blocked flag so the remaining
config-mutating options short-circuit instead of each rediscovering the same
unreadable file. The atomic write is inlined with tempfile + os.replace because
that script runs standalone with only the stdlib on its path.
2026-08-02 14:55:32 +05:30
Teknium 003af7f85c fix(docker): update runtime tests and docs for the entrypoint dispatcher
Follow-ups from sweeper review of #43763:
- tests/docker/test_tini_compat_shim.py asserts the dispatcher
  ENTRYPOINT (with /init delegation check) instead of a bare /init
- tests/docker/test_smoke.py gains a docker run --init regression
  for the non-PID-1 fallback (#38349)
- website/docs/user-guide/docker.md and the s6 supervision skill
  document the dispatcher and its wrapped-runtime fallback
2026-08-01 10:52:34 -07:00
briandevans 8a9ab8b56b fix(cli): stop shredding an existing MEMORY.md on hermes import-agent
memories/MEMORY.md is the "§"-delimited store written by MemoryStore, not a
markdown document. parse_existing_memory_entries() fell back to
extract_markdown_entries() -- the *source* parser for CLAUDE.md / AGENTS.md --
whenever the destination held no delimiter, which is exactly the case for a
single-entry store or one that was hand-edited or shell-appended. That
extractor skips fenced code blocks, skips table rows, splits a block into one
entry per bullet and reflows paragraphs. The shredded result was then written
straight back over the user's store and reported as "Imported", with no backup
to recover from.

Parse the destination the way MemoryStore._parse_entries does: split on
ENTRY_DELIMITER only, so a store with no delimiter is one intact entry.
extract_markdown_entries() is unchanged and still used on the sources, where
it is correct.

Also restore the safety net the port dropped. The openclaw migration script
this module was ported from calls maybe_backup(destination) before rewriting a
memory store; the port did not. Snapshot the store to <name>.bak.<unix_ts>
(same naming as MemoryStore._backup_drifted_file), refuse to rewrite when the
snapshot fails, and write via temp file + atomic rename so an interrupted
import cannot leave a truncated store and a symlinked MEMORY.md stays a
symlink.

The identical fallback lives in openclaw_to_hermes.py, where it is reached
from migrate_memory() (memories/MEMORY.md and memories/USER.md) and
migrate_daily_memory(); fixed there too.
2026-07-29 16:49:07 +05:30
teknium1 75e0d52034 fix(windows): sweep remaining bare read_text/write_text sites + linter rule
AST-driven pass over every Path.read_text()/write_text() without an
explicit encoding= across non-test code: 71 sites in 34 files
(skills_hub, hermes_cli/main+profiles+service_manager+container_boot,
mem0/hindsight/honcho plugins, achievements dashboard, release/CI
scripts, productivity+comfyui skill helpers, agent/*). Verified zero
positional-encoding collisions before insertion; per-file compile()
check after.

Adds a check-windows-footguns rule flagging bare single-line
read_text/write_text (multi-line forms stay covered by the AST guard
test from #38985). Together with the salvaged contributor commits this
retires the ~169-site bare file-I/O class (#37423's long tail).
2026-07-24 17:10:39 -07:00
chancelu 049af61d64 fix: handle non-UTF-8 files in OpenClaw migration script 2026-07-24 17:10:39 -07:00
Stoltemberg c89481db5e fix: add explicit UTF-8 encoding to all subprocess text=True calls (#53428)
On Windows with Chinese locale (GBK), subprocess.run(text=True) without
explicit encoding causes UnicodeDecodeError crashes. This fix adds
encoding='utf-8', errors='replace' to all subprocess.run() and
subprocess.Popen() calls that use text=True across 76 non-test Python files.

Fixes #53428 (master tracker for Windows GBK locale crash).

Note: credential_pool.py and electron changes excluded per reviewer request —
those will be submitted as separate focused PRs.
2026-07-24 11:45:57 -07:00
teknium1 55ef425d0c fix(skills): sync bundled + misc CLI skills to current upstream
Nine bundled and optional skills had stale flags, install URLs, packages, and paths. Verified each against upstream and corrected:

- vllm: removed bogus --enable-metrics/--metrics-port (metrics at /metrics on API port); --speculative-model -> --speculative-config; canonical HF model IDs
- lm-evaluation-harness: --tasks list -> lm-eval ls tasks; --allow_code_execution -> --confirm_run_unsafe_code
- weights-and-biases: wandb.keras import removed -> wandb.integration.keras (WandbMetricsLogger); log_uniform -> log_uniform_values for raw values
- huggingface-hub: upload-large-folder now deprecated; hf papers list -> ls
- openhue: Linux install 404 -> openhue_Linux_x86_64.tar.gz tarball (release repo openhue/openhue-cli, v0.24)
- apple-notes: memo notes -a is a bare flag, no positional title
- excalidraw: upload.py path skills/diagramming/... -> skills/creative/...
- searxng-search: removed Method 3 (searxng-data pip package is a PyPI 404)
- sketch: noted get-shit-done upstream is archived/unmaintained
2026-07-24 08:29:59 -07:00
teknium1 9a894dae5f fix(skills): sync coding-agent CLI skills to current flags/packages
Four coding-agent CLI skills drifted from their live CLIs. Verified against live --help/npm and corrected:

- codex: --full-auto deprecated -> --sandbox workspace-write; --yolo -> --dangerously-bypass-approvals-and-sandbox (yolo kept as noted alias)
- claude-code: --effort levels low/medium/high/xhigh/max (dropped removed 'auto', added 'xhigh'); fixed stray table cell
- grok: --session-id is UUID-only for new sessions (cannot resume by name); rewrote the Session Continuation example; noted --max-turns now exists
- blackbox: wrong npm package (@blackboxai/cli is unrelated) -> @blackbox_ai/blackbox-cli; removed dead source-repo link and phantom session/info subcommands
2026-07-24 08:18:10 -07:00
teknium1 1c646499b6 fix(skills): sync mlops training/model-infra skills to current APIs
Seven optional mlops training skills had stale APIs, config paths, image locations, and requirement pins. Verified against upstream and corrected:

- torchtitan: removed TOML train_configs paths (replaced upstream by config registry)
- trl-fine-tuning: PPO removed from TRL 1.x -> GRPO/RLOO; SFTTrainer tokenizer= -> processing_class
- flash-attention: torch.backends.cuda.sdp_kernel (deprecated) -> torch.nn.attention.sdpa_kernel; corrected false FA3/FP8-in-pip claim (FA2 only)
- accelerate: DeepSpeedPlugin instance not raw dict; --config_file expects accelerate YAML; auto_wrap_policy -> transformer_based_wrap
- saelens: v6 nested training config (sae=/logger=); from_pretrained tuple -> from_pretrained_with_cfg_and_sparsity
- tensorrt-llm: Docker Hub image 404 -> NGC nvcr.io; rc pin -> GA; CUDA req updated
- nemo-curator: pip extras renamed; repo moved to NVIDIA-NeMo/Curator; 1.x pipeline rewrite noted
2026-07-24 08:18:05 -07:00
teknium1 8a2b288462 fix(skills): sync mlops structured-output/vectordb skills to current APIs
Five optional mlops skills documented removed pre-major-version APIs. Verified each against upstream and rewrote to the current form:

- outlines: pre-1.0 outlines.generate.*/models.transformers -> v1 from_transformers + model(prompt, output_type)
- guidance: models.Anthropic (nonexistent in 0.3.x) -> Transformers backend; grammar-string -> guidance.json(); noted constrained gen needs local logits
- pinecone: pip install pinecone-client (deprecated) -> pinecone; removed bogus alpha= query kwarg, pre-scale hybrid vectors
- qdrant: client.search()/search_batch() (removed) -> query_points()/query_batch_points()
- modal: container_idle_timeout/concurrency_limit/allow_concurrent_inputs -> scaledown_window/max_containers/@modal.concurrent; floor bumped to modal>=1.0
2026-07-24 08:18:01 -07:00
teknium1 73b01fb7b6 docs(skills): fix remaining 13 broken related_skills refs repo-wide
Widening pass on top of the #38820 salvage: a full-graph audit of every
SKILL.md (bundled + optional) found 13 more references to skills that
no longer exist. Classes:

- deleted in the 38d3c49aaf bundled-skill cleanup: generative-widgets,
  spotify, cloudflared-quick-tunnel, webhook-subscriptions,
  debugging-hermes-tui-commands -> dropped
- native-mcp absorbed into the hermes-agent hub skill -> re-pointed
- toolset names that were never skills: browser, image_gen -> dropped

Audit now reports zero broken related_skills references.
2026-07-24 07:54:05 -07:00
bedirhancode 26685a9f34 docs(skills): fix broken related_skills references (#37338)
Salvaged from PR #38820 by @bedirhancode, re-applied at current skill
locations (obliteratus and s6 moved to optional-skills/ since the PR):

- research-paper-writing: drop ml-paper-writing (never existed)
- touchdesigner-mcp: drop native-mcp (consolidated) + hermes-video (never existed)
- obliteratus: vllm -> serving-llms-vllm, gguf -> llama-cpp
- s6-container-supervision: drop hermes-agent-dev (not a repo skill)

4 of the original 8 hunks were dropped: heartmula already fixed in
#70453; native-mcp SKILL.md deleted from main; architecture-diagram and
comfyui hunks removed refs to concept-diagrams and
stable-diffusion-image-generation, which are valid optional skills.
2026-07-24 07:54:05 -07:00
Love-JourneY 503da4e308 fix(skills): align skill directory names with frontmatter name
Salvaged from PR #42788 by @Love-JourneY, re-applied at current locations
(audiocraft and segment-anything have since moved to optional-skills/):

- skills/mlops/inference/vllm -> serving-llms-vllm
- skills/mlops/evaluation/lm-evaluation-harness -> evaluating-llms-harness
- optional-skills/mlops/models/segment-anything -> segment-anything-model
- optional-skills/creative/audiocraft -> audiocraft-audio-generation

Directory name != frontmatter name breaks skill_view() lookup by dir
name and causes hermes update sync re-seeding duplicates (#42786).
The authoring guide calls this out as Pitfall #8.

Fixes #42786
2026-07-24 07:53:54 -07:00
Teknium b0ef72a8a0 docs(skills): bring 69 skill descriptions under the 60-char authoring budget
Every SKILL.md description over 60 chars was silently truncated to
57 chars + '...' in the system-prompt skill index
(extract_skill_description, agent/skill_utils.py), destroying the
routing signal for 69 of 179 skills — some descriptions ran to
1,005 chars.

Rewrites follow the authoring standard: <=60 chars, one sentence,
ends with a period, trigger front-loaded, no marketing words, no
skill-name repetition. Excess detail already lives in each skill's
body.

Includes the touchdesigner-mcp trim from PR #32361 (credit:
@JeliTron) and aligns with the router-precision direction of PR
#48780 (@John-Lussier). Docs catalogs + per-skill pages regenerated
via website/scripts/generate-skill-docs.py.

Co-authored-by: JeliTron <287797501+JeliTron@users.noreply.github.com>
2026-07-23 21:07:16 -07:00
Teknium a56845bd8c fix(skills): add trailing periods to pinecone descriptions per authoring standard 2026-07-23 21:06:33 -07:00
iammuhammadfurqan 2978a9e9c2 fix(skills): rename pinecone-research, shorten descriptions, add scripts + tests
- Rename research/pinecone to pinecone-research (distinct from mlops/pinecone)
- Shorten mlops/pinecone description to <=60 chars
- Add rag_pipeline.py and memory_manager.py scripts
- Add test_pinecone_research_skill.py (10 tests: frontmatter, scripts, naming)
- Remove unconditional description: prefix strip from extract_skill_description()
2026-07-23 21:06:33 -07:00
upicat a4fa699a82 docs(jupyter-live-kernel): document zmq transport fallback and disable_check_xsrf pitfalls
Add two pitfalls discovered when running the skill against a fresh
Jupyter server:

- Pitfall #9: When the websocket reply channel hangs on every execute
  even though the kernel actually ran (REST shows execution_state=idle
  and execution_count increments), force zmq transport with
  --transport zmq. The zmq transport uses jupyter_client directly and
  sidesteps the broken websocket layer.

- Pitfall #10: A fresh ServerApp rejects POST /api/sessions with
  "_xsrf argument missing from POST" unless you start it with
  --ServerApp.disable_check_xsrf=True. Needed for REST-only flows
  where no browser/cookie is establishing the XSRF token.
2026-07-23 20:01:28 -07:00
teknium1 9a4d1a0130 refactor(skills): move yuanbao to optional-skills
The yuanbao skill is platform-specific guidance for Tencent Yuanbao
group chats — niche for the default bundled set. Per the
'when in doubt, optional' rule, ship it as an optional skill.

Install via: hermes skills install official/yuanbao/yuanbao
2026-07-23 19:47:46 -07:00
teknium1 832d691627 refactor(skills): move segment-anything to optional-skills
Per the 'when in doubt, optional' rule — zero-shot image segmentation
via SAM is a niche computer-vision capability with heavy deps
(torch, transformers), not something most users load.

Install via: hermes skills install official/mlops/segment-anything
2026-07-23 19:47:34 -07:00
teknium1 ba9277cc3e refactor(skills): move heartmula + audiocraft to optional-skills/creative
Both are heavy-dep, GPU-bound local music-generation skills (8-16GB VRAM,
torch stacks, manual source patches) that were bundled in two different
categories (media/ and mlops/models/). Per the 'when in doubt, optional'
rule they now sit side by side in optional-skills/creative/, and the
bundled songwriting-and-ai-music skill points at them for local generation.

- git mv skills/media/heartmula -> optional-skills/creative/heartmula
- git mv skills/mlops/models/audiocraft -> optional-skills/creative/audiocraft
- cross-link related_skills both ways + songwriting-and-ai-music
- new section 10 in songwriting-and-ai-music with install commands
- docs: bundled pages -> optional pages (en + zh-Hans), catalogs, sidebar

Install via:
  hermes skills install official/creative/heartmula
  hermes skills install official/creative/audiocraft
2026-07-23 19:47:21 -07:00
teknium1 2487dea9ce refactor(skills): move jupyter-live-kernel to optional-skills as jupyter-notebook
Per the 'when in doubt, optional' rule — the live-kernel workflow needs
uv + JupyterLab + a running server + a cloned hamelnb repo, a niche
setup that shouldn't ship active by default.

Renamed jupyter-live-kernel -> jupyter-notebook (skill name, page slugs,
catalogs, sidebar, zh-Hans mirror, darwinian-evolver related_skills).

Install via: hermes skills install official/data-science/jupyter-notebook
2026-07-23 18:36:49 -07:00
teknium1 849c17752d fix(skills/tldraw-offline): correct the computer-use delivery note
The skill claimed Chromium/Electron 'reject synthetic clicks' so computer-use
can't drive the canvas. The Cua team disproved this on the exact v1.11.0
AppImage (Linux/X11): background delivery returns background_unavailable, but
that's the first rung, not a wall — cua-driver returns escalation:'foreground'
and its X11 XTest path (x11_xtest_fg) with delivery_mode:'foreground' clicks
through, dismissing the consent dialog and landing canvas clicks.

Corrected the note to say: climb to foreground on background_unavailable, don't
conclude Electron is unclickable. Ref: NousResearch/hermes-agent#67052.
2026-07-23 08:07:00 -07:00
teknium1 e321b83392 feat(skills): add tldraw-offline agent scripting skill
Optional skill for driving the tldraw offline desktop app via its local
HTTP control API (the same curl-based path the app's own agent skills use
for Codex/Claude Code/Cursor/Gemini) — read the canvas, make live edits,
and write embedded document scripts.

Grounded in the app's bundled script-context.d.ts and agent playbook, and
in the real tldraw SDK v5 shape schema:
- document-script contract: export default function ({ editor, helpers, signal })
- HTTP API: /api/search, /api/doc/:id/exec, /api/doc/:id/script-workspace,
  /api/doc/:id/script-status (bearer token from server.json, re-read per call)
- shape schema table validated against @tldraw/tlschema (scripts/validate_shapes.mjs, 3/3)
- interactive-UI example (scripts/counter.js) + diagram-generation (scripts/main.js)
- honest verification boundary: click->state logic verified via /exec dispatch
  (0->1->2->1->0), with documented host caveats (inotify watcher, Electron
  background-click rejection)

Tests: tests/skills/test_tldraw_offline_skill.py (15 passing).
2026-07-23 08:07:00 -07:00
Teknium afb7bf6a5a
feat(skills): bundle docx, xlsx, and pdf office skills; refresh powerpoint (#68595)
Non-technical users asking for Word docs, spreadsheets, or PDF work had
no bundled skill coverage — docx/xlsx creation required discovering and
installing hub skills, and PDF manipulation had no skill at all beyond
OCR extraction and nano-pdf edits.

- skills/productivity/docx: create (docx-js), edit (unzip -> XML -> zip),
  tracked changes, comments, validation. Adapted from anthropics/skills.
- skills/productivity/xlsx: openpyxl creation/editing, mandatory
  LibreOffice recalc gate, formula-compatibility rules, financial-model
  conventions. Points at optional excel-author for finance-grade work.
- skills/productivity/pdf: merge/split/rotate/watermark/encrypt, form
  filling (AcroForm + flat overlay scripts), text/table extraction,
  reportlab creation, forms.md + reference.md companions.
- skills/productivity/powerpoint: synced to current upstream pptx skill —
  richer pptxgenjs corruption footguns, template workflow, validate.py +
  validators + thumbnail.py, font-substitution QA guidance; drops the
  stale pack.py/editing.md/pptxgenjs.md workflow files.
- Cross-linked ocr-and-documents, nano-pdf, excel-author via
  related_skills so each office skill routes to its siblings.
- deliverable-mode docs mention the new skills; regenerated per-skill
  docs pages, catalogs, and sidebar.
- tests/skills/test_office_document_skills.py: frontmatter contracts,
  referenced-script existence, schema-map integrity, cross-link
  resolution, script compilation.

E2E validated: docx create->render->edit->validate, xlsx recalc
(SUM + _xlfn.TEXTJOIN evaluate correctly), pdf create->merge->extract,
pptx generate->validate->thumbnail.
2026-07-21 05:39:23 -07:00
SHL0MS d57531b1a4 fix(unreal-mcp): pitfall 21b rewritten from live video production — hide sprites at source
Post-hoc sprite removal is a losing battle (three inpainting strategies
failed QC on letter-edge overlap frames). The production answer: sprites
are BillboardComponent/SpriteComponent/ArrowComponent subobjects — set
bVisible:false via ObjectTools (remove_component fails on default
subobjects), swept scene-wide in one ProgrammaticToolset script
(148 actors, 13 sprites, one round-trip, verified).
2026-07-16 19:30:22 -07:00
SHL0MS 665eaf1977 feat(unreal-mcp): video/frame-sequence pitfalls from live orbit production
21c: the viewport axis gizmo survives bShowUI=false — measured extent on
5.8, deterministic ffmpeg post-crop recipe. 21d: frame-sequence discipline
(one session, serial captures, idempotent resumable loop, s/frame budget,
smoothstep easing, VolumetricCloud artifact removal) — all from producing
a real 240-frame orbit through CaptureViewport.
2026-07-16 19:30:22 -07:00
SHL0MS 18694e96d8 feat(unreal-mcp): advanced-workflows layer, live-verified against UE 5.8
New references/advanced-workflows.md covering the sophisticated-workflow
surface, each section exercised against a running editor:

- ProgrammaticToolset batching: full contract (get_execution_environment
  gate, execute_tool fully-qualified names, JSON-string inputs,
  returnValue unwrapping, allowed imports) + a verified worked example
  (12-column colonnade, 36 components in one round-trip vs 37 serial calls)
- Blueprint DSL authoring loop, verified end-to-end: create -> list_graphs
  -> get_graph_dsl_docs -> find_node_types per node -> write_graph_dsl ->
  compile_blueprint -> spawn instance. Every node-ID gotcha hit live is
  recorded (EventTick not Tick, Math|Rotator|MakeRotator, registry
  categories vs doc categories, no (self) node)
- PIE session options schema (bSimulate/playMode/warmupSeconds/
  startTransform, out-of-process downgrade behavior)
- Sequencer orientation: 140-tool surface mapped by capability group +
  sibling keyframing/controlrig/conditions toolsets + minimal cinematic
  skeleton
- LogsToolset self-debugging, AutomationTestToolset CI loop,
  SemanticSearch, ConfigSettings, project AgentSkillToolset precedence
- Per-situation decision table

New pitfalls from this round's live failures: 10b (refPath-object vs
plain-string params; schema-in-error as tiebreaker), 10c (DSL node IDs
must come from find_node_types). SKILL.md: batching exception wired into
the operating loop, reference table row, description updated.
2026-07-16 19:30:22 -07:00
SHL0MS ab818493ff fix(unreal-mcp): dedupe pitfall numbering (two sections numbered 4) 2026-07-16 19:30:22 -07:00
SHL0MS d24ab20404 feat(unreal-mcp): live-verify skill against a running UE 5.8 server; encode e2e test findings
Ran the full loop against a real editor (blank project, ModelContextProtocol
+ ToolsetRegistry + AllToolsets enabled): raw MCP handshake, discovery walk,
environment relight for golden hour, primitive monument build, virtual-camera
captures with vision judgment, exposure debugging, annotated spatial capture.
67 toolsets advertised; every dispatch semantic below observed, not inferred.

Corrections and additions from the live run:
- Qualified toolset names (editor_toolset.toolsets.scene.SceneTools) with
  SHORT tool_name; TOptional params must be explicit null; find_actors
  requires ''/[] for its schema-required optionals; ObjectTools values is a
  JSON *string*; refPath object references; returnValue wrapping; per-property
  failure lists with schema-in-error
- HTTP wire contract: initialize=JSON + session header, tools/call=SSE frame
  after game-thread completion (plain-JSON clients read empty body)
- CaptureViewport as virtual camera (captureTransform, meter-unit annotation
  grid + actor callouts) verified with pixel evidence; recipes rewritten to
  use it instead of viewport piloting
- New pitfalls from real failures: template-level environment-actor
  duplication compounding into whiteouts (find-first/spawn-if-missing rule),
  template exposure calibration vs physical lux (12b), objective exposure
  check via ffprobe YAVG (12c), untitled-level Save-As modal deadlock,
  macOS full-Xcode + Metal Toolchain requirement (xcodebuild
  -downloadComponent MetalToolchain)
- Live toolset census (67 on blank project), LogsToolset/ConfigSettings/
  SemanticSearch highlights, UE EULA 6(e) licensing note
2026-07-16 19:30:22 -07:00
SHL0MS a8b81c56a0 feat(optional-skills): add unreal-mcp companion skill for the unreal-engine MCP catalog entry
Companion to optional-mcps/unreal-engine (Epic's official editor-embedded
MCP server, UE 5.8 experimental). Mirrors the blender-mcp catalog-entry +
companion-skill pattern, sized up for Unreal's discovery-based surface:

- SKILL.md: tool-search discovery contract (list_toolsets/describe_toolset/
  call_tool), serial game-thread call discipline (explicitly overrides the
  parallel-batching default), plain-English->scene translation workflow,
  save/verify hygiene, art-direction loop
- references/tool-surface.md: architecture (Unreal MCP / Toolset Registry /
  AllToolsets), confirmed shipped toolsets, call_tool dispatch semantics,
  project Agent Skills (AgentSkillToolset), capture paths, custom Python/C++
  toolset authoring, config/CVar/console reference, cooked-build notes
- references/scene-craft.md: physically-based lighting values (lux/lumens/
  Kelvin/EV100), mood recipes, Lumen Movable-mobility rule, scale tables,
  content-path conventions, CineCamera framing, editor Python entry points
- references/recipes.md: four end-to-end builds in INTENT/DISCOVER/VALUES/
  VERIFY grammar (exterior, night interior, golden-hour cinematic still,
  import+populate) that stay honest about the project-dependent surface
- references/pitfalls.md: 25+ failure modes with fixes: start order, modal
  deadlocks, Hermes-timeout-vs-editor-completion, _C class suffix, PascalCase
  silent no-op writes, referenced-asset delete crash, async shader compiles,
  editor sprite icons in screenshots, PIE interference

Grounded in Epic's UE 5.8 docs and Epic's agent-facing skill pack for this
server; no fabricated tool names — live describe_toolset schemas are the
contract throughout.
2026-07-16 19:30:22 -07:00
teknium1 5f171e36ab chore(skills/mcp-oauth-remote-gateway): move to optional-skills + modernize
- Move skills/mcp/ -> optional-skills/mcp/ (niche remote-deployment
  workflow; bundled tier is for daily-driver skills)
- Frontmatter: description 421 -> 57 chars, add platforms gating
  [linux, macos] (bash pipelines + gateway hosts), credit Ben Barclay
  first in author
- Document the built-in flow's own escape hatches (paste-back prompt,
  ssh -N -L port-forward) as cheap first fallbacks before manual
  token surgery; scope the skill to no-TTY messaging-gateway contexts
- Frame execution through the terminal / execute_code tools
- Tests: tests/skills/test_mcp_oauth_remote_gateway_skill.py covers
  all four diagnostic branches, atomic --write persistence, 0600
  perms, httpx UA on the wire, no-secrets-in-stdout, and frontmatter
  invariants (9 passing)
- Regen auto-gen docs page + one-line catalog row + sidebar entry
  (scoped; unrelated generator drift reverted)
2026-07-16 01:28:32 -07:00
Teknium b6c11a35ac refactor(skills): adapt salvaged references to the MCP-tool surface, bump to 2.1.0
Follow-up on kshitijk4poor's cherry-picked references:
- pitfalls.md rewritten from the raw-socket blender_exec() frame to the
  MCP-tool frame (dropped 'MCP server is optional, talk to the socket
  directly' — now the anti-pattern; dropped TCP-helper internals items;
  kept all bpy/addon knowledge: empty code results in 5.x, temp-file
  readback, ops-vs-data context, engine names by version, GPU setup)
- recipes.md: blender_exec -> execute_blender_code in the agent-side
  verification snippet
- SKILL.md: reference-file table added to Quick Reference, version
  2.1.0, kshitijk4poor added to authors
- docs page regenerated (scoped to this skill)
2026-07-15 12:28:13 -07:00
kshitijk4poor 5601f24449 feat(skills): enhance blender-mcp with comprehensive references and recipes
- Rewrite SKILL.md with full setup guide, MCP config, typed commands, object types table
- Add references/bpy-api.md: scene, transforms, bmesh, materials, modifiers, camera, rendering, animation
- Add references/pitfalls.md: 19 real-session pitfalls (connection, Python exec, rendering, version quirks)
- Add references/recipes.md: 5 copy-paste recipes (landscape, glass sphere, donut, turntable, render)
- Preserve original blender-mcp name and credit to alireza78a
- Tested with Blender 5.1 on macOS
2026-07-15 12:28:13 -07:00