From c49fa88b80753071e7b7bb83e2882232e43e87c0 Mon Sep 17 00:00:00 2001 From: Teknium <127238744+teknium1@users.noreply.github.com> Date: Sun, 30 Aug 2026 04:53:39 -0700 Subject: [PATCH] =?UTF-8?q?refactor(skills):=20shipped-set=20slim=20?= =?UTF-8?q?=E2=80=94=2015=20to=20optional,=20github=206-way=20merge,=20pdf?= =?UTF-8?q?=20absorbs=20OCR,=20channel-gated=20teams=20pipeline=20(index?= =?UTF-8?q?=20=E2=88=9226%)=20(#98539)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * refactor(skills): shipped-set slim — 15 skills to optional, github six-way merge, pdf absorbs OCR+nano-pdf, channel-gated teams pipeline Maintainer-directed shipped-skills curation (skills index 1,900 -> ~1,400 tok/call on desktop; every session pays the index, so this is a per-call diet on all installs): - optional-skills moves (installable via skills hub, history preserved): creative comfyui/ascii-art/excalidraw/pretext/sketch/touchdesigner-mcp; ALL of mlops (huggingface-hub, llama-cpp, serving-llms-vllm, weights-and-biases, evaluating-llms-harness — subcategory structure kept); research-paper-writing (55 supporting files, 17.3K-tok load); openhue; blogwatcher (first taught the cronjob monitor-field watch pattern + web_extract instead of pre-cron manual workflows) - DELETED session-librarian (Aug-12 'inspired by Perplexity Computer' port, never maintainer-intended; session_search covers discovery) - github: six skills (auth, issues, pr-workflow, issue-to-pr, code-review, repo-management) merged into ONE software-development/ github skill — routing body + complete per-workflow references; benbarclay authorship credited; codebase-inspection rides along; discipline pins from test_github_issue_to_pr_skill.py preserved against the reference body in the new test_github_skill.py - pdf absorbs ocr-and-documents + nano-pdf as references/ + scripts (extract_pymupdf, extract_marker converted to the argparse house standard its contract test enforces) - NEW session_platforms frontmatter gate (metadata.hermes): hides a skill from the index on gateway channels it is not for; fail-open on unknown platform; teams-meeting-pipeline gated to [teams, cron] - blocked-page-recovery: research -> new web category; trigger-first description ('Use when a fetch fails: 403/429, paywall, WAF, bot wall.') so the model actually reaches for it on blocked fetches - docs regenerated via generate-skill-docs.py (195 pages); related_skills swept repo-wide; tests: 1672 passed (2 openclaw failures pre-existing on clean main, Windows-local) * chore: ignore .skills_prompt_snapshot.json (local index cache, accidentally committed) --- .gitignore | 1 + SOUL.md | 1 + agent/prompt_builder.py | 19 + agent/skill_utils.py | 7 + .../creative/ascii-art/SKILL.md | 0 .../creative/comfyui/SKILL.md | 0 .../comfyui/references/official-cli.md | 0 .../creative/comfyui/references/rest-api.md | 0 .../comfyui/references/template-integrity.md | 0 .../comfyui/references/workflow-format.md | 0 .../creative/comfyui/scripts/_common.py | 0 .../creative/comfyui/scripts/auto_fix_deps.py | 0 .../creative/comfyui/scripts/check_deps.py | 0 .../creative/comfyui/scripts/comfyui_setup.sh | 0 .../comfyui/scripts/extract_schema.py | 0 .../creative/comfyui/scripts/fetch_logs.py | 0 .../comfyui/scripts/hardware_check.py | 0 .../creative/comfyui/scripts/health_check.py | 0 .../creative/comfyui/scripts/run_batch.py | 0 .../creative/comfyui/scripts/run_workflow.py | 0 .../creative/comfyui/scripts/ws_monitor.py | 0 .../creative/comfyui/tests/README.md | 0 .../creative/comfyui/tests/conftest.py | 0 .../creative/comfyui/tests/pytest.ini | 0 .../creative/comfyui/tests/test_check_deps.py | 0 .../comfyui/tests/test_cloud_integration.py | 0 .../creative/comfyui/tests/test_common.py | 0 .../comfyui/tests/test_extract_schema.py | 0 .../comfyui/tests/test_run_workflow.py | 0 .../creative/comfyui/workflows/README.md | 0 .../comfyui/workflows/animatediff_video.json | 0 .../comfyui/workflows/flux_dev_txt2img.json | 0 .../comfyui/workflows/sd15_txt2img.json | 0 .../comfyui/workflows/sdxl_img2img.json | 0 .../comfyui/workflows/sdxl_inpaint.json | 0 .../comfyui/workflows/sdxl_txt2img.json | 0 .../comfyui/workflows/upscale_4x.json | 0 .../comfyui/workflows/wan_video_t2v.json | 0 .../creative/excalidraw/SKILL.md | 0 .../creative/excalidraw/references/colors.md | 0 .../excalidraw/references/dark-mode.md | 0 .../excalidraw/references/examples.md | 0 .../creative/excalidraw/scripts/upload.py | 0 .../creative/pretext/SKILL.md | 0 .../creative/pretext/references/patterns.md | 0 .../pretext/templates/donut-orbit.html | 0 .../pretext/templates/hello-orb-flow.html | 0 .../creative/sketch/SKILL.md | 0 .../creative/touchdesigner-mcp/SKILL.md | 0 .../touchdesigner-mcp/references/3d-scene.md | 0 .../touchdesigner-mcp/references/animation.md | 0 .../references/audio-reactive.md | 0 .../references/dat-scripting.md | 0 .../references/external-data.md | 0 .../references/geometry-comp.md | 0 .../touchdesigner-mcp/references/glsl.md | 0 .../references/layout-compositor.md | 0 .../touchdesigner-mcp/references/mcp-tools.md | 0 .../touchdesigner-mcp/references/midi-osc.md | 0 .../references/network-patterns.md | 0 .../references/operator-tips.md | 0 .../touchdesigner-mcp/references/operators.md | 0 .../touchdesigner-mcp/references/panel-ui.md | 0 .../touchdesigner-mcp/references/particles.md | 0 .../touchdesigner-mcp/references/pitfalls.md | 0 .../touchdesigner-mcp/references/postfx.md | 0 .../references/projection-mapping.md | 0 .../references/python-api.md | 0 .../references/replicator.md | 0 .../references/troubleshooting.md | 0 .../touchdesigner-mcp/scripts/setup.sh | 0 .../mlops/evaluation/DESCRIPTION.md | 0 .../evaluating-llms-harness/SKILL.md | 0 .../references/api-evaluation.md | 0 .../references/benchmark-guide.md | 0 .../references/custom-tasks.md | 0 .../references/distributed-eval.md | 0 .../evaluation/weights-and-biases/SKILL.md | 0 .../references/artifacts.md | 0 .../references/integrations.md | 0 .../weights-and-biases/references/sweeps.md | 0 .../mlops/inference/DESCRIPTION.md | 0 .../mlops/inference/llama-cpp/SKILL.md | 0 .../llama-cpp/references/advanced-usage.md | 0 .../llama-cpp/references/hub-discovery.md | 0 .../llama-cpp/references/optimization.md | 0 .../llama-cpp/references/quantization.md | 0 .../inference/llama-cpp/references/server.md | 0 .../llama-cpp/references/troubleshooting.md | 0 .../inference/serving-llms-vllm/SKILL.md | 0 .../references/optimization.md | 0 .../references/quantization.md | 0 .../references/server-deployment.md | 0 .../references/troubleshooting.md | 0 .../mlops/models/DESCRIPTION.md | 0 .../mlops/models}/huggingface-hub/SKILL.md | 0 .../research/blogwatcher/SKILL.md | 9 + .../research/research-paper-writing/SKILL.md | 0 .../references/autoreason-methodology.md | 0 .../references/checklists.md | 0 .../references/citation-workflow.md | 0 .../references/experiment-patterns.md | 0 .../references/human-evaluation.md | 0 .../references/paper-types.md | 0 .../references/phase5-paper-drafting.md | 0 .../references/reviewer-guidelines.md | 0 .../references/sources.md | 0 .../references/writing-guide.md | 0 .../templates/README.md | 0 .../templates/aaai2026/README.md | 0 .../aaai2026/aaai2026-unified-supp.tex | 0 .../aaai2026/aaai2026-unified-template.tex | 0 .../templates/aaai2026/aaai2026.bib | 0 .../templates/aaai2026/aaai2026.bst | 0 .../templates/aaai2026/aaai2026.sty | 0 .../templates/acl/README.md | 0 .../templates/acl/acl.sty | 0 .../templates/acl/acl_latex.tex | 0 .../templates/acl/acl_lualatex.tex | 0 .../templates/acl/acl_natbib.bst | 0 .../templates/acl/anthology.bib.txt | 0 .../templates/acl/custom.bib | 0 .../templates/acl/formatting.md | 0 .../templates/colm2025/README.md | 0 .../colm2025/colm2025_conference.bib | 0 .../colm2025/colm2025_conference.bst | 0 .../colm2025/colm2025_conference.pdf | Bin .../colm2025/colm2025_conference.sty | 0 .../colm2025/colm2025_conference.tex | 0 .../templates/colm2025/fancyhdr.sty | 0 .../templates/colm2025/math_commands.tex | 0 .../templates/colm2025/natbib.sty | 0 .../templates/iclr2026/fancyhdr.sty | 0 .../iclr2026/iclr2026_conference.bib | 0 .../iclr2026/iclr2026_conference.bst | 0 .../iclr2026/iclr2026_conference.pdf | Bin .../iclr2026/iclr2026_conference.sty | 0 .../iclr2026/iclr2026_conference.tex | 0 .../templates/iclr2026/math_commands.tex | 0 .../templates/iclr2026/natbib.sty | 0 .../templates/icml2026/algorithm.sty | 0 .../templates/icml2026/algorithmic.sty | 0 .../templates/icml2026/example_paper.bib | 0 .../templates/icml2026/example_paper.pdf | Bin .../templates/icml2026/example_paper.tex | 0 .../templates/icml2026/fancyhdr.sty | 0 .../templates/icml2026/icml2026.bst | 0 .../templates/icml2026/icml2026.sty | 0 .../templates/icml2026/icml_numpapers.pdf | Bin .../templates/neurips2025/Makefile | 0 .../templates/neurips2025/extra_pkgs.tex | 0 .../templates/neurips2025/main.tex | 0 .../templates/neurips2025/neurips.sty | 0 .../smart-home/DESCRIPTION.md | 0 .../smart-home/openhue/SKILL.md | 0 .../software-development/code-wiki/SKILL.md | 2 +- skills/github/DESCRIPTION.md | 3 - skills/mlops/DESCRIPTION.md | 3 - .../document-to-action-items/SKILL.md | 8 +- .../ocr-and-documents/DESCRIPTION.md | 3 - skills/productivity/pdf/SKILL.md | 19 +- .../references/nano-pdf-editing.md} | 15 +- .../references/ocr-extraction.md} | 14 +- .../scripts/extract_marker.py | 39 +- .../scripts/extract_pymupdf.py | 49 +- .../pdf/scripts/pdf_page_image.py | 2 +- skills/productivity/pdf/scripts/pdf_read.py | 2 +- .../productivity/session-librarian/SKILL.md | 105 -- .../teams-meeting-pipeline/SKILL.md | 4 + skills/research/arxiv/SKILL.md | 2 +- skills/research/grounded-citations/SKILL.md | 4 +- .../references/citation-formats.md | 2 +- .../codebase-inspection/SKILL.md | 2 +- skills/software-development/github/SKILL.md | 56 + .../github/references/auth.md} | 13 - .../github}/references/ci-troubleshooting.md | 0 .../github/references/code-review.md} | 13 - .../references/conventional-commits.md | 0 .../references/github-api-cheatsheet.md | 0 .../github/references/issue-to-pr.md} | 13 - .../github/references/issues.md} | 13 - .../github/references/pr-workflow.md} | 13 - .../github/references/repo-management.md} | 13 - .../references/review-output-template.md | 0 .../github}/scripts/gh-env.sh | 0 .../github}/scripts/git-credential-token.py | 0 .../github}/templates/bug-report.md | 0 .../github}/templates/feature-request.md | 0 .../github}/templates/pr-body-bugfix.md | 0 .../github}/templates/pr-body-feature.md | 0 .../requesting-code-review/SKILL.md | 6 +- skills/web/DESCRIPTION.md | 3 + .../blocked-page-recovery/SKILL.md | 2 +- .../scripts/recover_page.py | 0 .../agent/test_skill_session_platform_gate.py | 48 + tests/skills/test_comfyui_skill.py | 4 +- tests/skills/test_github_credential_token.py | 8 +- ...ue_to_pr_skill.py => test_github_skill.py} | 68 +- .../docs/reference/optional-skills-catalog.md | 25 +- website/docs/reference/skills-catalog.md | 163 +- .../skills/bundled/apple/apple-apple-notes.md | 2 +- .../bundled/apple/apple-apple-reminders.md | 2 +- .../skills/bundled/apple/apple-findmy.md | 2 +- .../skills/bundled/apple/apple-imessage.md | 2 +- .../autonomous-ai-agents-claude-code.md | 6 +- .../autonomous-ai-agents-codex.md | 2 +- .../autonomous-ai-agents-computer-use.md | 2 +- .../autonomous-ai-agents-hermes-agent.md | 19 +- .../autonomous-ai-agents-merge-reconciler.md | 176 ++ .../autonomous-ai-agents-opencode.md | 2 +- .../creative/creative-architecture-diagram.md | 4 +- .../bundled/creative/creative-ascii-video.md | 2 +- .../creative/creative-baoyu-infographic.md | 2 +- .../creative/creative-claude-design.md | 4 +- .../bundled/creative/creative-design-md.md | 4 +- .../bundled/creative/creative-humanizer.md | 2 +- .../bundled/creative/creative-manim-video.md | 2 +- .../skills/bundled/creative/creative-p5js.md | 8 +- .../creative/creative-popular-web-designs.md | 2 +- .../creative-songwriting-and-ai-music.md | 2 +- .../bundled/devops/devops-sdlc-review.md | 195 ++ .../bundled/email/email-email-inbox-triage.md | 2 +- .../skills/bundled/email/email-himalaya.md | 2 +- .../skills/bundled/media/media-gif-search.md | 4 +- .../skills/bundled/media/media-songsee.md | 2 +- .../bundled/media/media-youtube-content.md | 12 +- .../note-taking/note-taking-obsidian.md | 2 +- .../productivity/productivity-airtable.md | 42 +- .../bundled/productivity/productivity-box.md | 38 +- .../productivity-document-to-action-items.md | 10 +- .../bundled/productivity/productivity-docx.md | 137 +- .../productivity-google-workspace.md | 2 +- .../bundled/productivity/productivity-maps.md | 44 +- .../productivity-meeting-action-items.md | 2 +- .../productivity/productivity-notion.md | 2 +- .../bundled/productivity/productivity-pdf.md | 89 +- .../productivity/productivity-powerpoint.md | 167 +- .../productivity-product-price-monitor.md | 2 +- .../productivity-teams-meeting-pipeline.md | 2 +- .../productivity-weekly-review-planning.md | 2 +- .../bundled/productivity/productivity-xlsx.md | 88 +- .../skills/bundled/research/research-arxiv.md | 24 +- .../research-competitor-news-monitor.md | 4 +- .../research/research-grounded-citations.md | 26 +- .../bundled/research/research-llm-wiki.md | 2 +- .../bundled/social-media/social-media-xurl.md | 2 +- ...oftware-development-codebase-inspection.md | 132 ++ .../software-development-dogfood.md | 2 +- .../software-development-github.md | 73 + ...evelopment-hermes-agent-skill-authoring.md | 6 +- ...velopment-inspecting-hermes-desktop-dom.md | 2 +- ...tware-development-node-inspect-debugger.md | 2 +- .../software-development-python-debugpy.md | 2 +- ...ware-development-requesting-code-review.md | 8 +- .../software-development-simplify-code.md | 4 +- .../software-development-spike.md | 6 +- ...ftware-development-systematic-debugging.md | 4 +- ...are-development-test-driven-development.md | 4 +- .../bundled/web/web-blocked-page-recovery.md | 155 ++ .../autonomous-ai-agents-antigravity-cli.md | 2 +- .../autonomous-ai-agents-blackbox.md | 2 +- .../autonomous-ai-agents-grok.md | 2 +- .../autonomous-ai-agents-honcho.md | 2 +- .../autonomous-ai-agents-openhands.md | 2 +- .../optional/blockchain/blockchain-evm.md | 80 +- .../blockchain/blockchain-hyperliquid.md | 34 +- .../optional/blockchain/blockchain-solana.md | 46 +- .../communication-one-three-one-rule.md | 2 +- .../optional/creative/creative-ascii-art.md | 338 ++++ .../creative-audiocraft-audio-generation.md | 6 +- .../creative-baoyu-article-illustrator.md | 28 +- .../optional/creative/creative-baoyu-comic.md | 24 +- .../optional/creative/creative-comfyui.md | 616 ++++++ .../creative/creative-concept-diagrams.md | 6 +- .../creative/creative-creative-ideation.md | 2 +- .../creative/creative-draw-your-font.md | 8 +- .../optional/creative/creative-excalidraw.md | 212 +++ .../optional/creative/creative-heartmula.md | 2 +- .../optional/creative/creative-hyperframes.md | 45 +- .../optional/creative/creative-impeccable.md | 2 +- .../creative-kanban-video-orchestrator.md | 16 +- .../creative/creative-meme-generation.md | 4 +- .../optional/creative/creative-pixel-art.md | 7 +- .../optional/creative/creative-pretext.md | 238 +++ .../creative/creative-simple-english.md | 12 +- .../optional/creative/creative-sketch.md | 240 +++ .../creative-social-media-content-calendar.md | 2 +- .../creative/creative-tldraw-offline.md | 6 +- .../creative/creative-touchdesigner-mcp.md | 373 ++++ .../optional/creative/creative-unreal-mcp.md | 2 +- .../data-science-jupyter-notebook.md | 4 +- .../optional/devops/devops-actual-setup.md | 2 +- .../devops/devops-docker-management.md | 5 +- .../devops-hermes-s6-container-supervision.md | 7 +- .../devops/devops-inference-sh-cli.md | 2 +- .../optional/devops/devops-pinggy-tunnel.md | 10 +- .../devops/devops-setup-wizard-generator.md | 2 +- .../skills/optional/devops/devops-watchers.md | 2 +- .../dogfood/dogfood-adversarial-ux-test.md | 2 +- .../skills/optional/email/email-agentmail.md | 22 +- .../finance/finance-3-statement-model.md | 6 +- .../finance/finance-comps-analysis.md | 2 +- .../optional/finance/finance-dcf-model.md | 6 +- .../optional/finance/finance-excel-author.md | 2 +- .../optional/finance/finance-lbo-model.md | 2 +- .../optional/finance/finance-merger-model.md | 2 +- .../optional/finance/finance-polymarket.md | 2 +- .../optional/finance/finance-pptx-author.md | 2 +- .../skills/optional/finance/finance-stocks.md | 18 +- .../gaming/gaming-minecraft-modpack-server.md | 2 +- .../optional/gaming/gaming-pokemon-player.md | 4 +- .../health/health-fitness-nutrition.md | 28 +- .../optional/health/health-neuroskill-bci.md | 2 +- .../skills/optional/mcp/mcp-fastmcp.md | 2 +- .../mcp/mcp-mcp-oauth-remote-gateway.md | 2 +- .../skills/optional/mcp/mcp-mcporter.md | 2 +- .../migration/migration-openclaw-migration.md | 14 +- .../skills/optional/mlops/mlops-accelerate.md | 8 +- .../skills/optional/mlops/mlops-chroma.md | 2 +- .../skills/optional/mlops/mlops-clip.md | 2 +- ...lops-evaluation-evaluating-llms-harness.md | 512 +++++ .../mlops-evaluation-weights-and-biases.md | 613 ++++++ .../skills/optional/mlops/mlops-faiss.md | 2 +- .../optional/mlops/mlops-flash-attention.md | 6 +- .../skills/optional/mlops/mlops-guidance.md | 2 +- .../mlops/mlops-huggingface-tokenizers.md | 10 +- .../mlops/mlops-inference-llama-cpp.md | 267 +++ .../mlops/mlops-inference-outlines.md | 2 +- .../mlops-inference-serving-llms-vllm.md | 387 ++++ .../skills/optional/mlops/mlops-instructor.md | 2 +- .../optional/mlops/mlops-lambda-labs.md | 6 +- .../skills/optional/mlops/mlops-llava.md | 2 +- .../skills/optional/mlops/mlops-modal.md | 6 +- .../mlops/mlops-models-huggingface-hub.md | 100 + .../mlops-models-segment-anything-model.md | 10 +- .../optional/mlops/mlops-nemo-curator.md | 6 +- .../optional/mlops/mlops-obliteratus.md | 4 +- .../skills/optional/mlops/mlops-peft.md | 6 +- .../skills/optional/mlops/mlops-pinecone.md | 2 +- .../optional/mlops/mlops-pytorch-fsdp.md | 2 +- .../optional/mlops/mlops-pytorch-lightning.md | 8 +- .../skills/optional/mlops/mlops-qdrant.md | 6 +- .../optional/mlops/mlops-research-dspy.md | 2 +- .../skills/optional/mlops/mlops-saelens.md | 8 +- .../skills/optional/mlops/mlops-simpo.md | 8 +- .../skills/optional/mlops/mlops-slime.md | 2 +- .../optional/mlops/mlops-stable-diffusion.md | 6 +- .../optional/mlops/mlops-tensorrt-llm.md | 8 +- .../skills/optional/mlops/mlops-torchtitan.md | 10 +- .../optional/mlops/mlops-training-axolotl.md | 2 +- .../mlops/mlops-training-trl-fine-tuning.md | 14 +- .../optional/mlops/mlops-training-unsloth.md | 2 +- .../skills/optional/mlops/mlops-whisper.md | 2 +- .../optional/payments/payments-mpp-agent.md | 2 +- .../payments/payments-stripe-link-cli.md | 2 +- .../payments/payments-stripe-projects.md | 2 +- .../productivity/productivity-canvas.md | 2 +- .../productivity-decision-questionnaire.md | 2 +- .../productivity/productivity-here-now.md | 2 +- .../productivity-memento-flashcards.md | 2 +- .../productivity/productivity-shop.md | 16 +- .../productivity/productivity-shopify.md | 2 +- .../productivity/productivity-siyuan.md | 2 +- .../productivity/productivity-telephony.md | 58 +- .../research/research-bioinformatics.md | 2 +- .../optional/research/research-blogwatcher.md | 161 ++ .../research/research-darwinian-evolver.md | 2 +- .../research/research-domain-intel.md | 16 +- .../research/research-drug-discovery.md | 28 +- .../research/research-duckduckgo-search.md | 2 +- .../research/research-gitnexus-explorer.md | 4 +- .../research/research-osint-investigation.md | 32 +- .../research/research-parallel-cli.md | 2 +- .../research/research-pinecone-research.md | 2 +- .../skills/optional/research/research-qmd.md | 2 +- .../research-research-paper-writing.md | 1645 +++++++++++++++++ .../optional/research/research-scrapling.md | 2 +- .../research/research-searxng-search.md | 2 +- .../optional/security/security-1password.md | 4 +- .../optional/security/security-godmode.md | 4 +- .../security/security-oss-forensics.md | 38 +- .../optional/security/security-sherlock.md | 2 +- .../optional/security/security-unbroker.md | 10 +- .../optional/security/security-web-pentest.md | 2 +- .../optional/smart-home/smart-home-openhue.md | 127 ++ .../software-development-ast-grep.md | 307 +++ .../software-development-code-wiki.md | 30 +- .../software-development-grill-me.md | 4 +- ...software-development-rest-graphql-debug.md | 4 +- ...development-subagent-driven-development.md | 4 +- ...development-cloudflare-temporary-deploy.md | 8 +- .../web-development-har-derived-api-client.md | 180 ++ .../web-development-page-agent.md | 2 +- .../web-development-publish-site.md | 2 +- website/sidebars.ts | 94 +- 395 files changed, 8466 insertions(+), 1231 deletions(-) create mode 100644 SOUL.md rename {skills => optional-skills}/creative/ascii-art/SKILL.md (100%) rename {skills => optional-skills}/creative/comfyui/SKILL.md (100%) rename {skills => optional-skills}/creative/comfyui/references/official-cli.md (100%) rename {skills => optional-skills}/creative/comfyui/references/rest-api.md (100%) rename {skills => optional-skills}/creative/comfyui/references/template-integrity.md (100%) rename {skills => optional-skills}/creative/comfyui/references/workflow-format.md (100%) rename {skills => optional-skills}/creative/comfyui/scripts/_common.py (100%) rename {skills => optional-skills}/creative/comfyui/scripts/auto_fix_deps.py (100%) rename {skills => optional-skills}/creative/comfyui/scripts/check_deps.py (100%) rename {skills => optional-skills}/creative/comfyui/scripts/comfyui_setup.sh (100%) rename {skills => optional-skills}/creative/comfyui/scripts/extract_schema.py (100%) rename {skills => optional-skills}/creative/comfyui/scripts/fetch_logs.py (100%) rename {skills => optional-skills}/creative/comfyui/scripts/hardware_check.py (100%) rename {skills => optional-skills}/creative/comfyui/scripts/health_check.py (100%) rename {skills => optional-skills}/creative/comfyui/scripts/run_batch.py (100%) rename {skills => optional-skills}/creative/comfyui/scripts/run_workflow.py (100%) rename {skills => optional-skills}/creative/comfyui/scripts/ws_monitor.py (100%) rename {skills => optional-skills}/creative/comfyui/tests/README.md (100%) rename {skills => optional-skills}/creative/comfyui/tests/conftest.py (100%) rename {skills => optional-skills}/creative/comfyui/tests/pytest.ini (100%) rename {skills => optional-skills}/creative/comfyui/tests/test_check_deps.py (100%) rename {skills => optional-skills}/creative/comfyui/tests/test_cloud_integration.py (100%) rename {skills => optional-skills}/creative/comfyui/tests/test_common.py (100%) rename {skills => optional-skills}/creative/comfyui/tests/test_extract_schema.py (100%) rename {skills => optional-skills}/creative/comfyui/tests/test_run_workflow.py (100%) rename {skills => optional-skills}/creative/comfyui/workflows/README.md (100%) rename {skills => optional-skills}/creative/comfyui/workflows/animatediff_video.json (100%) rename {skills => optional-skills}/creative/comfyui/workflows/flux_dev_txt2img.json (100%) rename {skills => optional-skills}/creative/comfyui/workflows/sd15_txt2img.json (100%) rename {skills => optional-skills}/creative/comfyui/workflows/sdxl_img2img.json (100%) rename {skills => optional-skills}/creative/comfyui/workflows/sdxl_inpaint.json (100%) rename {skills => optional-skills}/creative/comfyui/workflows/sdxl_txt2img.json (100%) rename {skills => optional-skills}/creative/comfyui/workflows/upscale_4x.json (100%) rename {skills => optional-skills}/creative/comfyui/workflows/wan_video_t2v.json (100%) rename {skills => optional-skills}/creative/excalidraw/SKILL.md (100%) rename {skills => optional-skills}/creative/excalidraw/references/colors.md (100%) rename {skills => optional-skills}/creative/excalidraw/references/dark-mode.md (100%) rename {skills => optional-skills}/creative/excalidraw/references/examples.md (100%) rename {skills => optional-skills}/creative/excalidraw/scripts/upload.py (100%) rename {skills => optional-skills}/creative/pretext/SKILL.md (100%) rename {skills => optional-skills}/creative/pretext/references/patterns.md (100%) rename {skills => optional-skills}/creative/pretext/templates/donut-orbit.html (100%) rename {skills => optional-skills}/creative/pretext/templates/hello-orb-flow.html (100%) rename {skills => optional-skills}/creative/sketch/SKILL.md (100%) rename {skills => optional-skills}/creative/touchdesigner-mcp/SKILL.md (100%) rename {skills => optional-skills}/creative/touchdesigner-mcp/references/3d-scene.md (100%) rename {skills => optional-skills}/creative/touchdesigner-mcp/references/animation.md (100%) rename {skills => optional-skills}/creative/touchdesigner-mcp/references/audio-reactive.md (100%) rename {skills => optional-skills}/creative/touchdesigner-mcp/references/dat-scripting.md (100%) rename {skills => optional-skills}/creative/touchdesigner-mcp/references/external-data.md (100%) rename {skills => optional-skills}/creative/touchdesigner-mcp/references/geometry-comp.md (100%) rename {skills => optional-skills}/creative/touchdesigner-mcp/references/glsl.md (100%) rename {skills => optional-skills}/creative/touchdesigner-mcp/references/layout-compositor.md (100%) rename {skills => optional-skills}/creative/touchdesigner-mcp/references/mcp-tools.md (100%) rename {skills => optional-skills}/creative/touchdesigner-mcp/references/midi-osc.md (100%) rename {skills => optional-skills}/creative/touchdesigner-mcp/references/network-patterns.md (100%) rename {skills => optional-skills}/creative/touchdesigner-mcp/references/operator-tips.md (100%) rename {skills => optional-skills}/creative/touchdesigner-mcp/references/operators.md (100%) rename {skills => optional-skills}/creative/touchdesigner-mcp/references/panel-ui.md (100%) rename {skills => optional-skills}/creative/touchdesigner-mcp/references/particles.md (100%) rename {skills => optional-skills}/creative/touchdesigner-mcp/references/pitfalls.md (100%) rename {skills => optional-skills}/creative/touchdesigner-mcp/references/postfx.md (100%) rename {skills => optional-skills}/creative/touchdesigner-mcp/references/projection-mapping.md (100%) rename {skills => optional-skills}/creative/touchdesigner-mcp/references/python-api.md (100%) rename {skills => optional-skills}/creative/touchdesigner-mcp/references/replicator.md (100%) rename {skills => optional-skills}/creative/touchdesigner-mcp/references/troubleshooting.md (100%) rename {skills => optional-skills}/creative/touchdesigner-mcp/scripts/setup.sh (100%) rename {skills => optional-skills}/mlops/evaluation/DESCRIPTION.md (100%) rename {skills => optional-skills}/mlops/evaluation/evaluating-llms-harness/SKILL.md (100%) rename {skills => optional-skills}/mlops/evaluation/evaluating-llms-harness/references/api-evaluation.md (100%) rename {skills => optional-skills}/mlops/evaluation/evaluating-llms-harness/references/benchmark-guide.md (100%) rename {skills => optional-skills}/mlops/evaluation/evaluating-llms-harness/references/custom-tasks.md (100%) rename {skills => optional-skills}/mlops/evaluation/evaluating-llms-harness/references/distributed-eval.md (100%) rename {skills => optional-skills}/mlops/evaluation/weights-and-biases/SKILL.md (100%) rename {skills => optional-skills}/mlops/evaluation/weights-and-biases/references/artifacts.md (100%) rename {skills => optional-skills}/mlops/evaluation/weights-and-biases/references/integrations.md (100%) rename {skills => optional-skills}/mlops/evaluation/weights-and-biases/references/sweeps.md (100%) rename {skills => optional-skills}/mlops/inference/DESCRIPTION.md (100%) rename {skills => optional-skills}/mlops/inference/llama-cpp/SKILL.md (100%) rename {skills => optional-skills}/mlops/inference/llama-cpp/references/advanced-usage.md (100%) rename {skills => optional-skills}/mlops/inference/llama-cpp/references/hub-discovery.md (100%) rename {skills => optional-skills}/mlops/inference/llama-cpp/references/optimization.md (100%) rename {skills => optional-skills}/mlops/inference/llama-cpp/references/quantization.md (100%) rename {skills => optional-skills}/mlops/inference/llama-cpp/references/server.md (100%) rename {skills => optional-skills}/mlops/inference/llama-cpp/references/troubleshooting.md (100%) rename {skills => optional-skills}/mlops/inference/serving-llms-vllm/SKILL.md (100%) rename {skills => optional-skills}/mlops/inference/serving-llms-vllm/references/optimization.md (100%) rename {skills => optional-skills}/mlops/inference/serving-llms-vllm/references/quantization.md (100%) rename {skills => optional-skills}/mlops/inference/serving-llms-vllm/references/server-deployment.md (100%) rename {skills => optional-skills}/mlops/inference/serving-llms-vllm/references/troubleshooting.md (100%) rename {skills => optional-skills}/mlops/models/DESCRIPTION.md (100%) rename {skills/mlops => optional-skills/mlops/models}/huggingface-hub/SKILL.md (100%) rename {skills => optional-skills}/research/blogwatcher/SKILL.md (82%) rename {skills => optional-skills}/research/research-paper-writing/SKILL.md (100%) rename {skills => optional-skills}/research/research-paper-writing/references/autoreason-methodology.md (100%) rename {skills => optional-skills}/research/research-paper-writing/references/checklists.md (100%) rename {skills => optional-skills}/research/research-paper-writing/references/citation-workflow.md (100%) rename {skills => optional-skills}/research/research-paper-writing/references/experiment-patterns.md (100%) rename {skills => optional-skills}/research/research-paper-writing/references/human-evaluation.md (100%) rename {skills => optional-skills}/research/research-paper-writing/references/paper-types.md (100%) rename {skills => optional-skills}/research/research-paper-writing/references/phase5-paper-drafting.md (100%) rename {skills => optional-skills}/research/research-paper-writing/references/reviewer-guidelines.md (100%) rename {skills => optional-skills}/research/research-paper-writing/references/sources.md (100%) rename {skills => optional-skills}/research/research-paper-writing/references/writing-guide.md (100%) rename {skills => optional-skills}/research/research-paper-writing/templates/README.md (100%) rename {skills => optional-skills}/research/research-paper-writing/templates/aaai2026/README.md (100%) rename {skills => optional-skills}/research/research-paper-writing/templates/aaai2026/aaai2026-unified-supp.tex (100%) rename {skills => optional-skills}/research/research-paper-writing/templates/aaai2026/aaai2026-unified-template.tex (100%) rename {skills => optional-skills}/research/research-paper-writing/templates/aaai2026/aaai2026.bib (100%) rename {skills => optional-skills}/research/research-paper-writing/templates/aaai2026/aaai2026.bst (100%) rename {skills => optional-skills}/research/research-paper-writing/templates/aaai2026/aaai2026.sty (100%) rename {skills => optional-skills}/research/research-paper-writing/templates/acl/README.md (100%) rename {skills => optional-skills}/research/research-paper-writing/templates/acl/acl.sty (100%) rename {skills => optional-skills}/research/research-paper-writing/templates/acl/acl_latex.tex (100%) rename {skills => optional-skills}/research/research-paper-writing/templates/acl/acl_lualatex.tex (100%) rename {skills => optional-skills}/research/research-paper-writing/templates/acl/acl_natbib.bst (100%) rename {skills => optional-skills}/research/research-paper-writing/templates/acl/anthology.bib.txt (100%) rename {skills => optional-skills}/research/research-paper-writing/templates/acl/custom.bib (100%) rename {skills => optional-skills}/research/research-paper-writing/templates/acl/formatting.md (100%) rename {skills => optional-skills}/research/research-paper-writing/templates/colm2025/README.md (100%) rename {skills => optional-skills}/research/research-paper-writing/templates/colm2025/colm2025_conference.bib (100%) rename {skills => optional-skills}/research/research-paper-writing/templates/colm2025/colm2025_conference.bst (100%) rename {skills => optional-skills}/research/research-paper-writing/templates/colm2025/colm2025_conference.pdf (100%) rename {skills => optional-skills}/research/research-paper-writing/templates/colm2025/colm2025_conference.sty (100%) rename {skills => optional-skills}/research/research-paper-writing/templates/colm2025/colm2025_conference.tex (100%) rename {skills => optional-skills}/research/research-paper-writing/templates/colm2025/fancyhdr.sty (100%) rename {skills => optional-skills}/research/research-paper-writing/templates/colm2025/math_commands.tex (100%) rename {skills => optional-skills}/research/research-paper-writing/templates/colm2025/natbib.sty (100%) rename {skills => optional-skills}/research/research-paper-writing/templates/iclr2026/fancyhdr.sty (100%) rename {skills => optional-skills}/research/research-paper-writing/templates/iclr2026/iclr2026_conference.bib (100%) rename {skills => optional-skills}/research/research-paper-writing/templates/iclr2026/iclr2026_conference.bst (100%) rename {skills => optional-skills}/research/research-paper-writing/templates/iclr2026/iclr2026_conference.pdf (100%) rename {skills => optional-skills}/research/research-paper-writing/templates/iclr2026/iclr2026_conference.sty (100%) rename {skills => optional-skills}/research/research-paper-writing/templates/iclr2026/iclr2026_conference.tex (100%) rename {skills => optional-skills}/research/research-paper-writing/templates/iclr2026/math_commands.tex (100%) rename {skills => optional-skills}/research/research-paper-writing/templates/iclr2026/natbib.sty (100%) rename {skills => optional-skills}/research/research-paper-writing/templates/icml2026/algorithm.sty (100%) rename {skills => optional-skills}/research/research-paper-writing/templates/icml2026/algorithmic.sty (100%) rename {skills => optional-skills}/research/research-paper-writing/templates/icml2026/example_paper.bib (100%) rename {skills => optional-skills}/research/research-paper-writing/templates/icml2026/example_paper.pdf (100%) rename {skills => optional-skills}/research/research-paper-writing/templates/icml2026/example_paper.tex (100%) rename {skills => optional-skills}/research/research-paper-writing/templates/icml2026/fancyhdr.sty (100%) rename {skills => optional-skills}/research/research-paper-writing/templates/icml2026/icml2026.bst (100%) rename {skills => optional-skills}/research/research-paper-writing/templates/icml2026/icml2026.sty (100%) rename {skills => optional-skills}/research/research-paper-writing/templates/icml2026/icml_numpapers.pdf (100%) rename {skills => optional-skills}/research/research-paper-writing/templates/neurips2025/Makefile (100%) rename {skills => optional-skills}/research/research-paper-writing/templates/neurips2025/extra_pkgs.tex (100%) rename {skills => optional-skills}/research/research-paper-writing/templates/neurips2025/main.tex (100%) rename {skills => optional-skills}/research/research-paper-writing/templates/neurips2025/neurips.sty (100%) rename {skills => optional-skills}/smart-home/DESCRIPTION.md (100%) rename {skills => optional-skills}/smart-home/openhue/SKILL.md (100%) delete mode 100644 skills/github/DESCRIPTION.md delete mode 100644 skills/mlops/DESCRIPTION.md delete mode 100644 skills/productivity/ocr-and-documents/DESCRIPTION.md rename skills/productivity/{nano-pdf/SKILL.md => pdf/references/nano-pdf-editing.md} (78%) rename skills/productivity/{ocr-and-documents/SKILL.md => pdf/references/ocr-extraction.md} (94%) rename skills/productivity/{ocr-and-documents => pdf}/scripts/extract_marker.py (72%) rename skills/productivity/{ocr-and-documents => pdf}/scripts/extract_pymupdf.py (65%) delete mode 100644 skills/productivity/session-librarian/SKILL.md rename skills/{github => software-development}/codebase-inspection/SKILL.md (98%) create mode 100644 skills/software-development/github/SKILL.md rename skills/{github/github-auth/SKILL.md => software-development/github/references/auth.md} (96%) rename skills/{github/github-pr-workflow => software-development/github}/references/ci-troubleshooting.md (100%) rename skills/{github/github-code-review/SKILL.md => software-development/github/references/code-review.md} (97%) rename skills/{github/github-pr-workflow => software-development/github}/references/conventional-commits.md (100%) rename skills/{github/github-repo-management => software-development/github}/references/github-api-cheatsheet.md (100%) rename skills/{github/github-issue-to-pr/SKILL.md => software-development/github/references/issue-to-pr.md} (93%) rename skills/{github/github-issues/SKILL.md => software-development/github/references/issues.md} (96%) rename skills/{github/github-pr-workflow/SKILL.md => software-development/github/references/pr-workflow.md} (96%) rename skills/{github/github-repo-management/SKILL.md => software-development/github/references/repo-management.md} (97%) rename skills/{github/github-code-review => software-development/github}/references/review-output-template.md (100%) rename skills/{github/github-auth => software-development/github}/scripts/gh-env.sh (100%) rename skills/{github/github-auth => software-development/github}/scripts/git-credential-token.py (100%) rename skills/{github/github-issues => software-development/github}/templates/bug-report.md (100%) rename skills/{github/github-issues => software-development/github}/templates/feature-request.md (100%) rename skills/{github/github-pr-workflow => software-development/github}/templates/pr-body-bugfix.md (100%) rename skills/{github/github-pr-workflow => software-development/github}/templates/pr-body-feature.md (100%) create mode 100644 skills/web/DESCRIPTION.md rename skills/{research => web}/blocked-page-recovery/SKILL.md (98%) rename skills/{research => web}/blocked-page-recovery/scripts/recover_page.py (100%) create mode 100644 tests/agent/test_skill_session_platform_gate.py rename tests/skills/{test_github_issue_to_pr_skill.py => test_github_skill.py} (58%) create mode 100644 website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-merge-reconciler.md create mode 100644 website/docs/user-guide/skills/bundled/devops/devops-sdlc-review.md create mode 100644 website/docs/user-guide/skills/bundled/software-development/software-development-codebase-inspection.md create mode 100644 website/docs/user-guide/skills/bundled/software-development/software-development-github.md create mode 100644 website/docs/user-guide/skills/bundled/web/web-blocked-page-recovery.md create mode 100644 website/docs/user-guide/skills/optional/creative/creative-ascii-art.md create mode 100644 website/docs/user-guide/skills/optional/creative/creative-comfyui.md create mode 100644 website/docs/user-guide/skills/optional/creative/creative-excalidraw.md create mode 100644 website/docs/user-guide/skills/optional/creative/creative-pretext.md create mode 100644 website/docs/user-guide/skills/optional/creative/creative-sketch.md create mode 100644 website/docs/user-guide/skills/optional/creative/creative-touchdesigner-mcp.md create mode 100644 website/docs/user-guide/skills/optional/mlops/mlops-evaluation-evaluating-llms-harness.md create mode 100644 website/docs/user-guide/skills/optional/mlops/mlops-evaluation-weights-and-biases.md create mode 100644 website/docs/user-guide/skills/optional/mlops/mlops-inference-llama-cpp.md create mode 100644 website/docs/user-guide/skills/optional/mlops/mlops-inference-serving-llms-vllm.md create mode 100644 website/docs/user-guide/skills/optional/mlops/mlops-models-huggingface-hub.md create mode 100644 website/docs/user-guide/skills/optional/research/research-blogwatcher.md create mode 100644 website/docs/user-guide/skills/optional/research/research-research-paper-writing.md create mode 100644 website/docs/user-guide/skills/optional/smart-home/smart-home-openhue.md create mode 100644 website/docs/user-guide/skills/optional/software-development/software-development-ast-grep.md create mode 100644 website/docs/user-guide/skills/optional/web-development/web-development-har-derived-api-client.md diff --git a/.gitignore b/.gitignore index bef8cb592e..7ad222cd54 100644 --- a/.gitignore +++ b/.gitignore @@ -212,3 +212,4 @@ native/fts5_cjk/*.so # interrupted; consumed by launch-time recovery. Never commit it (was tracked # by accident via 3a69e34702, removed in the #72002 salvage). .lazy-refresh-incomplete +.skills_prompt_snapshot.json diff --git a/SOUL.md b/SOUL.md new file mode 100644 index 0000000000..de81136d43 --- /dev/null +++ b/SOUL.md @@ -0,0 +1 @@ +You are Hermes Agent, built by Nous Research. Be direct: match the length of your reply to the weight of the ask — a one-line question gets a one-line answer, and finished work gets a short report of what changed, what's verified, and what's left, never a replay of the process. No filler ("Great question," "I'd be happy to"), no restating the request back, no re-summarizing what you already said, no narrating tool calls the user can see. Plain claims over adjectives; when unsure, say so plainly. Agree because it's right, not because the user said it. Depth is earned — give it when the user asks for detail, teaches, or the stakes demand it, not by default. \ No newline at end of file diff --git a/agent/prompt_builder.py b/agent/prompt_builder.py index cee20eba90..eb7175ec44 100644 --- a/agent/prompt_builder.py +++ b/agent/prompt_builder.py @@ -1702,8 +1702,23 @@ def _skill_should_show( conditions: dict, available_tools: "set[str] | None", available_toolsets: "set[str] | None", + session_platform: "str | None" = None, ) -> bool: """Return False if the skill's conditional activation rules exclude it.""" + # Gateway-channel gate: independent of tool filtering info, because a + # channel-specific skill (e.g. teams-meeting-pipeline) is noise on every + # other channel regardless of what tools are available. Fail-open when + # the session platform is unknown (offline builds, tests) — hiding a + # skill someone might need is worse than one spare index line. + wanted_platforms = [ + str(p).strip().lower() + for p in (conditions.get("session_platforms") or []) + if str(p).strip() + ] + if wanted_platforms and session_platform: + if session_platform.strip().lower() not in wanted_platforms: + return False + if available_tools is None and available_toolsets is None: return True # No filtering info — show everything (backward compat) @@ -1864,6 +1879,7 @@ def _build_skills_system_prompt_inner( entry.get("conditions") or {}, available_tools, available_toolsets, + _platform_hint or None, ): continue visible_entries.append(entry) @@ -1886,6 +1902,7 @@ def _build_skills_system_prompt_inner( extract_skill_conditions(frontmatter), available_tools, available_toolsets, + _platform_hint or None, ): continue visible_entries.append(entry) @@ -1917,6 +1934,7 @@ def _build_skills_system_prompt_inner( extract_skill_conditions(frontmatter), available_tools, available_toolsets, + _platform_hint or None, ): continue project_names.add(fm_name) @@ -2016,6 +2034,7 @@ def _build_skills_system_prompt_inner( extract_skill_conditions(frontmatter), available_tools, available_toolsets, + _platform_hint or None, ): continue seen_skill_names.add(frontmatter_name) diff --git a/agent/skill_utils.py b/agent/skill_utils.py index 0c893ab465..8b3a23b7c7 100644 --- a/agent/skill_utils.py +++ b/agent/skill_utils.py @@ -1018,6 +1018,13 @@ def extract_skill_conditions(frontmatter: Dict[str, Any]) -> Dict[str, List]: "requires_toolsets": hermes.get("requires_toolsets", []), "fallback_for_tools": hermes.get("fallback_for_tools", []), "requires_tools": hermes.get("requires_tools", []), + # Gateway-channel gate (maintainer-directed, skills-index slim): + # list of session platforms (e.g. ["msteams"]) the skill is FOR. + # Unlike top-level ``platforms:`` (host OS), this hides the skill + # from the index on every other channel — the teams-meeting + # pipeline has no business in a desktop or telegram session's + # index. Empty/absent = visible everywhere (backward compat). + "session_platforms": hermes.get("session_platforms", []), } diff --git a/skills/creative/ascii-art/SKILL.md b/optional-skills/creative/ascii-art/SKILL.md similarity index 100% rename from skills/creative/ascii-art/SKILL.md rename to optional-skills/creative/ascii-art/SKILL.md diff --git a/skills/creative/comfyui/SKILL.md b/optional-skills/creative/comfyui/SKILL.md similarity index 100% rename from skills/creative/comfyui/SKILL.md rename to optional-skills/creative/comfyui/SKILL.md diff --git a/skills/creative/comfyui/references/official-cli.md b/optional-skills/creative/comfyui/references/official-cli.md similarity index 100% rename from skills/creative/comfyui/references/official-cli.md rename to optional-skills/creative/comfyui/references/official-cli.md diff --git a/skills/creative/comfyui/references/rest-api.md b/optional-skills/creative/comfyui/references/rest-api.md similarity index 100% rename from skills/creative/comfyui/references/rest-api.md rename to optional-skills/creative/comfyui/references/rest-api.md diff --git a/skills/creative/comfyui/references/template-integrity.md b/optional-skills/creative/comfyui/references/template-integrity.md similarity index 100% rename from skills/creative/comfyui/references/template-integrity.md rename to optional-skills/creative/comfyui/references/template-integrity.md diff --git a/skills/creative/comfyui/references/workflow-format.md b/optional-skills/creative/comfyui/references/workflow-format.md similarity index 100% rename from skills/creative/comfyui/references/workflow-format.md rename to optional-skills/creative/comfyui/references/workflow-format.md diff --git a/skills/creative/comfyui/scripts/_common.py b/optional-skills/creative/comfyui/scripts/_common.py similarity index 100% rename from skills/creative/comfyui/scripts/_common.py rename to optional-skills/creative/comfyui/scripts/_common.py diff --git a/skills/creative/comfyui/scripts/auto_fix_deps.py b/optional-skills/creative/comfyui/scripts/auto_fix_deps.py similarity index 100% rename from skills/creative/comfyui/scripts/auto_fix_deps.py rename to optional-skills/creative/comfyui/scripts/auto_fix_deps.py diff --git a/skills/creative/comfyui/scripts/check_deps.py b/optional-skills/creative/comfyui/scripts/check_deps.py similarity index 100% rename from skills/creative/comfyui/scripts/check_deps.py rename to optional-skills/creative/comfyui/scripts/check_deps.py diff --git a/skills/creative/comfyui/scripts/comfyui_setup.sh b/optional-skills/creative/comfyui/scripts/comfyui_setup.sh similarity index 100% rename from skills/creative/comfyui/scripts/comfyui_setup.sh rename to optional-skills/creative/comfyui/scripts/comfyui_setup.sh diff --git a/skills/creative/comfyui/scripts/extract_schema.py b/optional-skills/creative/comfyui/scripts/extract_schema.py similarity index 100% rename from skills/creative/comfyui/scripts/extract_schema.py rename to optional-skills/creative/comfyui/scripts/extract_schema.py diff --git a/skills/creative/comfyui/scripts/fetch_logs.py b/optional-skills/creative/comfyui/scripts/fetch_logs.py similarity index 100% rename from skills/creative/comfyui/scripts/fetch_logs.py rename to optional-skills/creative/comfyui/scripts/fetch_logs.py diff --git a/skills/creative/comfyui/scripts/hardware_check.py b/optional-skills/creative/comfyui/scripts/hardware_check.py similarity index 100% rename from skills/creative/comfyui/scripts/hardware_check.py rename to optional-skills/creative/comfyui/scripts/hardware_check.py diff --git a/skills/creative/comfyui/scripts/health_check.py b/optional-skills/creative/comfyui/scripts/health_check.py similarity index 100% rename from skills/creative/comfyui/scripts/health_check.py rename to optional-skills/creative/comfyui/scripts/health_check.py diff --git a/skills/creative/comfyui/scripts/run_batch.py b/optional-skills/creative/comfyui/scripts/run_batch.py similarity index 100% rename from skills/creative/comfyui/scripts/run_batch.py rename to optional-skills/creative/comfyui/scripts/run_batch.py diff --git a/skills/creative/comfyui/scripts/run_workflow.py b/optional-skills/creative/comfyui/scripts/run_workflow.py similarity index 100% rename from skills/creative/comfyui/scripts/run_workflow.py rename to optional-skills/creative/comfyui/scripts/run_workflow.py diff --git a/skills/creative/comfyui/scripts/ws_monitor.py b/optional-skills/creative/comfyui/scripts/ws_monitor.py similarity index 100% rename from skills/creative/comfyui/scripts/ws_monitor.py rename to optional-skills/creative/comfyui/scripts/ws_monitor.py diff --git a/skills/creative/comfyui/tests/README.md b/optional-skills/creative/comfyui/tests/README.md similarity index 100% rename from skills/creative/comfyui/tests/README.md rename to optional-skills/creative/comfyui/tests/README.md diff --git a/skills/creative/comfyui/tests/conftest.py b/optional-skills/creative/comfyui/tests/conftest.py similarity index 100% rename from skills/creative/comfyui/tests/conftest.py rename to optional-skills/creative/comfyui/tests/conftest.py diff --git a/skills/creative/comfyui/tests/pytest.ini b/optional-skills/creative/comfyui/tests/pytest.ini similarity index 100% rename from skills/creative/comfyui/tests/pytest.ini rename to optional-skills/creative/comfyui/tests/pytest.ini diff --git a/skills/creative/comfyui/tests/test_check_deps.py b/optional-skills/creative/comfyui/tests/test_check_deps.py similarity index 100% rename from skills/creative/comfyui/tests/test_check_deps.py rename to optional-skills/creative/comfyui/tests/test_check_deps.py diff --git a/skills/creative/comfyui/tests/test_cloud_integration.py b/optional-skills/creative/comfyui/tests/test_cloud_integration.py similarity index 100% rename from skills/creative/comfyui/tests/test_cloud_integration.py rename to optional-skills/creative/comfyui/tests/test_cloud_integration.py diff --git a/skills/creative/comfyui/tests/test_common.py b/optional-skills/creative/comfyui/tests/test_common.py similarity index 100% rename from skills/creative/comfyui/tests/test_common.py rename to optional-skills/creative/comfyui/tests/test_common.py diff --git a/skills/creative/comfyui/tests/test_extract_schema.py b/optional-skills/creative/comfyui/tests/test_extract_schema.py similarity index 100% rename from skills/creative/comfyui/tests/test_extract_schema.py rename to optional-skills/creative/comfyui/tests/test_extract_schema.py diff --git a/skills/creative/comfyui/tests/test_run_workflow.py b/optional-skills/creative/comfyui/tests/test_run_workflow.py similarity index 100% rename from skills/creative/comfyui/tests/test_run_workflow.py rename to optional-skills/creative/comfyui/tests/test_run_workflow.py diff --git a/skills/creative/comfyui/workflows/README.md b/optional-skills/creative/comfyui/workflows/README.md similarity index 100% rename from skills/creative/comfyui/workflows/README.md rename to optional-skills/creative/comfyui/workflows/README.md diff --git a/skills/creative/comfyui/workflows/animatediff_video.json b/optional-skills/creative/comfyui/workflows/animatediff_video.json similarity index 100% rename from skills/creative/comfyui/workflows/animatediff_video.json rename to optional-skills/creative/comfyui/workflows/animatediff_video.json diff --git a/skills/creative/comfyui/workflows/flux_dev_txt2img.json b/optional-skills/creative/comfyui/workflows/flux_dev_txt2img.json similarity index 100% rename from skills/creative/comfyui/workflows/flux_dev_txt2img.json rename to optional-skills/creative/comfyui/workflows/flux_dev_txt2img.json diff --git a/skills/creative/comfyui/workflows/sd15_txt2img.json b/optional-skills/creative/comfyui/workflows/sd15_txt2img.json similarity index 100% rename from skills/creative/comfyui/workflows/sd15_txt2img.json rename to optional-skills/creative/comfyui/workflows/sd15_txt2img.json diff --git a/skills/creative/comfyui/workflows/sdxl_img2img.json b/optional-skills/creative/comfyui/workflows/sdxl_img2img.json similarity index 100% rename from skills/creative/comfyui/workflows/sdxl_img2img.json rename to optional-skills/creative/comfyui/workflows/sdxl_img2img.json diff --git a/skills/creative/comfyui/workflows/sdxl_inpaint.json b/optional-skills/creative/comfyui/workflows/sdxl_inpaint.json similarity index 100% rename from skills/creative/comfyui/workflows/sdxl_inpaint.json rename to optional-skills/creative/comfyui/workflows/sdxl_inpaint.json diff --git a/skills/creative/comfyui/workflows/sdxl_txt2img.json b/optional-skills/creative/comfyui/workflows/sdxl_txt2img.json similarity index 100% rename from skills/creative/comfyui/workflows/sdxl_txt2img.json rename to optional-skills/creative/comfyui/workflows/sdxl_txt2img.json diff --git a/skills/creative/comfyui/workflows/upscale_4x.json b/optional-skills/creative/comfyui/workflows/upscale_4x.json similarity index 100% rename from skills/creative/comfyui/workflows/upscale_4x.json rename to optional-skills/creative/comfyui/workflows/upscale_4x.json diff --git a/skills/creative/comfyui/workflows/wan_video_t2v.json b/optional-skills/creative/comfyui/workflows/wan_video_t2v.json similarity index 100% rename from skills/creative/comfyui/workflows/wan_video_t2v.json rename to optional-skills/creative/comfyui/workflows/wan_video_t2v.json diff --git a/skills/creative/excalidraw/SKILL.md b/optional-skills/creative/excalidraw/SKILL.md similarity index 100% rename from skills/creative/excalidraw/SKILL.md rename to optional-skills/creative/excalidraw/SKILL.md diff --git a/skills/creative/excalidraw/references/colors.md b/optional-skills/creative/excalidraw/references/colors.md similarity index 100% rename from skills/creative/excalidraw/references/colors.md rename to optional-skills/creative/excalidraw/references/colors.md diff --git a/skills/creative/excalidraw/references/dark-mode.md b/optional-skills/creative/excalidraw/references/dark-mode.md similarity index 100% rename from skills/creative/excalidraw/references/dark-mode.md rename to optional-skills/creative/excalidraw/references/dark-mode.md diff --git a/skills/creative/excalidraw/references/examples.md b/optional-skills/creative/excalidraw/references/examples.md similarity index 100% rename from skills/creative/excalidraw/references/examples.md rename to optional-skills/creative/excalidraw/references/examples.md diff --git a/skills/creative/excalidraw/scripts/upload.py b/optional-skills/creative/excalidraw/scripts/upload.py similarity index 100% rename from skills/creative/excalidraw/scripts/upload.py rename to optional-skills/creative/excalidraw/scripts/upload.py diff --git a/skills/creative/pretext/SKILL.md b/optional-skills/creative/pretext/SKILL.md similarity index 100% rename from skills/creative/pretext/SKILL.md rename to optional-skills/creative/pretext/SKILL.md diff --git a/skills/creative/pretext/references/patterns.md b/optional-skills/creative/pretext/references/patterns.md similarity index 100% rename from skills/creative/pretext/references/patterns.md rename to optional-skills/creative/pretext/references/patterns.md diff --git a/skills/creative/pretext/templates/donut-orbit.html b/optional-skills/creative/pretext/templates/donut-orbit.html similarity index 100% rename from skills/creative/pretext/templates/donut-orbit.html rename to optional-skills/creative/pretext/templates/donut-orbit.html diff --git a/skills/creative/pretext/templates/hello-orb-flow.html b/optional-skills/creative/pretext/templates/hello-orb-flow.html similarity index 100% rename from skills/creative/pretext/templates/hello-orb-flow.html rename to optional-skills/creative/pretext/templates/hello-orb-flow.html diff --git a/skills/creative/sketch/SKILL.md b/optional-skills/creative/sketch/SKILL.md similarity index 100% rename from skills/creative/sketch/SKILL.md rename to optional-skills/creative/sketch/SKILL.md diff --git a/skills/creative/touchdesigner-mcp/SKILL.md b/optional-skills/creative/touchdesigner-mcp/SKILL.md similarity index 100% rename from skills/creative/touchdesigner-mcp/SKILL.md rename to optional-skills/creative/touchdesigner-mcp/SKILL.md diff --git a/skills/creative/touchdesigner-mcp/references/3d-scene.md b/optional-skills/creative/touchdesigner-mcp/references/3d-scene.md similarity index 100% rename from skills/creative/touchdesigner-mcp/references/3d-scene.md rename to optional-skills/creative/touchdesigner-mcp/references/3d-scene.md diff --git a/skills/creative/touchdesigner-mcp/references/animation.md b/optional-skills/creative/touchdesigner-mcp/references/animation.md similarity index 100% rename from skills/creative/touchdesigner-mcp/references/animation.md rename to optional-skills/creative/touchdesigner-mcp/references/animation.md diff --git a/skills/creative/touchdesigner-mcp/references/audio-reactive.md b/optional-skills/creative/touchdesigner-mcp/references/audio-reactive.md similarity index 100% rename from skills/creative/touchdesigner-mcp/references/audio-reactive.md rename to optional-skills/creative/touchdesigner-mcp/references/audio-reactive.md diff --git a/skills/creative/touchdesigner-mcp/references/dat-scripting.md b/optional-skills/creative/touchdesigner-mcp/references/dat-scripting.md similarity index 100% rename from skills/creative/touchdesigner-mcp/references/dat-scripting.md rename to optional-skills/creative/touchdesigner-mcp/references/dat-scripting.md diff --git a/skills/creative/touchdesigner-mcp/references/external-data.md b/optional-skills/creative/touchdesigner-mcp/references/external-data.md similarity index 100% rename from skills/creative/touchdesigner-mcp/references/external-data.md rename to optional-skills/creative/touchdesigner-mcp/references/external-data.md diff --git a/skills/creative/touchdesigner-mcp/references/geometry-comp.md b/optional-skills/creative/touchdesigner-mcp/references/geometry-comp.md similarity index 100% rename from skills/creative/touchdesigner-mcp/references/geometry-comp.md rename to optional-skills/creative/touchdesigner-mcp/references/geometry-comp.md diff --git a/skills/creative/touchdesigner-mcp/references/glsl.md b/optional-skills/creative/touchdesigner-mcp/references/glsl.md similarity index 100% rename from skills/creative/touchdesigner-mcp/references/glsl.md rename to optional-skills/creative/touchdesigner-mcp/references/glsl.md diff --git a/skills/creative/touchdesigner-mcp/references/layout-compositor.md b/optional-skills/creative/touchdesigner-mcp/references/layout-compositor.md similarity index 100% rename from skills/creative/touchdesigner-mcp/references/layout-compositor.md rename to optional-skills/creative/touchdesigner-mcp/references/layout-compositor.md diff --git a/skills/creative/touchdesigner-mcp/references/mcp-tools.md b/optional-skills/creative/touchdesigner-mcp/references/mcp-tools.md similarity index 100% rename from skills/creative/touchdesigner-mcp/references/mcp-tools.md rename to optional-skills/creative/touchdesigner-mcp/references/mcp-tools.md diff --git a/skills/creative/touchdesigner-mcp/references/midi-osc.md b/optional-skills/creative/touchdesigner-mcp/references/midi-osc.md similarity index 100% rename from skills/creative/touchdesigner-mcp/references/midi-osc.md rename to optional-skills/creative/touchdesigner-mcp/references/midi-osc.md diff --git a/skills/creative/touchdesigner-mcp/references/network-patterns.md b/optional-skills/creative/touchdesigner-mcp/references/network-patterns.md similarity index 100% rename from skills/creative/touchdesigner-mcp/references/network-patterns.md rename to optional-skills/creative/touchdesigner-mcp/references/network-patterns.md diff --git a/skills/creative/touchdesigner-mcp/references/operator-tips.md b/optional-skills/creative/touchdesigner-mcp/references/operator-tips.md similarity index 100% rename from skills/creative/touchdesigner-mcp/references/operator-tips.md rename to optional-skills/creative/touchdesigner-mcp/references/operator-tips.md diff --git a/skills/creative/touchdesigner-mcp/references/operators.md b/optional-skills/creative/touchdesigner-mcp/references/operators.md similarity index 100% rename from skills/creative/touchdesigner-mcp/references/operators.md rename to optional-skills/creative/touchdesigner-mcp/references/operators.md diff --git a/skills/creative/touchdesigner-mcp/references/panel-ui.md b/optional-skills/creative/touchdesigner-mcp/references/panel-ui.md similarity index 100% rename from skills/creative/touchdesigner-mcp/references/panel-ui.md rename to optional-skills/creative/touchdesigner-mcp/references/panel-ui.md diff --git a/skills/creative/touchdesigner-mcp/references/particles.md b/optional-skills/creative/touchdesigner-mcp/references/particles.md similarity index 100% rename from skills/creative/touchdesigner-mcp/references/particles.md rename to optional-skills/creative/touchdesigner-mcp/references/particles.md diff --git a/skills/creative/touchdesigner-mcp/references/pitfalls.md b/optional-skills/creative/touchdesigner-mcp/references/pitfalls.md similarity index 100% rename from skills/creative/touchdesigner-mcp/references/pitfalls.md rename to optional-skills/creative/touchdesigner-mcp/references/pitfalls.md diff --git a/skills/creative/touchdesigner-mcp/references/postfx.md b/optional-skills/creative/touchdesigner-mcp/references/postfx.md similarity index 100% rename from skills/creative/touchdesigner-mcp/references/postfx.md rename to optional-skills/creative/touchdesigner-mcp/references/postfx.md diff --git a/skills/creative/touchdesigner-mcp/references/projection-mapping.md b/optional-skills/creative/touchdesigner-mcp/references/projection-mapping.md similarity index 100% rename from skills/creative/touchdesigner-mcp/references/projection-mapping.md rename to optional-skills/creative/touchdesigner-mcp/references/projection-mapping.md diff --git a/skills/creative/touchdesigner-mcp/references/python-api.md b/optional-skills/creative/touchdesigner-mcp/references/python-api.md similarity index 100% rename from skills/creative/touchdesigner-mcp/references/python-api.md rename to optional-skills/creative/touchdesigner-mcp/references/python-api.md diff --git a/skills/creative/touchdesigner-mcp/references/replicator.md b/optional-skills/creative/touchdesigner-mcp/references/replicator.md similarity index 100% rename from skills/creative/touchdesigner-mcp/references/replicator.md rename to optional-skills/creative/touchdesigner-mcp/references/replicator.md diff --git a/skills/creative/touchdesigner-mcp/references/troubleshooting.md b/optional-skills/creative/touchdesigner-mcp/references/troubleshooting.md similarity index 100% rename from skills/creative/touchdesigner-mcp/references/troubleshooting.md rename to optional-skills/creative/touchdesigner-mcp/references/troubleshooting.md diff --git a/skills/creative/touchdesigner-mcp/scripts/setup.sh b/optional-skills/creative/touchdesigner-mcp/scripts/setup.sh similarity index 100% rename from skills/creative/touchdesigner-mcp/scripts/setup.sh rename to optional-skills/creative/touchdesigner-mcp/scripts/setup.sh diff --git a/skills/mlops/evaluation/DESCRIPTION.md b/optional-skills/mlops/evaluation/DESCRIPTION.md similarity index 100% rename from skills/mlops/evaluation/DESCRIPTION.md rename to optional-skills/mlops/evaluation/DESCRIPTION.md diff --git a/skills/mlops/evaluation/evaluating-llms-harness/SKILL.md b/optional-skills/mlops/evaluation/evaluating-llms-harness/SKILL.md similarity index 100% rename from skills/mlops/evaluation/evaluating-llms-harness/SKILL.md rename to optional-skills/mlops/evaluation/evaluating-llms-harness/SKILL.md diff --git a/skills/mlops/evaluation/evaluating-llms-harness/references/api-evaluation.md b/optional-skills/mlops/evaluation/evaluating-llms-harness/references/api-evaluation.md similarity index 100% rename from skills/mlops/evaluation/evaluating-llms-harness/references/api-evaluation.md rename to optional-skills/mlops/evaluation/evaluating-llms-harness/references/api-evaluation.md diff --git a/skills/mlops/evaluation/evaluating-llms-harness/references/benchmark-guide.md b/optional-skills/mlops/evaluation/evaluating-llms-harness/references/benchmark-guide.md similarity index 100% rename from skills/mlops/evaluation/evaluating-llms-harness/references/benchmark-guide.md rename to optional-skills/mlops/evaluation/evaluating-llms-harness/references/benchmark-guide.md diff --git a/skills/mlops/evaluation/evaluating-llms-harness/references/custom-tasks.md b/optional-skills/mlops/evaluation/evaluating-llms-harness/references/custom-tasks.md similarity index 100% rename from skills/mlops/evaluation/evaluating-llms-harness/references/custom-tasks.md rename to optional-skills/mlops/evaluation/evaluating-llms-harness/references/custom-tasks.md diff --git a/skills/mlops/evaluation/evaluating-llms-harness/references/distributed-eval.md b/optional-skills/mlops/evaluation/evaluating-llms-harness/references/distributed-eval.md similarity index 100% rename from skills/mlops/evaluation/evaluating-llms-harness/references/distributed-eval.md rename to optional-skills/mlops/evaluation/evaluating-llms-harness/references/distributed-eval.md diff --git a/skills/mlops/evaluation/weights-and-biases/SKILL.md b/optional-skills/mlops/evaluation/weights-and-biases/SKILL.md similarity index 100% rename from skills/mlops/evaluation/weights-and-biases/SKILL.md rename to optional-skills/mlops/evaluation/weights-and-biases/SKILL.md diff --git a/skills/mlops/evaluation/weights-and-biases/references/artifacts.md b/optional-skills/mlops/evaluation/weights-and-biases/references/artifacts.md similarity index 100% rename from skills/mlops/evaluation/weights-and-biases/references/artifacts.md rename to optional-skills/mlops/evaluation/weights-and-biases/references/artifacts.md diff --git a/skills/mlops/evaluation/weights-and-biases/references/integrations.md b/optional-skills/mlops/evaluation/weights-and-biases/references/integrations.md similarity index 100% rename from skills/mlops/evaluation/weights-and-biases/references/integrations.md rename to optional-skills/mlops/evaluation/weights-and-biases/references/integrations.md diff --git a/skills/mlops/evaluation/weights-and-biases/references/sweeps.md b/optional-skills/mlops/evaluation/weights-and-biases/references/sweeps.md similarity index 100% rename from skills/mlops/evaluation/weights-and-biases/references/sweeps.md rename to optional-skills/mlops/evaluation/weights-and-biases/references/sweeps.md diff --git a/skills/mlops/inference/DESCRIPTION.md b/optional-skills/mlops/inference/DESCRIPTION.md similarity index 100% rename from skills/mlops/inference/DESCRIPTION.md rename to optional-skills/mlops/inference/DESCRIPTION.md diff --git a/skills/mlops/inference/llama-cpp/SKILL.md b/optional-skills/mlops/inference/llama-cpp/SKILL.md similarity index 100% rename from skills/mlops/inference/llama-cpp/SKILL.md rename to optional-skills/mlops/inference/llama-cpp/SKILL.md diff --git a/skills/mlops/inference/llama-cpp/references/advanced-usage.md b/optional-skills/mlops/inference/llama-cpp/references/advanced-usage.md similarity index 100% rename from skills/mlops/inference/llama-cpp/references/advanced-usage.md rename to optional-skills/mlops/inference/llama-cpp/references/advanced-usage.md diff --git a/skills/mlops/inference/llama-cpp/references/hub-discovery.md b/optional-skills/mlops/inference/llama-cpp/references/hub-discovery.md similarity index 100% rename from skills/mlops/inference/llama-cpp/references/hub-discovery.md rename to optional-skills/mlops/inference/llama-cpp/references/hub-discovery.md diff --git a/skills/mlops/inference/llama-cpp/references/optimization.md b/optional-skills/mlops/inference/llama-cpp/references/optimization.md similarity index 100% rename from skills/mlops/inference/llama-cpp/references/optimization.md rename to optional-skills/mlops/inference/llama-cpp/references/optimization.md diff --git a/skills/mlops/inference/llama-cpp/references/quantization.md b/optional-skills/mlops/inference/llama-cpp/references/quantization.md similarity index 100% rename from skills/mlops/inference/llama-cpp/references/quantization.md rename to optional-skills/mlops/inference/llama-cpp/references/quantization.md diff --git a/skills/mlops/inference/llama-cpp/references/server.md b/optional-skills/mlops/inference/llama-cpp/references/server.md similarity index 100% rename from skills/mlops/inference/llama-cpp/references/server.md rename to optional-skills/mlops/inference/llama-cpp/references/server.md diff --git a/skills/mlops/inference/llama-cpp/references/troubleshooting.md b/optional-skills/mlops/inference/llama-cpp/references/troubleshooting.md similarity index 100% rename from skills/mlops/inference/llama-cpp/references/troubleshooting.md rename to optional-skills/mlops/inference/llama-cpp/references/troubleshooting.md diff --git a/skills/mlops/inference/serving-llms-vllm/SKILL.md b/optional-skills/mlops/inference/serving-llms-vllm/SKILL.md similarity index 100% rename from skills/mlops/inference/serving-llms-vllm/SKILL.md rename to optional-skills/mlops/inference/serving-llms-vllm/SKILL.md diff --git a/skills/mlops/inference/serving-llms-vllm/references/optimization.md b/optional-skills/mlops/inference/serving-llms-vllm/references/optimization.md similarity index 100% rename from skills/mlops/inference/serving-llms-vllm/references/optimization.md rename to optional-skills/mlops/inference/serving-llms-vllm/references/optimization.md diff --git a/skills/mlops/inference/serving-llms-vllm/references/quantization.md b/optional-skills/mlops/inference/serving-llms-vllm/references/quantization.md similarity index 100% rename from skills/mlops/inference/serving-llms-vllm/references/quantization.md rename to optional-skills/mlops/inference/serving-llms-vllm/references/quantization.md diff --git a/skills/mlops/inference/serving-llms-vllm/references/server-deployment.md b/optional-skills/mlops/inference/serving-llms-vllm/references/server-deployment.md similarity index 100% rename from skills/mlops/inference/serving-llms-vllm/references/server-deployment.md rename to optional-skills/mlops/inference/serving-llms-vllm/references/server-deployment.md diff --git a/skills/mlops/inference/serving-llms-vllm/references/troubleshooting.md b/optional-skills/mlops/inference/serving-llms-vllm/references/troubleshooting.md similarity index 100% rename from skills/mlops/inference/serving-llms-vllm/references/troubleshooting.md rename to optional-skills/mlops/inference/serving-llms-vllm/references/troubleshooting.md diff --git a/skills/mlops/models/DESCRIPTION.md b/optional-skills/mlops/models/DESCRIPTION.md similarity index 100% rename from skills/mlops/models/DESCRIPTION.md rename to optional-skills/mlops/models/DESCRIPTION.md diff --git a/skills/mlops/huggingface-hub/SKILL.md b/optional-skills/mlops/models/huggingface-hub/SKILL.md similarity index 100% rename from skills/mlops/huggingface-hub/SKILL.md rename to optional-skills/mlops/models/huggingface-hub/SKILL.md diff --git a/skills/research/blogwatcher/SKILL.md b/optional-skills/research/blogwatcher/SKILL.md similarity index 82% rename from skills/research/blogwatcher/SKILL.md rename to optional-skills/research/blogwatcher/SKILL.md index a1d52441e1..cf4b58472a 100644 --- a/skills/research/blogwatcher/SKILL.md +++ b/optional-skills/research/blogwatcher/SKILL.md @@ -17,6 +17,15 @@ prerequisites: Track blog and RSS/Atom feed updates with the `blogwatcher-cli` tool. Supports automatic feed discovery, HTML scraping fallback, OPML import, and read/unread article management. +## Working with Hermes tools (read this first) + +`blogwatcher-cli` is the feed database; Hermes tools do the automation around it: + +- **Recurring watch — use the cronjob tool's `monitor` field, not a bare schedule.** `monitor` runs a script each tick and only wakes the agent when output changes: set it to a script that runs `blogwatcher-cli scan >/dev/null 2>&1 && blogwatcher-cli articles` (deterministic output; new articles = changed output = agent wakes with the diff injected). Unchanged ticks cost zero LLM calls. Set `deliver` to route digests to a chat/channel; add `continuity: true` so consecutive digests can dedupe. +- **Reading an article the user asks about**: `web_extract([url])` on the article URL from `blogwatcher-cli articles` — do not re-scrape by hand. +- **One-off "watch this page for changes" without feed semantics**: skip this skill; the cronjob tool's `monitor` field accepts an http(s) URL directly. +- **Company/competitor tracking with analysis and citations**: prefer the `competitor-news-monitor` skill; blogwatcher is the lighter raw-feed layer it can sit on. + ## Installation Pick one method: diff --git a/skills/research/research-paper-writing/SKILL.md b/optional-skills/research/research-paper-writing/SKILL.md similarity index 100% rename from skills/research/research-paper-writing/SKILL.md rename to optional-skills/research/research-paper-writing/SKILL.md diff --git a/skills/research/research-paper-writing/references/autoreason-methodology.md b/optional-skills/research/research-paper-writing/references/autoreason-methodology.md similarity index 100% rename from skills/research/research-paper-writing/references/autoreason-methodology.md rename to optional-skills/research/research-paper-writing/references/autoreason-methodology.md diff --git a/skills/research/research-paper-writing/references/checklists.md b/optional-skills/research/research-paper-writing/references/checklists.md similarity index 100% rename from skills/research/research-paper-writing/references/checklists.md rename to optional-skills/research/research-paper-writing/references/checklists.md diff --git a/skills/research/research-paper-writing/references/citation-workflow.md b/optional-skills/research/research-paper-writing/references/citation-workflow.md similarity index 100% rename from skills/research/research-paper-writing/references/citation-workflow.md rename to optional-skills/research/research-paper-writing/references/citation-workflow.md diff --git a/skills/research/research-paper-writing/references/experiment-patterns.md b/optional-skills/research/research-paper-writing/references/experiment-patterns.md similarity index 100% rename from skills/research/research-paper-writing/references/experiment-patterns.md rename to optional-skills/research/research-paper-writing/references/experiment-patterns.md diff --git a/skills/research/research-paper-writing/references/human-evaluation.md b/optional-skills/research/research-paper-writing/references/human-evaluation.md similarity index 100% rename from skills/research/research-paper-writing/references/human-evaluation.md rename to optional-skills/research/research-paper-writing/references/human-evaluation.md diff --git a/skills/research/research-paper-writing/references/paper-types.md b/optional-skills/research/research-paper-writing/references/paper-types.md similarity index 100% rename from skills/research/research-paper-writing/references/paper-types.md rename to optional-skills/research/research-paper-writing/references/paper-types.md diff --git a/skills/research/research-paper-writing/references/phase5-paper-drafting.md b/optional-skills/research/research-paper-writing/references/phase5-paper-drafting.md similarity index 100% rename from skills/research/research-paper-writing/references/phase5-paper-drafting.md rename to optional-skills/research/research-paper-writing/references/phase5-paper-drafting.md diff --git a/skills/research/research-paper-writing/references/reviewer-guidelines.md b/optional-skills/research/research-paper-writing/references/reviewer-guidelines.md similarity index 100% rename from skills/research/research-paper-writing/references/reviewer-guidelines.md rename to optional-skills/research/research-paper-writing/references/reviewer-guidelines.md diff --git a/skills/research/research-paper-writing/references/sources.md b/optional-skills/research/research-paper-writing/references/sources.md similarity index 100% rename from skills/research/research-paper-writing/references/sources.md rename to optional-skills/research/research-paper-writing/references/sources.md diff --git a/skills/research/research-paper-writing/references/writing-guide.md b/optional-skills/research/research-paper-writing/references/writing-guide.md similarity index 100% rename from skills/research/research-paper-writing/references/writing-guide.md rename to optional-skills/research/research-paper-writing/references/writing-guide.md diff --git a/skills/research/research-paper-writing/templates/README.md b/optional-skills/research/research-paper-writing/templates/README.md similarity index 100% rename from skills/research/research-paper-writing/templates/README.md rename to optional-skills/research/research-paper-writing/templates/README.md diff --git a/skills/research/research-paper-writing/templates/aaai2026/README.md b/optional-skills/research/research-paper-writing/templates/aaai2026/README.md similarity index 100% rename from skills/research/research-paper-writing/templates/aaai2026/README.md rename to optional-skills/research/research-paper-writing/templates/aaai2026/README.md diff --git a/skills/research/research-paper-writing/templates/aaai2026/aaai2026-unified-supp.tex b/optional-skills/research/research-paper-writing/templates/aaai2026/aaai2026-unified-supp.tex similarity index 100% rename from skills/research/research-paper-writing/templates/aaai2026/aaai2026-unified-supp.tex rename to optional-skills/research/research-paper-writing/templates/aaai2026/aaai2026-unified-supp.tex diff --git a/skills/research/research-paper-writing/templates/aaai2026/aaai2026-unified-template.tex b/optional-skills/research/research-paper-writing/templates/aaai2026/aaai2026-unified-template.tex similarity index 100% rename from skills/research/research-paper-writing/templates/aaai2026/aaai2026-unified-template.tex rename to optional-skills/research/research-paper-writing/templates/aaai2026/aaai2026-unified-template.tex diff --git a/skills/research/research-paper-writing/templates/aaai2026/aaai2026.bib b/optional-skills/research/research-paper-writing/templates/aaai2026/aaai2026.bib similarity index 100% rename from skills/research/research-paper-writing/templates/aaai2026/aaai2026.bib rename to optional-skills/research/research-paper-writing/templates/aaai2026/aaai2026.bib diff --git a/skills/research/research-paper-writing/templates/aaai2026/aaai2026.bst b/optional-skills/research/research-paper-writing/templates/aaai2026/aaai2026.bst similarity index 100% rename from skills/research/research-paper-writing/templates/aaai2026/aaai2026.bst rename to optional-skills/research/research-paper-writing/templates/aaai2026/aaai2026.bst diff --git a/skills/research/research-paper-writing/templates/aaai2026/aaai2026.sty b/optional-skills/research/research-paper-writing/templates/aaai2026/aaai2026.sty similarity index 100% rename from skills/research/research-paper-writing/templates/aaai2026/aaai2026.sty rename to optional-skills/research/research-paper-writing/templates/aaai2026/aaai2026.sty diff --git a/skills/research/research-paper-writing/templates/acl/README.md b/optional-skills/research/research-paper-writing/templates/acl/README.md similarity index 100% rename from skills/research/research-paper-writing/templates/acl/README.md rename to optional-skills/research/research-paper-writing/templates/acl/README.md diff --git a/skills/research/research-paper-writing/templates/acl/acl.sty b/optional-skills/research/research-paper-writing/templates/acl/acl.sty similarity index 100% rename from skills/research/research-paper-writing/templates/acl/acl.sty rename to optional-skills/research/research-paper-writing/templates/acl/acl.sty diff --git a/skills/research/research-paper-writing/templates/acl/acl_latex.tex b/optional-skills/research/research-paper-writing/templates/acl/acl_latex.tex similarity index 100% rename from skills/research/research-paper-writing/templates/acl/acl_latex.tex rename to optional-skills/research/research-paper-writing/templates/acl/acl_latex.tex diff --git a/skills/research/research-paper-writing/templates/acl/acl_lualatex.tex b/optional-skills/research/research-paper-writing/templates/acl/acl_lualatex.tex similarity index 100% rename from skills/research/research-paper-writing/templates/acl/acl_lualatex.tex rename to optional-skills/research/research-paper-writing/templates/acl/acl_lualatex.tex diff --git a/skills/research/research-paper-writing/templates/acl/acl_natbib.bst b/optional-skills/research/research-paper-writing/templates/acl/acl_natbib.bst similarity index 100% rename from skills/research/research-paper-writing/templates/acl/acl_natbib.bst rename to optional-skills/research/research-paper-writing/templates/acl/acl_natbib.bst diff --git a/skills/research/research-paper-writing/templates/acl/anthology.bib.txt b/optional-skills/research/research-paper-writing/templates/acl/anthology.bib.txt similarity index 100% rename from skills/research/research-paper-writing/templates/acl/anthology.bib.txt rename to optional-skills/research/research-paper-writing/templates/acl/anthology.bib.txt diff --git a/skills/research/research-paper-writing/templates/acl/custom.bib b/optional-skills/research/research-paper-writing/templates/acl/custom.bib similarity index 100% rename from skills/research/research-paper-writing/templates/acl/custom.bib rename to optional-skills/research/research-paper-writing/templates/acl/custom.bib diff --git a/skills/research/research-paper-writing/templates/acl/formatting.md b/optional-skills/research/research-paper-writing/templates/acl/formatting.md similarity index 100% rename from skills/research/research-paper-writing/templates/acl/formatting.md rename to optional-skills/research/research-paper-writing/templates/acl/formatting.md diff --git a/skills/research/research-paper-writing/templates/colm2025/README.md b/optional-skills/research/research-paper-writing/templates/colm2025/README.md similarity index 100% rename from skills/research/research-paper-writing/templates/colm2025/README.md rename to optional-skills/research/research-paper-writing/templates/colm2025/README.md diff --git a/skills/research/research-paper-writing/templates/colm2025/colm2025_conference.bib b/optional-skills/research/research-paper-writing/templates/colm2025/colm2025_conference.bib similarity index 100% rename from skills/research/research-paper-writing/templates/colm2025/colm2025_conference.bib rename to optional-skills/research/research-paper-writing/templates/colm2025/colm2025_conference.bib diff --git a/skills/research/research-paper-writing/templates/colm2025/colm2025_conference.bst b/optional-skills/research/research-paper-writing/templates/colm2025/colm2025_conference.bst similarity index 100% rename from skills/research/research-paper-writing/templates/colm2025/colm2025_conference.bst rename to optional-skills/research/research-paper-writing/templates/colm2025/colm2025_conference.bst diff --git a/skills/research/research-paper-writing/templates/colm2025/colm2025_conference.pdf b/optional-skills/research/research-paper-writing/templates/colm2025/colm2025_conference.pdf similarity index 100% rename from skills/research/research-paper-writing/templates/colm2025/colm2025_conference.pdf rename to optional-skills/research/research-paper-writing/templates/colm2025/colm2025_conference.pdf diff --git a/skills/research/research-paper-writing/templates/colm2025/colm2025_conference.sty b/optional-skills/research/research-paper-writing/templates/colm2025/colm2025_conference.sty similarity index 100% rename from skills/research/research-paper-writing/templates/colm2025/colm2025_conference.sty rename to optional-skills/research/research-paper-writing/templates/colm2025/colm2025_conference.sty diff --git a/skills/research/research-paper-writing/templates/colm2025/colm2025_conference.tex b/optional-skills/research/research-paper-writing/templates/colm2025/colm2025_conference.tex similarity index 100% rename from skills/research/research-paper-writing/templates/colm2025/colm2025_conference.tex rename to optional-skills/research/research-paper-writing/templates/colm2025/colm2025_conference.tex diff --git a/skills/research/research-paper-writing/templates/colm2025/fancyhdr.sty b/optional-skills/research/research-paper-writing/templates/colm2025/fancyhdr.sty similarity index 100% rename from skills/research/research-paper-writing/templates/colm2025/fancyhdr.sty rename to optional-skills/research/research-paper-writing/templates/colm2025/fancyhdr.sty diff --git a/skills/research/research-paper-writing/templates/colm2025/math_commands.tex b/optional-skills/research/research-paper-writing/templates/colm2025/math_commands.tex similarity index 100% rename from skills/research/research-paper-writing/templates/colm2025/math_commands.tex rename to optional-skills/research/research-paper-writing/templates/colm2025/math_commands.tex diff --git a/skills/research/research-paper-writing/templates/colm2025/natbib.sty b/optional-skills/research/research-paper-writing/templates/colm2025/natbib.sty similarity index 100% rename from skills/research/research-paper-writing/templates/colm2025/natbib.sty rename to optional-skills/research/research-paper-writing/templates/colm2025/natbib.sty diff --git a/skills/research/research-paper-writing/templates/iclr2026/fancyhdr.sty b/optional-skills/research/research-paper-writing/templates/iclr2026/fancyhdr.sty similarity index 100% rename from skills/research/research-paper-writing/templates/iclr2026/fancyhdr.sty rename to optional-skills/research/research-paper-writing/templates/iclr2026/fancyhdr.sty diff --git a/skills/research/research-paper-writing/templates/iclr2026/iclr2026_conference.bib b/optional-skills/research/research-paper-writing/templates/iclr2026/iclr2026_conference.bib similarity index 100% rename from skills/research/research-paper-writing/templates/iclr2026/iclr2026_conference.bib rename to optional-skills/research/research-paper-writing/templates/iclr2026/iclr2026_conference.bib diff --git a/skills/research/research-paper-writing/templates/iclr2026/iclr2026_conference.bst b/optional-skills/research/research-paper-writing/templates/iclr2026/iclr2026_conference.bst similarity index 100% rename from skills/research/research-paper-writing/templates/iclr2026/iclr2026_conference.bst rename to optional-skills/research/research-paper-writing/templates/iclr2026/iclr2026_conference.bst diff --git a/skills/research/research-paper-writing/templates/iclr2026/iclr2026_conference.pdf b/optional-skills/research/research-paper-writing/templates/iclr2026/iclr2026_conference.pdf similarity index 100% rename from skills/research/research-paper-writing/templates/iclr2026/iclr2026_conference.pdf rename to optional-skills/research/research-paper-writing/templates/iclr2026/iclr2026_conference.pdf diff --git a/skills/research/research-paper-writing/templates/iclr2026/iclr2026_conference.sty b/optional-skills/research/research-paper-writing/templates/iclr2026/iclr2026_conference.sty similarity index 100% rename from skills/research/research-paper-writing/templates/iclr2026/iclr2026_conference.sty rename to optional-skills/research/research-paper-writing/templates/iclr2026/iclr2026_conference.sty diff --git a/skills/research/research-paper-writing/templates/iclr2026/iclr2026_conference.tex b/optional-skills/research/research-paper-writing/templates/iclr2026/iclr2026_conference.tex similarity index 100% rename from skills/research/research-paper-writing/templates/iclr2026/iclr2026_conference.tex rename to optional-skills/research/research-paper-writing/templates/iclr2026/iclr2026_conference.tex diff --git a/skills/research/research-paper-writing/templates/iclr2026/math_commands.tex b/optional-skills/research/research-paper-writing/templates/iclr2026/math_commands.tex similarity index 100% rename from skills/research/research-paper-writing/templates/iclr2026/math_commands.tex rename to optional-skills/research/research-paper-writing/templates/iclr2026/math_commands.tex diff --git a/skills/research/research-paper-writing/templates/iclr2026/natbib.sty b/optional-skills/research/research-paper-writing/templates/iclr2026/natbib.sty similarity index 100% rename from skills/research/research-paper-writing/templates/iclr2026/natbib.sty rename to optional-skills/research/research-paper-writing/templates/iclr2026/natbib.sty diff --git a/skills/research/research-paper-writing/templates/icml2026/algorithm.sty b/optional-skills/research/research-paper-writing/templates/icml2026/algorithm.sty similarity index 100% rename from skills/research/research-paper-writing/templates/icml2026/algorithm.sty rename to optional-skills/research/research-paper-writing/templates/icml2026/algorithm.sty diff --git a/skills/research/research-paper-writing/templates/icml2026/algorithmic.sty b/optional-skills/research/research-paper-writing/templates/icml2026/algorithmic.sty similarity index 100% rename from skills/research/research-paper-writing/templates/icml2026/algorithmic.sty rename to optional-skills/research/research-paper-writing/templates/icml2026/algorithmic.sty diff --git a/skills/research/research-paper-writing/templates/icml2026/example_paper.bib b/optional-skills/research/research-paper-writing/templates/icml2026/example_paper.bib similarity index 100% rename from skills/research/research-paper-writing/templates/icml2026/example_paper.bib rename to optional-skills/research/research-paper-writing/templates/icml2026/example_paper.bib diff --git a/skills/research/research-paper-writing/templates/icml2026/example_paper.pdf b/optional-skills/research/research-paper-writing/templates/icml2026/example_paper.pdf similarity index 100% rename from skills/research/research-paper-writing/templates/icml2026/example_paper.pdf rename to optional-skills/research/research-paper-writing/templates/icml2026/example_paper.pdf diff --git a/skills/research/research-paper-writing/templates/icml2026/example_paper.tex b/optional-skills/research/research-paper-writing/templates/icml2026/example_paper.tex similarity index 100% rename from skills/research/research-paper-writing/templates/icml2026/example_paper.tex rename to optional-skills/research/research-paper-writing/templates/icml2026/example_paper.tex diff --git a/skills/research/research-paper-writing/templates/icml2026/fancyhdr.sty b/optional-skills/research/research-paper-writing/templates/icml2026/fancyhdr.sty similarity index 100% rename from skills/research/research-paper-writing/templates/icml2026/fancyhdr.sty rename to optional-skills/research/research-paper-writing/templates/icml2026/fancyhdr.sty diff --git a/skills/research/research-paper-writing/templates/icml2026/icml2026.bst b/optional-skills/research/research-paper-writing/templates/icml2026/icml2026.bst similarity index 100% rename from skills/research/research-paper-writing/templates/icml2026/icml2026.bst rename to optional-skills/research/research-paper-writing/templates/icml2026/icml2026.bst diff --git a/skills/research/research-paper-writing/templates/icml2026/icml2026.sty b/optional-skills/research/research-paper-writing/templates/icml2026/icml2026.sty similarity index 100% rename from skills/research/research-paper-writing/templates/icml2026/icml2026.sty rename to optional-skills/research/research-paper-writing/templates/icml2026/icml2026.sty diff --git a/skills/research/research-paper-writing/templates/icml2026/icml_numpapers.pdf b/optional-skills/research/research-paper-writing/templates/icml2026/icml_numpapers.pdf similarity index 100% rename from skills/research/research-paper-writing/templates/icml2026/icml_numpapers.pdf rename to optional-skills/research/research-paper-writing/templates/icml2026/icml_numpapers.pdf diff --git a/skills/research/research-paper-writing/templates/neurips2025/Makefile b/optional-skills/research/research-paper-writing/templates/neurips2025/Makefile similarity index 100% rename from skills/research/research-paper-writing/templates/neurips2025/Makefile rename to optional-skills/research/research-paper-writing/templates/neurips2025/Makefile diff --git a/skills/research/research-paper-writing/templates/neurips2025/extra_pkgs.tex b/optional-skills/research/research-paper-writing/templates/neurips2025/extra_pkgs.tex similarity index 100% rename from skills/research/research-paper-writing/templates/neurips2025/extra_pkgs.tex rename to optional-skills/research/research-paper-writing/templates/neurips2025/extra_pkgs.tex diff --git a/skills/research/research-paper-writing/templates/neurips2025/main.tex b/optional-skills/research/research-paper-writing/templates/neurips2025/main.tex similarity index 100% rename from skills/research/research-paper-writing/templates/neurips2025/main.tex rename to optional-skills/research/research-paper-writing/templates/neurips2025/main.tex diff --git a/skills/research/research-paper-writing/templates/neurips2025/neurips.sty b/optional-skills/research/research-paper-writing/templates/neurips2025/neurips.sty similarity index 100% rename from skills/research/research-paper-writing/templates/neurips2025/neurips.sty rename to optional-skills/research/research-paper-writing/templates/neurips2025/neurips.sty diff --git a/skills/smart-home/DESCRIPTION.md b/optional-skills/smart-home/DESCRIPTION.md similarity index 100% rename from skills/smart-home/DESCRIPTION.md rename to optional-skills/smart-home/DESCRIPTION.md diff --git a/skills/smart-home/openhue/SKILL.md b/optional-skills/smart-home/openhue/SKILL.md similarity index 100% rename from skills/smart-home/openhue/SKILL.md rename to optional-skills/smart-home/openhue/SKILL.md diff --git a/optional-skills/software-development/code-wiki/SKILL.md b/optional-skills/software-development/code-wiki/SKILL.md index 4b764ac658..3dc69fbb5a 100644 --- a/optional-skills/software-development/code-wiki/SKILL.md +++ b/optional-skills/software-development/code-wiki/SKILL.md @@ -8,7 +8,7 @@ platforms: [linux, macos, windows] metadata: hermes: tags: [Documentation, Mermaid, Architecture, Diagrams, Wiki, Code-Analysis] - related_skills: [codebase-inspection, github-repo-management] + related_skills: [codebase-inspection, github] --- # Code Wiki Skill diff --git a/skills/github/DESCRIPTION.md b/skills/github/DESCRIPTION.md deleted file mode 100644 index a01a258faf..0000000000 --- a/skills/github/DESCRIPTION.md +++ /dev/null @@ -1,3 +0,0 @@ ---- -description: GitHub workflow skills for managing repositories, pull requests, code reviews, issues, and CI/CD pipelines using the gh CLI and git via terminal. ---- diff --git a/skills/mlops/DESCRIPTION.md b/skills/mlops/DESCRIPTION.md deleted file mode 100644 index a5c3cf8ee9..0000000000 --- a/skills/mlops/DESCRIPTION.md +++ /dev/null @@ -1,3 +0,0 @@ ---- -description: Knowledge and Tools for Machine Learning Operations - tools and frameworks for training, fine-tuning, deploying, and optimizing ML/AI models ---- diff --git a/skills/productivity/document-to-action-items/SKILL.md b/skills/productivity/document-to-action-items/SKILL.md index 1c32c2459f..037848e06b 100644 --- a/skills/productivity/document-to-action-items/SKILL.md +++ b/skills/productivity/document-to-action-items/SKILL.md @@ -8,12 +8,12 @@ platforms: [linux, macos, windows] metadata: hermes: tags: [Documents, OCR, Action-Items, Deadlines, Extraction] - related_skills: [ocr-and-documents, pdf, docx, notion] + related_skills: [pdf, pdf, docx, notion] --- # Document to Action Items -Turn documents into cited facts and proposed actions. Extraction is not legal advice, and low-confidence OCR or ambiguous language must remain visible. The `ocr-and-documents` / `pdf` / `docx` skills own extraction mechanics; this skill owns what happens to the extracted content. +Turn documents into cited facts and proposed actions. Extraction is not legal advice, and low-confidence OCR or ambiguous language must remain visible. The `pdf` / `pdf` / `docx` skills own extraction mechanics; this skill owns what happens to the extracted content. ## When to Use @@ -22,7 +22,7 @@ Turn documents into cited facts and proposed actions. Extraction is not legal ad - "Read these scanned forms and structure the data." - "Find risks, owners, and follow-ups in these attachments." -Don't use for: plain text extraction with no downstream structuring (load `ocr-and-documents` directly). +Don't use for: plain text extraction with no downstream structuring (load `pdf` directly). ## Procedure @@ -32,7 +32,7 @@ Use `read_file` for local files and `web_extract` for URLs to identify files, ve ### 2. Extract with provenance -Load `ocr-and-documents`, `pdf`, or `docx`. Extract text/tables while retaining file and page/section coordinates. For scans, record OCR confidence or visible quality issues. Done when every extracted field can cite its source location. +Load `pdf`, `pdf`, or `docx`. Extract text/tables while retaining file and page/section coordinates. For scans, record OCR confidence or visible quality issues. Done when every extracted field can cite its source location. ### 3. Classify evidence diff --git a/skills/productivity/ocr-and-documents/DESCRIPTION.md b/skills/productivity/ocr-and-documents/DESCRIPTION.md deleted file mode 100644 index b74c8a0c68..0000000000 --- a/skills/productivity/ocr-and-documents/DESCRIPTION.md +++ /dev/null @@ -1,3 +0,0 @@ ---- -description: Skills for extracting text from PDFs, scanned documents, images, and other file formats using OCR and document parsing tools. ---- diff --git a/skills/productivity/pdf/SKILL.md b/skills/productivity/pdf/SKILL.md index a10b25fdca..26e357f93a 100644 --- a/skills/productivity/pdf/SKILL.md +++ b/skills/productivity/pdf/SKILL.md @@ -1,20 +1,23 @@ --- name: pdf -description: Create, read, merge, fill, and secure PDF files. -version: 1.0.0 +description: "PDF files: create, read, merge, fill, OCR, edit text." +version: 1.1.0 author: Nous Research license: MIT platforms: [linux, macos, windows] metadata: hermes: - tags: [pdf, documents, forms, reportlab, pypdf, pdfplumber] + tags: [pdf, documents, forms, ocr, text-extraction, reportlab, pypdf, pdfplumber, pymupdf, marker] category: productivity - related_skills: [docx, xlsx, powerpoint, ocr-and-documents] + related_skills: [docx, xlsx, powerpoint] --- # PDF Skill -Create PDFs from structured specs, build and fill AcroForm forms (with layout linting and visual overlays), extract text/tables/metadata, merge/split/rotate/watermark/stamp pages, export page images, manage metadata and attachments, and encrypt/decrypt — using pypdf, reportlab, and pdfplumber. Scanned (image-only) PDFs contain no text layer: OCR is explicitly out of scope here — when a page is image-only, stop and use the `ocr-and-documents` skill instead of pretending to extract text. +Create PDFs from structured specs, build and fill AcroForm forms (with layout linting and visual overlays), extract text/tables/metadata, merge/split/rotate/watermark/stamp pages, export page images, manage metadata and attachments, and encrypt/decrypt — using pypdf, reportlab, and pdfplumber. Two absorbed capabilities live in references/ (read the matching file before those tasks): + +- **Scanned/image-only PDFs and OCR** (pymupdf fast path, marker-pdf quality path, scripts/extract_pymupdf.py + scripts/extract_marker.py): `references/ocr-extraction.md` +- **Editing text inside an existing PDF via natural-language prompts** (nano-pdf CLI): `references/nano-pdf-editing.md` ## When to Use @@ -24,7 +27,7 @@ Create PDFs from structured specs, build and fill AcroForm forms (with layout li - Merge, split, rotate, extract page subsets, watermark, stamp text/images at coordinates, bookmark, or compress PDFs. - Export pages as PNGs for visual review or for OCR hand-off; set/clear document metadata; add/extract file attachments. - Fill or flatten AcroForm forms; encrypt or decrypt with passwords. -- NOT for scanned/image-only PDFs (use `ocr-and-documents`) and NOT for pixel-perfect HTML-to-PDF rendering (use a headless browser). +- NOT for scanned/image-only PDFs (use `references/ocr-extraction.md`) and NOT for pixel-perfect HTML-to-PDF rendering (use a headless browser). ## Prerequisites @@ -83,7 +86,7 @@ python scripts/pdf_meta.py doc.pdf --list-attachments | --extract-attachments di ## Procedure -1. **Inspect first.** Run `pdf_read.py file.pdf --meta`. Check `encrypted` (if true, decrypt first with `pdf_secure.py --decrypt`) and `likely_scanned_pages`. If pages are image-only, export them with `pdf_page_image.py --pages --dpi 300 --out-dir imgs/` and hand the PNGs to the `ocr-and-documents` skill — do not report empty text as "no content". +1. **Inspect first.** Run `pdf_read.py file.pdf --meta`. Check `encrypted` (if true, decrypt first with `pdf_secure.py --decrypt`) and `likely_scanned_pages`. If pages are image-only, export them with `pdf_page_image.py --pages --dpi 300 --out-dir imgs/` and hand the PNGs to the `references/ocr-extraction.md` skill — do not report empty text as "no content". 2. **Create.** Write a JSON spec with `write_file` (elements: `heading`, `paragraph`, `table`, `image`, `pagebreak`; optional `title`/`author` metadata; page numbers are added automatically), then run `pdf_create.py`. Verify visually with `vision_analyze` on a rendered page image if layout matters. 3. **Extract.** `--text` gives a JSON list of per-page strings; `--tables` gives row arrays per page and can also emit CSV files. Read results with `read_file`; never eyeball a binary PDF directly. 4. **Manipulate.** `pdf_merge.py` concatenates and can add one bookmark per source file; `pdf_split.py` handles page ranges (1-based, e.g. `1-3,5,9-`), rotation in 90° steps, and `--compress`. Watermark by preparing a single-page stamp PDF (e.g. via `pdf_create.py`) and overlaying it with `pdf_watermark.py`; for one-liner stamps ("sign here", diagonal DRAFT, corner labels) use `pdf_stamp.py` with text or an image at explicit coordinates. @@ -95,7 +98,7 @@ python scripts/pdf_meta.py doc.pdf --list-attachments | --extract-attachments di ## Pitfalls -- **Scanned PDFs**: empty `extract_text()` plus page images means there is no text layer. Route to `ocr-and-documents`; do not fabricate text. +- **Scanned PDFs**: empty `extract_text()` plus page images means there is no text layer. Route to `references/ocr-extraction.md`; do not fabricate text. - **Flattening limits**: `pdf_fill_form.py --flatten` uses pypdf's flatten support, which converts widget appearances into page content. It is reliable for plain text fields and checkboxes but can drop or misrender exotic widgets (rich text, custom appearance streams, some radio groups). Verify the flattened output visually with `vision_analyze`; for bulletproof flattening use an external renderer (e.g. Ghostscript or `pdftoppm`+reassembly) as a fallback. - **NeedAppearances**: after filling, viewers only render values if appearance streams exist. The fill script sets the AcroForm `NeedAppearances` flag so conforming viewers regenerate them; some minimal viewers ignore it — flatten if display fidelity matters. - **Non-Latin form values**: values are stored correctly (UTF-16), but the field's default font may lack glyphs, so a viewer can show blanks even though the data round-trips. Verify with `--fields`, not just visually. diff --git a/skills/productivity/nano-pdf/SKILL.md b/skills/productivity/pdf/references/nano-pdf-editing.md similarity index 78% rename from skills/productivity/nano-pdf/SKILL.md rename to skills/productivity/pdf/references/nano-pdf-editing.md index a8022c8185..44ecde5d90 100644 --- a/skills/productivity/nano-pdf/SKILL.md +++ b/skills/productivity/pdf/references/nano-pdf-editing.md @@ -1,17 +1,4 @@ ---- -name: nano-pdf -description: "Edit text in existing PDFs via natural-language prompts." -version: 1.0.0 -author: community -license: MIT -platforms: [linux, macos, windows] -metadata: - hermes: - tags: [PDF, Documents, Editing, NLP, Productivity] - homepage: https://pypi.org/project/nano-pdf/ - related_skills: [pdf, ocr-and-documents] ---- - +# Natural-language PDF text editing with nano-pdf (merged from the nano-pdf skill) # nano-pdf Edit PDFs using natural-language instructions. Point it at a page and describe what to change. For structural PDF work (merge, split, forms, watermarks, creation), see the `pdf` skill; for text extraction from scans, see `ocr-and-documents`. diff --git a/skills/productivity/ocr-and-documents/SKILL.md b/skills/productivity/pdf/references/ocr-extraction.md similarity index 94% rename from skills/productivity/ocr-and-documents/SKILL.md rename to skills/productivity/pdf/references/ocr-extraction.md index 0677b70a15..fd44d519db 100644 --- a/skills/productivity/ocr-and-documents/SKILL.md +++ b/skills/productivity/pdf/references/ocr-extraction.md @@ -1,16 +1,6 @@ ---- -name: ocr-and-documents -description: "Extract text from PDFs/scans (pymupdf, marker-pdf)." -version: 2.3.0 -author: Hermes Agent -license: MIT -platforms: [linux, macos, windows] -metadata: - hermes: - tags: [PDF, Documents, Research, Arxiv, Text-Extraction, OCR] - related_skills: [pdf, docx, powerpoint] ---- +# OCR & Document Text Extraction (merged from the ocr-and-documents skill) +Scripts referenced below live in this skill's scripts/ directory. # PDF & Document Extraction For DOCX: see the `docx` skill (create/edit) or use `python-docx` for structured reads. diff --git a/skills/productivity/ocr-and-documents/scripts/extract_marker.py b/skills/productivity/pdf/scripts/extract_marker.py similarity index 72% rename from skills/productivity/ocr-and-documents/scripts/extract_marker.py rename to skills/productivity/pdf/scripts/extract_marker.py index d48fd10bb0..044eda22b0 100644 --- a/skills/productivity/ocr-and-documents/scripts/extract_marker.py +++ b/skills/productivity/pdf/scripts/extract_marker.py @@ -62,26 +62,27 @@ def check_requirements(): if __name__ == "__main__": - args = sys.argv[1:] - if not args or args[0] in {"-h", "--help"}: - print(__doc__) - sys.exit(0) + import argparse - if args[0] == "--check": + parser = argparse.ArgumentParser( + description="Extract text from documents using marker-pdf (high-quality OCR + layout analysis)." + ) + parser.add_argument("path", nargs="?", help="Document to convert (PDF, DOCX, PPTX, XLSX, HTML, EPUB, image)") + parser.add_argument("--output_dir", help="Directory to save extracted images") + parser.add_argument("--json", action="store_true", help="Structured JSON output instead of markdown") + parser.add_argument("--use_llm", action="store_true", help="LLM-boosted accuracy") + parser.add_argument("--check", action="store_true", help="Check disk space requirements and exit") + args = parser.parse_args() + + if args.check: check_requirements() sys.exit(0) + if not args.path: + parser.error("path is required unless --check is given") - path = args[0] - output_dir = None - output_format = "markdown" - use_llm = False - - if "--output_dir" in args: - idx = args.index("--output_dir") - output_dir = args[idx + 1] - if "--json" in args: - output_format = "json" - if "--use_llm" in args: - use_llm = True - - convert(path, output_dir=output_dir, output_format=output_format, use_llm=use_llm) + convert( + args.path, + output_dir=args.output_dir, + output_format="json" if args.json else "markdown", + use_llm=args.use_llm, + ) diff --git a/skills/productivity/ocr-and-documents/scripts/extract_pymupdf.py b/skills/productivity/pdf/scripts/extract_pymupdf.py similarity index 65% rename from skills/productivity/ocr-and-documents/scripts/extract_pymupdf.py rename to skills/productivity/pdf/scripts/extract_pymupdf.py index 50cb8ee86c..0edc2bd51f 100644 --- a/skills/productivity/ocr-and-documents/scripts/extract_pymupdf.py +++ b/skills/productivity/pdf/scripts/extract_pymupdf.py @@ -67,32 +67,35 @@ def show_metadata(path): }, indent=2)) if __name__ == "__main__": - args = sys.argv[1:] - if not args or args[0] in {"-h", "--help"}: - print(__doc__) - sys.exit(0) + import argparse + + parser = argparse.ArgumentParser( + description="Extract text/tables/images/metadata from documents using pymupdf (lightweight, no models)." + ) + parser.add_argument("path", help="Document to read") + parser.add_argument("--pages", help="Page selection: N or START-END (0-indexed)") + parser.add_argument("--markdown", action="store_true", help="Markdown output via pymupdf4llm") + parser.add_argument("--tables", action="store_true", help="Extract tables as markdown") + parser.add_argument("--images", nargs="?", const="./images", metavar="OUTPUT_DIR", + help="Extract embedded images to OUTPUT_DIR (default ./images)") + parser.add_argument("--metadata", action="store_true", help="Show document metadata as JSON") + args = parser.parse_args() - path = args[0] pages = None - - if "--pages" in args: - idx = args.index("--pages") - p = args[idx + 1] - if "-" in p: - start, end = p.split("-") + if args.pages: + if "-" in args.pages: + start, end = args.pages.split("-") pages = list(range(int(start), int(end) + 1)) else: - pages = [int(p)] + pages = [int(args.pages)] - if "--metadata" in args: - show_metadata(path) - elif "--tables" in args: - extract_tables(path) - elif "--images" in args: - idx = args.index("--images") - output_dir = args[idx + 1] if idx + 1 < len(args) else "./images" - extract_images(path, output_dir) - elif "--markdown" in args: - extract_markdown(path, pages=pages) + if args.metadata: + show_metadata(args.path) + elif args.tables: + extract_tables(args.path) + elif args.images is not None: + extract_images(args.path, args.images) + elif args.markdown: + extract_markdown(args.path, pages=pages) else: - extract_text(path, pages=pages) + extract_text(args.path, pages=pages) diff --git a/skills/productivity/pdf/scripts/pdf_page_image.py b/skills/productivity/pdf/scripts/pdf_page_image.py index bb25584820..eeecdc8f7b 100644 --- a/skills/productivity/pdf/scripts/pdf_page_image.py +++ b/skills/productivity/pdf/scripts/pdf_page_image.py @@ -6,7 +6,7 @@ When neither is available, exits 0 with {"rendered": false, "missing": [...]} so callers can branch instead of crashing. Typical uses: visual verification with a vision model, and exporting -image-only (scanned) pages for hand-off to the ocr-and-documents skill. +image-only (scanned) pages for hand-off to the references/ocr-extraction.md in this skill. """ from __future__ import annotations diff --git a/skills/productivity/pdf/scripts/pdf_read.py b/skills/productivity/pdf/scripts/pdf_read.py index aa032a3d82..208785863a 100644 --- a/skills/productivity/pdf/scripts/pdf_read.py +++ b/skills/productivity/pdf/scripts/pdf_read.py @@ -96,7 +96,7 @@ def read_meta(path: str, password: str | None) -> dict: } if likely_scanned: out["note"] = ("Image-only pages detected: no text layer to extract. " - "Use the ocr-and-documents skill for OCR.") + "Use the references/ocr-extraction.md in this skill for OCR.") return out diff --git a/skills/productivity/session-librarian/SKILL.md b/skills/productivity/session-librarian/SKILL.md deleted file mode 100644 index 4e605e0e73..0000000000 --- a/skills/productivity/session-librarian/SKILL.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -name: session-librarian -description: "Organize sessions by prompt: find, rename, archive, prune." -version: 1.0.0 -author: Hermes Agent + Teknium -license: MIT -platforms: [linux, macos, windows] -metadata: - hermes: - tags: [Sessions, Organization, Cleanup, Library, Productivity] - category: productivity - related_skills: [weekly-review-planning] ---- - -# Session Librarian - -Manage the user's session library conversationally: find past sessions about a -topic, summarize what they decided, rename them meaningfully, split work into -parallel sessions, and propose stale ones for archive or deletion — all from a -plain-language request like *"find my sessions about Q3 pricing, keep the -useful ones, and clean up the duplicates."* - -Inspired by Perplexity Computer's prompt-driven session management (Aug 2026): -the agent starts, organizes, and cleans up the user's own session library, and -always shows the plan before touching anything. - -## When to Use - -- "What sessions do I have about X?" / "What did we decide about X?" -- "Rename these sessions to something meaningful." -- "Clean up my session library" / "archive the stale ones." -- "Fork that session into a follow-up focused on Y." -- "Split this into one session per ticket" (see Parallel workstreams below). - -## The Two Surfaces - -| Task | Surface | -|---|---| -| Find sessions by topic, read content, summarize decisions | `session_search` tool (FTS5 over the message store) | -| List/filter by metadata (age, source, cost, tokens, workspace) | `hermes sessions list` / `stats` via terminal | -| Rename | `hermes sessions rename ` | -| Bulk soft-hide (reversible) | `hermes sessions archive ` | -| Delete (destructive) | `hermes sessions delete` / `hermes sessions prune ` | -| Export before deleting anything valuable | `hermes sessions export --session-id --format md` | -| Continue work in a new place | `/branch` (fork current session) or start a fresh session and cite the summary | - -## Procedure - -① **Discover.** Use `session_search(query=..., limit=5-10)` with topic -keywords; vary phrasing (feature name, symptom, project name). For metadata -sweeps ("sessions older than 60 days from telegram"), use -`hermes sessions list --source telegram --limit 50` instead. - -② **Summarize per session.** The discovery result's `bookend_start` (goal), -match window, and `bookend_end` (resolution) usually suffice — only dump a -full session (`session_search(session_id=...)`) when the user asks for -decisions in depth. Report each as: link (`@session:` form) — one-line goal — -one-line outcome. - -③ **Plan before acting (MANDATORY for anything that mutates).** Present a -plan table first: which sessions get renamed to what, which get archived, -which are proposed for deletion and why (duplicate of which keeper, stale, -empty). Wait for the user's go-ahead. Exception: a single rename the user -explicitly dictated can be done directly. - -④ **Act with the safest primitive.** -- Prefer `archive` (reversible soft-hide) over `delete`/`prune`. -- Always run destructive commands with `--dry-run` first and show the output, - then re-run with `--yes` after confirmation. -- Before deleting anything with meaningful content, offer - `hermes sessions export --format md` as a backup. - -⑤ **Report.** Renames applied, sessions archived (count + how to undo: -archived sessions remain in the DB and are listed with `--include-archived`), -anything exported, anything skipped and why. - -## Parallel Workstreams - -For "one session per ticket, investigate each, report back": do NOT try to -drive other live sessions. Use `delegate_task` with one task per workstream — -each subagent runs in its own session automatically — then synthesize their -summaries. Mention that each delegation's transcript is itself searchable -later via `session_search`. - -## Pitfalls - -- **Never delete without a dry-run + explicit confirmation in this - conversation.** A standing "clean things up" is authority to *propose*, not - to prune. -- **`session_search` finds content, not metadata.** Age/cost/source filters - live in the CLI; combine both when the request mixes them ("old sessions - about pricing"). -- **Titles are identity for `/resume `.** When renaming, keep titles - short, unique, and prefix-friendly; warn the user if a rename collides with - an existing title. -- **Archived ≠ deleted.** Archive hides sessions from default listings only. - Say which one you did. -- **Cross-profile session links** (`@session:<profile>/<id>`) are read-only - from another profile; management commands act on the current profile's DB. - -## Verification - -After a cleanup pass, re-run the discovery query and `hermes sessions list` -to confirm the library reflects the plan (keepers present with new titles, -archived ones gone from the default listing). diff --git a/skills/productivity/teams-meeting-pipeline/SKILL.md b/skills/productivity/teams-meeting-pipeline/SKILL.md index dc2f88611e..041aa5ab83 100644 --- a/skills/productivity/teams-meeting-pipeline/SKILL.md +++ b/skills/productivity/teams-meeting-pipeline/SKILL.md @@ -11,6 +11,10 @@ prerequisites: metadata: hermes: tags: [Teams, Microsoft Graph, Meetings, Productivity, Operations] + # Channel-gated: this pipeline only makes sense on the Teams gateway + # channel (and in cron jobs, where its scheduled summary/replay work + # actually runs). Hidden from every other session's skills index. + session_platforms: [teams, cron] related_docs: - /docs/guides/microsoft-graph-app-registration - /docs/user-guide/messaging/teams-meetings diff --git a/skills/research/arxiv/SKILL.md b/skills/research/arxiv/SKILL.md index e3e6ac738f..e627145589 100644 --- a/skills/research/arxiv/SKILL.md +++ b/skills/research/arxiv/SKILL.md @@ -8,7 +8,7 @@ platforms: [linux, macos, windows] metadata: hermes: tags: [Research, Arxiv, Papers, Academic, Science, API] - related_skills: [ocr-and-documents] + related_skills: [pdf] --- # arXiv Research diff --git a/skills/research/grounded-citations/SKILL.md b/skills/research/grounded-citations/SKILL.md index 4c767369f4..ae69fb98b0 100644 --- a/skills/research/grounded-citations/SKILL.md +++ b/skills/research/grounded-citations/SKILL.md @@ -9,7 +9,7 @@ metadata: hermes: tags: [Research, Citations, Grounding, Sources, Web, Reports] category: research - related_skills: [research-paper-writing, arxiv, ocr-and-documents] + related_skills: [arxiv, pdf] --- # Grounded Citations @@ -26,7 +26,7 @@ and `verify --evidence` fails any draft whose cited sources carry no evidence. This skill covers answers in chat, written documents (markdown, PDF, docx, slides), and research reports. It does not cover academic BibTeX pipelines — -for conference papers use the `research-paper-writing` skill, which this skill +for conference papers use the `arxiv` skill, which this skill feeds (see `references/citation-formats.md`). ## When to Use diff --git a/skills/research/grounded-citations/references/citation-formats.md b/skills/research/grounded-citations/references/citation-formats.md index d83e270bf0..cf7d3f7f5b 100644 --- a/skills/research/grounded-citations/references/citation-formats.md +++ b/skills/research/grounded-citations/references/citation-formats.md @@ -53,7 +53,7 @@ consistency is the reason not to reset the ledger between pages of one build. ## Research papers -Hand off to the `research-paper-writing` skill. Export with +Hand off to the `grounded-citations` skill. Export with `--style bibtex` into `references.bib`, then follow that skill's citation verification (it greps `\cite{...}` against the .bib). The ledger's job ends at producing verified URL entries; venue formatting is that skill's domain. diff --git a/skills/github/codebase-inspection/SKILL.md b/skills/software-development/codebase-inspection/SKILL.md similarity index 98% rename from skills/github/codebase-inspection/SKILL.md rename to skills/software-development/codebase-inspection/SKILL.md index d42b9a2292..198b7e9c72 100644 --- a/skills/github/codebase-inspection/SKILL.md +++ b/skills/software-development/codebase-inspection/SKILL.md @@ -8,7 +8,7 @@ platforms: [linux, macos, windows] metadata: hermes: tags: [LOC, Code Analysis, pygount, Codebase, Metrics, Repository] - related_skills: [github-repo-management] + related_skills: [github] prerequisites: commands: [pygount] --- diff --git a/skills/software-development/github/SKILL.md b/skills/software-development/github/SKILL.md new file mode 100644 index 0000000000..8e843115e3 --- /dev/null +++ b/skills/software-development/github/SKILL.md @@ -0,0 +1,56 @@ +--- +name: github +description: "GitHub via gh CLI: PRs, issues, reviews, repos, auth." +version: 2.0.0 +author: Ben Barclay (benbarclay), Hermes Agent +license: MIT +platforms: [linux, macos, windows] +metadata: + hermes: + tags: [github, gh, git, pull-requests, issues, code-review, repos, auth, ci] + category: software-development + related_skills: [codebase-inspection, requesting-code-review] +--- + +# 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. diff --git a/skills/github/github-auth/SKILL.md b/skills/software-development/github/references/auth.md similarity index 96% rename from skills/github/github-auth/SKILL.md rename to skills/software-development/github/references/auth.md index ec4884c905..7d13a5110b 100644 --- a/skills/github/github-auth/SKILL.md +++ b/skills/software-development/github/references/auth.md @@ -1,16 +1,3 @@ ---- -name: github-auth -description: "GitHub auth setup: HTTPS tokens, SSH keys, gh CLI login." -version: 1.1.0 -author: Hermes Agent -license: MIT -platforms: [linux, macos, windows] -metadata: - hermes: - tags: [GitHub, Authentication, Git, gh-cli, SSH, Setup] - related_skills: [github-pr-workflow, github-code-review, github-issues, github-repo-management] ---- - # GitHub Authentication Setup This skill sets up authentication so the agent can work with GitHub repositories, PRs, issues, and CI. It covers two paths: diff --git a/skills/github/github-pr-workflow/references/ci-troubleshooting.md b/skills/software-development/github/references/ci-troubleshooting.md similarity index 100% rename from skills/github/github-pr-workflow/references/ci-troubleshooting.md rename to skills/software-development/github/references/ci-troubleshooting.md diff --git a/skills/github/github-code-review/SKILL.md b/skills/software-development/github/references/code-review.md similarity index 97% rename from skills/github/github-code-review/SKILL.md rename to skills/software-development/github/references/code-review.md index 38b0989b1c..7e52dd2779 100644 --- a/skills/github/github-code-review/SKILL.md +++ b/skills/software-development/github/references/code-review.md @@ -1,16 +1,3 @@ ---- -name: github-code-review -description: "Review PRs: diffs, inline comments via gh or REST." -version: 1.1.0 -author: Hermes Agent -license: MIT -platforms: [linux, macos, windows] -metadata: - hermes: - tags: [GitHub, Code-Review, Pull-Requests, Git, Quality] - related_skills: [github-auth, github-pr-workflow] ---- - # GitHub Code Review Perform code reviews on local changes before pushing, or review open PRs on GitHub. Most of this skill uses plain `git` — the `gh`/`curl` split only matters for PR-level interactions. diff --git a/skills/github/github-pr-workflow/references/conventional-commits.md b/skills/software-development/github/references/conventional-commits.md similarity index 100% rename from skills/github/github-pr-workflow/references/conventional-commits.md rename to skills/software-development/github/references/conventional-commits.md diff --git a/skills/github/github-repo-management/references/github-api-cheatsheet.md b/skills/software-development/github/references/github-api-cheatsheet.md similarity index 100% rename from skills/github/github-repo-management/references/github-api-cheatsheet.md rename to skills/software-development/github/references/github-api-cheatsheet.md diff --git a/skills/github/github-issue-to-pr/SKILL.md b/skills/software-development/github/references/issue-to-pr.md similarity index 93% rename from skills/github/github-issue-to-pr/SKILL.md rename to skills/software-development/github/references/issue-to-pr.md index 343725c233..f25717cb0c 100644 --- a/skills/github/github-issue-to-pr/SKILL.md +++ b/skills/software-development/github/references/issue-to-pr.md @@ -1,16 +1,3 @@ ---- -name: github-issue-to-pr -description: "Carry a GitHub issue to a verified PR with honest CI state." -version: 0.1.0 -author: Ben Barclay (benbarclay), Hermes Agent -license: MIT -platforms: [linux, macos, windows] -metadata: - hermes: - tags: [GitHub, Issues, Coding, Pull-Requests, CI] - related_skills: [github-issues, github-pr-workflow, systematic-debugging, test-driven-development, requesting-code-review] ---- - # GitHub Issue to Pull Request Turn a GitHub issue into a tested, verified PR. This skill owns the end-to-end discipline — premise validation, duplicate sweeps, class-level fixes, and honest CI reporting; the sibling GitHub and development skills own their own mechanics. diff --git a/skills/github/github-issues/SKILL.md b/skills/software-development/github/references/issues.md similarity index 96% rename from skills/github/github-issues/SKILL.md rename to skills/software-development/github/references/issues.md index 39172fbb47..3ceef2ffc3 100644 --- a/skills/github/github-issues/SKILL.md +++ b/skills/software-development/github/references/issues.md @@ -1,16 +1,3 @@ ---- -name: github-issues -description: "Create, triage, label, assign GitHub issues via gh or REST." -version: 1.1.0 -author: Hermes Agent -license: MIT -platforms: [linux, macos, windows] -metadata: - hermes: - tags: [GitHub, Issues, Project-Management, Bug-Tracking, Triage] - related_skills: [github-auth, github-pr-workflow] ---- - # GitHub Issues Management Create, search, triage, and manage GitHub issues. Each section shows `gh` first, then the `curl` fallback. diff --git a/skills/github/github-pr-workflow/SKILL.md b/skills/software-development/github/references/pr-workflow.md similarity index 96% rename from skills/github/github-pr-workflow/SKILL.md rename to skills/software-development/github/references/pr-workflow.md index b8a71bf68f..2619bd4b82 100644 --- a/skills/github/github-pr-workflow/SKILL.md +++ b/skills/software-development/github/references/pr-workflow.md @@ -1,16 +1,3 @@ ---- -name: github-pr-workflow -description: "GitHub PR lifecycle: branch, commit, open, CI, merge." -version: 1.1.0 -author: Hermes Agent -license: MIT -platforms: [linux, macos, windows] -metadata: - hermes: - tags: [GitHub, Pull-Requests, CI/CD, Git, Automation, Merge] - related_skills: [github-auth, github-code-review] ---- - # GitHub Pull Request Workflow Complete guide for managing the PR lifecycle. Each section shows the `gh` way first, then the `git` + `curl` fallback for machines without `gh`. diff --git a/skills/github/github-repo-management/SKILL.md b/skills/software-development/github/references/repo-management.md similarity index 97% rename from skills/github/github-repo-management/SKILL.md rename to skills/software-development/github/references/repo-management.md index af147a6fa4..b0988c61fe 100644 --- a/skills/github/github-repo-management/SKILL.md +++ b/skills/software-development/github/references/repo-management.md @@ -1,16 +1,3 @@ ---- -name: github-repo-management -description: "Clone/create/fork repos; manage remotes, releases." -version: 1.1.0 -author: Hermes Agent -license: MIT -platforms: [linux, macos, windows] -metadata: - hermes: - tags: [GitHub, Repositories, Git, Releases, Secrets, Configuration] - related_skills: [github-auth, github-pr-workflow, github-issues] ---- - # GitHub Repository Management Create, clone, fork, configure, and manage GitHub repositories. Each section shows `gh` first, then the `git` + `curl` fallback. diff --git a/skills/github/github-code-review/references/review-output-template.md b/skills/software-development/github/references/review-output-template.md similarity index 100% rename from skills/github/github-code-review/references/review-output-template.md rename to skills/software-development/github/references/review-output-template.md diff --git a/skills/github/github-auth/scripts/gh-env.sh b/skills/software-development/github/scripts/gh-env.sh similarity index 100% rename from skills/github/github-auth/scripts/gh-env.sh rename to skills/software-development/github/scripts/gh-env.sh diff --git a/skills/github/github-auth/scripts/git-credential-token.py b/skills/software-development/github/scripts/git-credential-token.py similarity index 100% rename from skills/github/github-auth/scripts/git-credential-token.py rename to skills/software-development/github/scripts/git-credential-token.py diff --git a/skills/github/github-issues/templates/bug-report.md b/skills/software-development/github/templates/bug-report.md similarity index 100% rename from skills/github/github-issues/templates/bug-report.md rename to skills/software-development/github/templates/bug-report.md diff --git a/skills/github/github-issues/templates/feature-request.md b/skills/software-development/github/templates/feature-request.md similarity index 100% rename from skills/github/github-issues/templates/feature-request.md rename to skills/software-development/github/templates/feature-request.md diff --git a/skills/github/github-pr-workflow/templates/pr-body-bugfix.md b/skills/software-development/github/templates/pr-body-bugfix.md similarity index 100% rename from skills/github/github-pr-workflow/templates/pr-body-bugfix.md rename to skills/software-development/github/templates/pr-body-bugfix.md diff --git a/skills/github/github-pr-workflow/templates/pr-body-feature.md b/skills/software-development/github/templates/pr-body-feature.md similarity index 100% rename from skills/github/github-pr-workflow/templates/pr-body-feature.md rename to skills/software-development/github/templates/pr-body-feature.md diff --git a/skills/software-development/requesting-code-review/SKILL.md b/skills/software-development/requesting-code-review/SKILL.md index 0a543cee2b..1209c3411c 100644 --- a/skills/software-development/requesting-code-review/SKILL.md +++ b/skills/software-development/requesting-code-review/SKILL.md @@ -8,7 +8,7 @@ platforms: [linux, macos, windows] metadata: hermes: tags: [code-review, security, verification, quality, pre-commit, auto-fix] - related_skills: [subagent-driven-development, test-driven-development, github-code-review] + related_skills: [subagent-driven-development, test-driven-development, github] --- # Pre-Commit Code Verification @@ -27,8 +27,8 @@ quality gates, an independent reviewer subagent, and an auto-fix loop. **Skip for:** documentation-only changes, pure config tweaks, or when user says "skip verification". -**This skill vs github-code-review:** This skill verifies YOUR changes before committing. -`github-code-review` reviews OTHER people's PRs on GitHub with inline comments. +**This skill vs github:** This skill verifies YOUR changes before committing. +`github` reviews OTHER people's PRs on GitHub with inline comments. ## Step 1 — Get the diff diff --git a/skills/web/DESCRIPTION.md b/skills/web/DESCRIPTION.md new file mode 100644 index 0000000000..2f6af71f51 --- /dev/null +++ b/skills/web/DESCRIPTION.md @@ -0,0 +1,3 @@ +--- +description: Skills for reaching web content when direct access fails — blocked, paywalled, rate-limited, or bot-walled pages. +--- diff --git a/skills/research/blocked-page-recovery/SKILL.md b/skills/web/blocked-page-recovery/SKILL.md similarity index 98% rename from skills/research/blocked-page-recovery/SKILL.md rename to skills/web/blocked-page-recovery/SKILL.md index 64d19dc967..1385e08b31 100644 --- a/skills/research/blocked-page-recovery/SKILL.md +++ b/skills/web/blocked-page-recovery/SKILL.md @@ -1,6 +1,6 @@ --- name: blocked-page-recovery -description: "Recover blocked/paywalled/WAF'd pages via fallbacks." +description: "Use when a fetch fails: 403/429, paywall, WAF, bot wall." version: 1.0.0 author: Hermes Agent license: MIT diff --git a/skills/research/blocked-page-recovery/scripts/recover_page.py b/skills/web/blocked-page-recovery/scripts/recover_page.py similarity index 100% rename from skills/research/blocked-page-recovery/scripts/recover_page.py rename to skills/web/blocked-page-recovery/scripts/recover_page.py diff --git a/tests/agent/test_skill_session_platform_gate.py b/tests/agent/test_skill_session_platform_gate.py new file mode 100644 index 0000000000..9672e8f95b --- /dev/null +++ b/tests/agent/test_skill_session_platform_gate.py @@ -0,0 +1,48 @@ +"""The session_platforms frontmatter gate (skills-index slim PR). + +A skill whose metadata.hermes.session_platforms names gateway channels is +hidden from the skills index on every other channel; unknown platform +fails OPEN (offline builds/tests must not hide skills). +""" +from agent.prompt_builder import _skill_should_show +from agent.skill_utils import extract_skill_conditions + + +def _conds(platforms): + return extract_skill_conditions( + {"metadata": {"hermes": {"session_platforms": platforms}}} + ) + + +class TestSessionPlatformGate: + def test_hidden_on_other_channel(self): + assert _skill_should_show(_conds(["teams", "cron"]), {"terminal"}, set(), "desktop") is False + assert _skill_should_show(_conds(["teams", "cron"]), {"terminal"}, set(), "telegram") is False + + def test_shown_on_named_channel(self): + assert _skill_should_show(_conds(["teams", "cron"]), {"terminal"}, set(), "teams") is True + assert _skill_should_show(_conds(["teams", "cron"]), {"terminal"}, set(), "cron") is True + + def test_case_insensitive(self): + assert _skill_should_show(_conds(["Teams"]), {"terminal"}, set(), "TEAMS") is True + + def test_unknown_platform_fails_open(self): + assert _skill_should_show(_conds(["teams"]), {"terminal"}, set(), None) is True + assert _skill_should_show(_conds(["teams"]), {"terminal"}, set(), "") is True + + def test_empty_list_visible_everywhere(self): + assert _skill_should_show(_conds([]), {"terminal"}, set(), "desktop") is True + + def test_gate_runs_even_without_tool_info(self): + # The channel gate is independent of tool-filtering backward compat. + assert _skill_should_show(_conds(["teams"]), None, None, "desktop") is False + + def test_teams_meeting_pipeline_carries_the_gate(self): + from pathlib import Path + import re, yaml + + p = Path(__file__).resolve().parents[2] / "skills" / "productivity" / "teams-meeting-pipeline" / "SKILL.md" + content = p.read_text(encoding="utf-8") + m = re.search(r"\n---\s*\n", content[3:]) + fm = yaml.safe_load(content[3 : m.start() + 3]) + assert fm["metadata"]["hermes"]["session_platforms"] == ["teams", "cron"] diff --git a/tests/skills/test_comfyui_skill.py b/tests/skills/test_comfyui_skill.py index b1b3e74b55..7141ee9234 100644 --- a/tests/skills/test_comfyui_skill.py +++ b/tests/skills/test_comfyui_skill.py @@ -1,6 +1,6 @@ """Invariant tests for the bundled comfyui skill. -Covers skills/creative/comfyui — the diffusion workflow runner. Tests assert +Covers optional-skills/creative/comfyui — the diffusion workflow runner. Tests assert contracts (locale-independent file reads), not snapshots of skill content. """ @@ -16,7 +16,7 @@ from pathlib import Path import pytest REPO = Path(__file__).resolve().parent.parent.parent -SCRIPTS = REPO / "skills" / "creative" / "comfyui" / "scripts" +SCRIPTS = REPO / "optional-skills" / "creative" / "comfyui" / "scripts" # Text reads that must not depend on the host locale. The workflow and schema # JSON are user-authored files (exported by ComfyUI or hand-edited), so they diff --git a/tests/skills/test_github_credential_token.py b/tests/skills/test_github_credential_token.py index 433111fcf7..1944aba17f 100644 --- a/tests/skills/test_github_credential_token.py +++ b/tests/skills/test_github_credential_token.py @@ -8,13 +8,13 @@ import pytest REPO_ROOT = Path(__file__).resolve().parents[2] -HELPER = REPO_ROOT / "skills/github/github-auth/scripts/git-credential-token.py" +HELPER = REPO_ROOT / "skills/software-development/github/scripts/git-credential-token.py" LEGACY_SED = r"sed 's|https://[^:]*:\([^@]*\)@.*|\1|'" SHIPPED_TREES = ( - REPO_ROOT / "skills/github", - REPO_ROOT / "website/docs/user-guide/skills/bundled/github", + REPO_ROOT / "skills/software-development/github", + REPO_ROOT / "website/docs/user-guide/skills/bundled/software-development", REPO_ROOT - / "website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/github", + / "website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/software-development", ) diff --git a/tests/skills/test_github_issue_to_pr_skill.py b/tests/skills/test_github_skill.py similarity index 58% rename from tests/skills/test_github_issue_to_pr_skill.py rename to tests/skills/test_github_skill.py index cdbfa95df5..8beba787e6 100644 --- a/tests/skills/test_github_issue_to_pr_skill.py +++ b/tests/skills/test_github_skill.py @@ -1,16 +1,24 @@ -"""Tests for the github-issue-to-pr bundled skill.""" +"""Tests for the github merged skill (formerly six github-* skills). + +The issue-to-pr workflow (originally the github-issue-to-pr skill, +author benbarclay) now lives complete in references/issue-to-pr.md of the +merged software-development/github skill. Frontmatter contracts apply to +the merged SKILL.md; the content pins that guarded the issue-to-pr +disciplines now check the reference body. +""" import re from pathlib import Path import yaml -SKILL_PATH = ( +SKILL_DIR = ( Path(__file__).resolve().parents[2] / "skills" + / "software-development" / "github" - / "github-issue-to-pr" - / "SKILL.md" ) +SKILL_PATH = SKILL_DIR / "SKILL.md" +ISSUE_TO_PR_REF = SKILL_DIR / "references" / "issue-to-pr.md" def _frontmatter_and_body(): @@ -27,11 +35,23 @@ def test_skill_file_exists(): assert SKILL_PATH.is_file() +def test_all_workflow_references_exist(): + for ref in ( + "auth.md", + "issues.md", + "pr-workflow.md", + "issue-to-pr.md", + "code-review.md", + "repo-management.md", + ): + assert (SKILL_DIR / "references" / ref).is_file(), f"missing reference: {ref}" + + def test_frontmatter_required_fields(): fm, _ = _frontmatter_and_body() for field in ("name", "description", "version", "author", "license", "platforms"): assert field in fm, f"missing frontmatter field: {field}" - assert fm["name"] == "github-issue-to-pr" + assert fm["name"] == "github" hermes = fm["metadata"]["hermes"] assert hermes["tags"] assert "related_skills" in hermes @@ -62,30 +82,38 @@ def test_related_skills_resolve_in_repo(): assert hits, f"related_skills entry does not resolve in-repo: {name}" -def test_body_structure_and_size(): +def test_body_routes_every_workflow(): _, body = _frontmatter_and_body() - for section in ("## When to Use", "## Procedure", "## Pitfalls", "## Verification"): - assert section in body, f"missing section: {section}" + for ref in ( + "references/auth.md", + "references/issues.md", + "references/pr-workflow.md", + "references/issue-to-pr.md", + "references/code-review.md", + "references/repo-management.md", + ): + assert ref in body, f"routing table missing: {ref}" assert len(SKILL_PATH.read_text(encoding="utf-8")) <= 100_000 def test_no_machine_local_paths(): - content = SKILL_PATH.read_text(encoding="utf-8") - assert "/home/" not in content - assert not re.search(r"[A-Z]:\\\\Users", content) + for p in (SKILL_PATH, ISSUE_TO_PR_REF): + content = p.read_text(encoding="utf-8") + assert "/home/" not in content + assert not re.search(r"[A-Z]:\\\\Users", content) -def test_steps_have_completion_criteria(): - _, body = _frontmatter_and_body() - steps = re.findall(r"^### \d+\..*?(?=^### \d+\.|^## )", body, re.MULTILINE | re.DOTALL) +def test_issue_to_pr_steps_have_completion_criteria(): + body = ISSUE_TO_PR_REF.read_text(encoding="utf-8") + steps = re.findall(r"^### \d+\..*?(?=^### \d+\.|^## |\Z)", body, re.MULTILINE | re.DOTALL) assert len(steps) >= 6 for step in steps: assert "Done when" in step, f"step missing completion criterion: {step[:60]!r}" -def test_core_disciplines_present(): +def test_issue_to_pr_core_disciplines_present(): """The learnings folded in from maintainer practice must survive edits.""" - _, body = _frontmatter_and_body() + body = ISSUE_TO_PR_REF.read_text(encoding="utf-8") assert "--comments" in body, "must read the full issue thread" assert "pr list --search" in body, "must sweep for duplicate PRs before coding" assert re.search(r"git log -p -S", body), "must check design intent via history" @@ -94,9 +122,9 @@ def test_core_disciplines_present(): assert "dispatches CI" in body, "must open the PR immediately after work exists" -def test_not_a_router_skill(): - """Steps must carry their own procedure, not just route to sibling skills.""" - _, body = _frontmatter_and_body() - steps = re.findall(r"^### \d+\..*?(?=^### \d+\.|^## )", body, re.MULTILINE | re.DOTALL) +def test_issue_to_pr_not_a_router(): + """Reference steps must carry their own procedure, not route elsewhere.""" + body = ISSUE_TO_PR_REF.read_text(encoding="utf-8") + steps = re.findall(r"^### \d+\..*?(?=^### \d+\.|^## |\Z)", body, re.MULTILINE | re.DOTALL) routing = [s for s in steps if re.match(r"^### \d+\.[^\n]*\n+Load `", s)] assert len(routing) == 0, "steps must not open by delegating to another skill" diff --git a/website/docs/reference/optional-skills-catalog.md b/website/docs/reference/optional-skills-catalog.md index 4ab09825e9..48c8959d4c 100644 --- a/website/docs/reference/optional-skills-catalog.md +++ b/website/docs/reference/optional-skills-catalog.md @@ -55,21 +55,27 @@ hermes skills uninstall <skill-name> | Skill | Description | |-------|-------------| +| [**ascii-art**](/docs/user-guide/skills/optional/creative/creative-ascii-art) | ASCII art: pyfiglet, cowsay, boxes, image-to-ascii. | | [**audiocraft-audio-generation**](/docs/user-guide/skills/optional/creative/creative-audiocraft-audio-generation) | AudioCraft: MusicGen text-to-music, AudioGen text-to-sound. | | [**baoyu-article-illustrator**](/docs/user-guide/skills/optional/creative/creative-baoyu-article-illustrator) | Article illustrations: type × style × palette consistency. | | [**baoyu-comic**](/docs/user-guide/skills/optional/creative/creative-baoyu-comic) | Knowledge comics (知识漫画): educational, biography, tutorial. | +| [**comfyui**](/docs/user-guide/skills/optional/creative/creative-comfyui) | Generate images, video, and audio via diffusion workflows. | | [**concept-diagrams**](/docs/user-guide/skills/optional/creative/creative-concept-diagrams) | Generate flat, minimal educational SVG visuals as HTML. | | [**creative-ideation**](/docs/user-guide/skills/optional/creative/creative-creative-ideation) | Generate ideas via named methods from creative practice. | -| [**draw-your-font**](/docs/user-guide/skills/optional/creative/creative-draw-your-font) | Turn a photo of handwriting into an installable font (TTF/WOFF). | +| [**draw-your-font**](/docs/user-guide/skills/optional/creative/creative-draw-your-font) | Turn a handwriting photo into an installable TTF font. | +| [**excalidraw**](/docs/user-guide/skills/optional/creative/creative-excalidraw) | Hand-drawn Excalidraw JSON diagrams (arch, flow, seq). | | [**heartmula**](/docs/user-guide/skills/optional/creative/creative-heartmula) | HeartMuLa: Suno-like song generation from lyrics + tags. | | [**hyperframes**](/docs/user-guide/skills/optional/creative/creative-hyperframes) | Render MP4/WebM videos from HTML compositions. | | [**impeccable**](/docs/user-guide/skills/optional/creative/creative-impeccable) | Frontend design guidance, upstream-maintained (impeccable). | | [**kanban-video-orchestrator**](/docs/user-guide/skills/optional/creative/creative-kanban-video-orchestrator) | Plan and run multi-agent video production pipelines. | | [**meme-generation**](/docs/user-guide/skills/optional/creative/creative-meme-generation) | Create meme PNGs from templates with Pillow text overlay. | | [**pixel-art**](/docs/user-guide/skills/optional/creative/creative-pixel-art) | Pixel art w/ era palettes (NES, Game Boy, PICO-8). | -| [**simple-english**](/docs/user-guide/skills/optional/creative/creative-simple-english) | Rewrite technical text to ASD-STE100 Simplified Technical English. | +| [**pretext**](/docs/user-guide/skills/optional/creative/creative-pretext) | Build creative browser demos with DOM-free text layout. | +| [**simple-english**](/docs/user-guide/skills/optional/creative/creative-simple-english) | Rewrite text to ASD-STE100 Simplified Technical English. | +| [**sketch**](/docs/user-guide/skills/optional/creative/creative-sketch) | Throwaway HTML mockups: 2-3 design variants to compare. | | [**social-media-content-calendar**](/docs/user-guide/skills/optional/creative/creative-social-media-content-calendar) | Plan multi-platform social campaigns: briefs to posting. | | [**tldraw-offline**](/docs/user-guide/skills/optional/creative/creative-tldraw-offline) | Drive and script tldraw offline canvases with an agent. | +| [**touchdesigner-mcp**](/docs/user-guide/skills/optional/creative/creative-touchdesigner-mcp) | Control TouchDesigner via twozero MCP. | | [**unreal-mcp**](/docs/user-guide/skills/optional/creative/creative-unreal-mcp) | Automate Unreal Engine editor scenes, actors, and renders. | ## data-science @@ -153,12 +159,15 @@ hermes skills uninstall <skill-name> | [**chroma**](/docs/user-guide/skills/optional/mlops/mlops-chroma) | Embedding database for RAG and semantic search. | | [**clip**](/docs/user-guide/skills/optional/mlops/mlops-clip) | Zero-shot image classification and image-text search. | | [**dspy**](/docs/user-guide/skills/optional/mlops/mlops-research-dspy) | DSPy: declarative LM programs, auto-optimize prompts, RAG. | +| [**evaluating-llms-harness**](/docs/user-guide/skills/optional/mlops/mlops-evaluation-evaluating-llms-harness) | lm-eval-harness: benchmark LLMs (MMLU, GSM8K, etc.). | | [**faiss**](/docs/user-guide/skills/optional/mlops/mlops-faiss) | Fast vector similarity search at billion scale. | | [**flash-attention**](/docs/user-guide/skills/optional/mlops/mlops-flash-attention) | Speed up long-sequence transformer training and inference. | | [**guidance**](/docs/user-guide/skills/optional/mlops/mlops-guidance) | Constrain LLM output with grammars; guarantee valid JSON. | +| [**huggingface-hub**](/docs/user-guide/skills/optional/mlops/mlops-models-huggingface-hub) | HuggingFace hf CLI: search/download/upload models, datasets. | | [**huggingface-tokenizers**](/docs/user-guide/skills/optional/mlops/mlops-huggingface-tokenizers) | Fast BPE/WordPiece tokenization and custom vocab training. | | [**instructor**](/docs/user-guide/skills/optional/mlops/mlops-instructor) | Structured LLM outputs validated with Pydantic. | | [**lambda-labs**](/docs/user-guide/skills/optional/mlops/mlops-lambda-labs) | On-demand GPU cloud instances for ML training. | +| [**llama-cpp**](/docs/user-guide/skills/optional/mlops/mlops-inference-llama-cpp) | llama.cpp local GGUF inference + HF Hub model discovery. | | [**llava**](/docs/user-guide/skills/optional/mlops/mlops-llava) | Vision-language chat: VQA, captioning, image dialogue. | | [**modal**](/docs/user-guide/skills/optional/mlops/mlops-modal) | Serverless GPU cloud for ML jobs and model APIs. | | [**nemo-curator**](/docs/user-guide/skills/optional/mlops/mlops-nemo-curator) | Curate LLM training data: dedupe, filter, PII redaction. | @@ -171,6 +180,7 @@ hermes skills uninstall <skill-name> | [**qdrant**](/docs/user-guide/skills/optional/mlops/mlops-qdrant) | Vector search engine for production RAG systems. | | [**saelens**](/docs/user-guide/skills/optional/mlops/mlops-saelens) | Train sparse autoencoders to interpret model features. | | [**segment-anything-model**](/docs/user-guide/skills/optional/mlops/mlops-models-segment-anything-model) | SAM: zero-shot image segmentation via points, boxes, masks. | +| [**serving-llms-vllm**](/docs/user-guide/skills/optional/mlops/mlops-inference-serving-llms-vllm) | vLLM: high-throughput LLM serving, OpenAI API, quantization. | | [**simpo**](/docs/user-guide/skills/optional/mlops/mlops-simpo) | Reference-free preference alignment, simpler than DPO. | | [**slime**](/docs/user-guide/skills/optional/mlops/mlops-slime) | RL post-training for LLMs with Megatron and SGLang. | | [**stable-diffusion**](/docs/user-guide/skills/optional/mlops/mlops-stable-diffusion) | Text-to-image generation, inpainting, and img2img. | @@ -178,6 +188,7 @@ hermes skills uninstall <skill-name> | [**torchtitan**](/docs/user-guide/skills/optional/mlops/mlops-torchtitan) | Pretrain LLMs at scale with PyTorch 4D parallelism. | | [**trl-fine-tuning**](/docs/user-guide/skills/optional/mlops/mlops-training-trl-fine-tuning) | TRL: SFT, DPO, GRPO, RLOO reward modeling for LLM RLHF. | | [**unsloth**](/docs/user-guide/skills/optional/mlops/mlops-training-unsloth) | Unsloth: 2-5x faster LoRA/QLoRA fine-tuning, less VRAM. | +| [**weights-and-biases**](/docs/user-guide/skills/optional/mlops/mlops-evaluation-weights-and-biases) | W&B: log ML experiments, sweeps, model registry, dashboards. | | [**whisper**](/docs/user-guide/skills/optional/mlops/mlops-whisper) | Transcribe and translate speech in 99 languages. | ## payments @@ -206,6 +217,7 @@ hermes skills uninstall <skill-name> | Skill | Description | |-------|-------------| | [**bioinformatics**](/docs/user-guide/skills/optional/research/research-bioinformatics) | Gateway to 400+ genomics and computational biology skills. | +| [**blogwatcher**](/docs/user-guide/skills/optional/research/research-blogwatcher) | Monitor blogs and RSS/Atom feeds via blogwatcher-cli tool. | | [**darwinian-evolver**](/docs/user-guide/skills/optional/research/research-darwinian-evolver) | Evolve prompts/regex/SQL/code with Imbue's evolution loop. | | [**domain-intel**](/docs/user-guide/skills/optional/research/research-domain-intel) | Passive recon of subdomains, SSL certs, WHOIS, and DNS. | | [**drug-discovery**](/docs/user-guide/skills/optional/research/research-drug-discovery) | Drug discovery: ChEMBL search, drug-likeness, interactions. | @@ -215,6 +227,7 @@ hermes skills uninstall <skill-name> | [**parallel-cli**](/docs/user-guide/skills/optional/research/research-parallel-cli) | Agent-native web search, deep research, and enrichment. | | [**pinecone-research**](/docs/user-guide/skills/optional/research/research-pinecone-research) | Agent RAG and long-term memory with Pinecone. | | [**qmd**](/docs/user-guide/skills/optional/research/research-qmd) | Hybrid local search over notes, docs, and transcripts. | +| [**research-paper-writing**](/docs/user-guide/skills/optional/research/research-research-paper-writing) | Write ML papers for NeurIPS/ICML/ICLR: design→submit. | | [**scrapling**](/docs/user-guide/skills/optional/research/research-scrapling) | Scrape sites with stealth browsing and Cloudflare bypass. | | [**searxng-search**](/docs/user-guide/skills/optional/research/research-searxng-search) | Free keyless meta-search aggregating 70+ engines. | @@ -229,10 +242,17 @@ hermes skills uninstall <skill-name> | [**unbroker**](/docs/user-guide/skills/optional/security/security-unbroker) | Autonomously remove your info from data-broker sites. | | [**web-pentest**](/docs/user-guide/skills/optional/security/security-web-pentest) | Authorized web pentest: recon, proof-based exploits, report. | +## smart-home + +| Skill | Description | +|-------|-------------| +| [**openhue**](/docs/user-guide/skills/optional/smart-home/smart-home-openhue) | Control Philips Hue lights, scenes, rooms via OpenHue CLI. | + ## software-development | Skill | Description | |-------|-------------| +| [**ast-grep**](/docs/user-guide/skills/optional/software-development/software-development-ast-grep) | AST-aware structural code search and rewrite via ast-grep. | | [**code-wiki**](/docs/user-guide/skills/optional/software-development/software-development-code-wiki) | Generate wiki docs + Mermaid diagrams for any codebase. | | [**grill-me**](/docs/user-guide/skills/optional/software-development/software-development-grill-me) | Adversarial plan interview before implementation. | | [**rest-graphql-debug**](/docs/user-guide/skills/optional/software-development/software-development-rest-graphql-debug) | Debug REST/GraphQL APIs: status codes, auth, schemas, repro. | @@ -243,6 +263,7 @@ hermes skills uninstall <skill-name> | Skill | Description | |-------|-------------| | [**cloudflare-temporary-deploy**](/docs/user-guide/skills/optional/web-development/web-development-cloudflare-temporary-deploy) | Deploy a Worker live, no account, via wrangler --temporary. | +| [**har-derived-api-client**](/docs/user-guide/skills/optional/web-development/web-development-har-derived-api-client) | Record a site's XHR into a HAR, derive an HTTP client. | | [**page-agent**](/docs/user-guide/skills/optional/web-development/web-development-page-agent) | Embed an in-page natural-language GUI copilot in web apps. | | [**publish-site**](/docs/user-guide/skills/optional/web-development/web-development-publish-site) | Versioned site deploys to GitHub/Cloudflare/Netlify Pages. | diff --git a/website/docs/reference/skills-catalog.md b/website/docs/reference/skills-catalog.md index a5bf58c88b..b6ab7f5c21 100644 --- a/website/docs/reference/skills-catalog.md +++ b/website/docs/reference/skills-catalog.md @@ -16,142 +16,117 @@ If a skill is missing from this list but present in the repo, the catalog is reg | Skill | Description | Path | |-------|-------------|------| -| [`apple-notes`](/docs/user-guide/skills/bundled/apple/apple-apple-notes) | Manage Apple Notes via memo CLI: create, search, edit. | `apple/apple-notes` | -| [`apple-reminders`](/docs/user-guide/skills/bundled/apple/apple-apple-reminders) | Apple Reminders via remindctl: add, list, complete. | `apple/apple-reminders` | -| [`findmy`](/docs/user-guide/skills/bundled/apple/apple-findmy) | Track Apple devices/AirTags via FindMy.app on macOS. | `apple/findmy` | -| [`imessage`](/docs/user-guide/skills/bundled/apple/apple-imessage) | Send and receive iMessages/SMS via the imsg CLI on macOS. | `apple/imessage` | +| [`apple-notes`](/docs/user-guide/skills/bundled/apple/apple-apple-notes) | Manage Apple Notes via memo CLI: create, search, edit. | `apple\apple-notes` | +| [`apple-reminders`](/docs/user-guide/skills/bundled/apple/apple-apple-reminders) | Apple Reminders via remindctl: add, list, complete. | `apple\apple-reminders` | +| [`findmy`](/docs/user-guide/skills/bundled/apple/apple-findmy) | Track Apple devices/AirTags via FindMy.app on macOS. | `apple\findmy` | +| [`imessage`](/docs/user-guide/skills/bundled/apple/apple-imessage) | Send and receive iMessages/SMS via the imsg CLI on macOS. | `apple\imessage` | ## autonomous-ai-agents | Skill | Description | Path | |-------|-------------|------| -| [`claude-code`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code) | Delegate coding to Claude Code CLI (features, PRs). | `autonomous-ai-agents/claude-code` | -| [`codex`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex) | Delegate coding to OpenAI Codex CLI (features, PRs). | `autonomous-ai-agents/codex` | -| [`computer-use`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-computer-use) | Drive the desktop in the background without stealing focus. | `autonomous-ai-agents/computer-use` | -| [`hermes-agent`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent) | Use, configure, theme, extend, and orchestrate Hermes Agent. | `autonomous-ai-agents/hermes-agent` | -| [`opencode`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-opencode) | Delegate coding to OpenCode CLI (features, PR review). | `autonomous-ai-agents/opencode` | +| [`claude-code`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code) | Delegate coding to Claude Code CLI (features, PRs). | `autonomous-ai-agents\claude-code` | +| [`codex`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex) | Delegate coding to OpenAI Codex CLI (features, PRs). | `autonomous-ai-agents\codex` | +| [`computer-use`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-computer-use) | Drive the desktop background-first; escalate on signal. | `autonomous-ai-agents\computer-use` | +| [`hermes-agent`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent) | Use, configure, theme, extend, and orchestrate Hermes Agent. | `autonomous-ai-agents\hermes-agent` | +| [`merge-reconciler`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-merge-reconciler) | Neutral third-party resolution of agent merge conflicts. | `autonomous-ai-agents\merge-reconciler` | +| [`opencode`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-opencode) | Delegate coding to OpenCode CLI (features, PR review). | `autonomous-ai-agents\opencode` | ## creative | Skill | Description | Path | |-------|-------------|------| -| [`architecture-diagram`](/docs/user-guide/skills/bundled/creative/creative-architecture-diagram) | Dark-themed SVG architecture/cloud/infra diagrams as HTML. | `creative/architecture-diagram` | -| [`ascii-art`](/docs/user-guide/skills/bundled/creative/creative-ascii-art) | ASCII art: pyfiglet, cowsay, boxes, image-to-ascii. | `creative/ascii-art` | -| [`ascii-video`](/docs/user-guide/skills/bundled/creative/creative-ascii-video) | ASCII video: convert video/audio to colored ASCII MP4/GIF. | `creative/ascii-video` | -| [`baoyu-infographic`](/docs/user-guide/skills/bundled/creative/creative-baoyu-infographic) | Infographics: 21 layouts x 21 styles (信息图, 可视化). | `creative/baoyu-infographic` | -| [`claude-design`](/docs/user-guide/skills/bundled/creative/creative-claude-design) | Design one-off HTML artifacts (landing, deck, prototype). | `creative/claude-design` | -| [`comfyui`](/docs/user-guide/skills/bundled/creative/creative-comfyui) | Generate images, video, and audio via diffusion workflows. | `creative/comfyui` | -| [`design-md`](/docs/user-guide/skills/bundled/creative/creative-design-md) | Author/validate/export Google's DESIGN.md token spec files. | `creative/design-md` | -| [`excalidraw`](/docs/user-guide/skills/bundled/creative/creative-excalidraw) | Hand-drawn Excalidraw JSON diagrams (arch, flow, seq). | `creative/excalidraw` | -| [`humanizer`](/docs/user-guide/skills/bundled/creative/creative-humanizer) | Humanize text: strip AI-isms and add real voice. | `creative/humanizer` | -| [`manim-video`](/docs/user-guide/skills/bundled/creative/creative-manim-video) | Manim CE animations: 3Blue1Brown math/algo videos. | `creative/manim-video` | -| [`p5js`](/docs/user-guide/skills/bundled/creative/creative-p5js) | p5.js sketches: gen art, shaders, interactive, 3D. | `creative/p5js` | -| [`popular-web-designs`](/docs/user-guide/skills/bundled/creative/creative-popular-web-designs) | 54 real design systems (Stripe, Linear, Vercel) as HTML/CSS. | `creative/popular-web-designs` | -| [`pretext`](/docs/user-guide/skills/bundled/creative/creative-pretext) | Build creative browser demos with DOM-free text layout. | `creative/pretext` | -| [`sketch`](/docs/user-guide/skills/bundled/creative/creative-sketch) | Throwaway HTML mockups: 2-3 design variants to compare. | `creative/sketch` | -| [`songwriting-and-ai-music`](/docs/user-guide/skills/bundled/creative/creative-songwriting-and-ai-music) | Songwriting craft and Suno AI music prompts. | `creative/songwriting-and-ai-music` | -| [`touchdesigner-mcp`](/docs/user-guide/skills/bundled/creative/creative-touchdesigner-mcp) | Control TouchDesigner via twozero MCP. | `creative/touchdesigner-mcp` | +| [`architecture-diagram`](/docs/user-guide/skills/bundled/creative/creative-architecture-diagram) | Dark-themed SVG architecture/cloud/infra diagrams as HTML. | `creative\architecture-diagram` | +| [`ascii-video`](/docs/user-guide/skills/bundled/creative/creative-ascii-video) | ASCII video: convert video/audio to colored ASCII MP4/GIF. | `creative\ascii-video` | +| [`baoyu-infographic`](/docs/user-guide/skills/bundled/creative/creative-baoyu-infographic) | Infographics: 21 layouts x 21 styles (信息图, 可视化). | `creative\baoyu-infographic` | +| [`claude-design`](/docs/user-guide/skills/bundled/creative/creative-claude-design) | Design one-off HTML artifacts (landing, deck, prototype). | `creative\claude-design` | +| [`design-md`](/docs/user-guide/skills/bundled/creative/creative-design-md) | Author/validate/export Google's DESIGN.md token spec files. | `creative\design-md` | +| [`humanizer`](/docs/user-guide/skills/bundled/creative/creative-humanizer) | Humanize text: strip AI-isms and add real voice. | `creative\humanizer` | +| [`manim-video`](/docs/user-guide/skills/bundled/creative/creative-manim-video) | Manim CE animations: 3Blue1Brown math/algo videos. | `creative\manim-video` | +| [`p5js`](/docs/user-guide/skills/bundled/creative/creative-p5js) | p5.js sketches: gen art, shaders, interactive, 3D. | `creative\p5js` | +| [`popular-web-designs`](/docs/user-guide/skills/bundled/creative/creative-popular-web-designs) | 54 real design systems (Stripe, Linear, Vercel) as HTML/CSS. | `creative\popular-web-designs` | +| [`songwriting-and-ai-music`](/docs/user-guide/skills/bundled/creative/creative-songwriting-and-ai-music) | Songwriting craft and Suno AI music prompts. | `creative\songwriting-and-ai-music` | + +## devops + +| Skill | Description | Path | +|-------|-------------|------| +| [`sdlc-review`](/docs/user-guide/skills/bundled/devops/devops-sdlc-review) | Review Kanban handoffs and route verified outcomes. | `devops\sdlc-review` | ## email | Skill | Description | Path | |-------|-------------|------| -| [`email-inbox-triage`](/docs/user-guide/skills/bundled/email/email-email-inbox-triage) | Triage an inbox: prioritize threads, draft replies safely. | `email/email-inbox-triage` | -| [`himalaya`](/docs/user-guide/skills/bundled/email/email-himalaya) | Himalaya CLI: IMAP/SMTP email from terminal. | `email/himalaya` | - -## github - -| Skill | Description | Path | -|-------|-------------|------| -| [`codebase-inspection`](/docs/user-guide/skills/bundled/github/github-codebase-inspection) | Inspect codebases w/ pygount: LOC, languages, ratios. | `github/codebase-inspection` | -| [`github-auth`](/docs/user-guide/skills/bundled/github/github-github-auth) | GitHub auth setup: HTTPS tokens, SSH keys, gh CLI login. | `github/github-auth` | -| [`github-code-review`](/docs/user-guide/skills/bundled/github/github-github-code-review) | Review PRs: diffs, inline comments via gh or REST. | `github/github-code-review` | -| [`github-issue-to-pr`](/docs/user-guide/skills/bundled/github/github-github-issue-to-pr) | Carry a GitHub issue to a verified PR with honest CI state. | `github/github-issue-to-pr` | -| [`github-issues`](/docs/user-guide/skills/bundled/github/github-github-issues) | Create, triage, label, assign GitHub issues via gh or REST. | `github/github-issues` | -| [`github-pr-workflow`](/docs/user-guide/skills/bundled/github/github-github-pr-workflow) | GitHub PR lifecycle: branch, commit, open, CI, merge. | `github/github-pr-workflow` | -| [`github-repo-management`](/docs/user-guide/skills/bundled/github/github-github-repo-management) | Clone/create/fork repos; manage remotes, releases. | `github/github-repo-management` | +| [`email-inbox-triage`](/docs/user-guide/skills/bundled/email/email-email-inbox-triage) | Triage an inbox: prioritize threads, draft replies safely. | `email\email-inbox-triage` | +| [`himalaya`](/docs/user-guide/skills/bundled/email/email-himalaya) | Himalaya CLI: IMAP/SMTP email from terminal. | `email\himalaya` | ## media | Skill | Description | Path | |-------|-------------|------| -| [`gif-search`](/docs/user-guide/skills/bundled/media/media-gif-search) | Search/download GIFs from Tenor via curl + jq. | `media/gif-search` | -| [`songsee`](/docs/user-guide/skills/bundled/media/media-songsee) | Audio spectrograms/features (mel, chroma, MFCC) via CLI. | `media/songsee` | -| [`youtube-content`](/docs/user-guide/skills/bundled/media/media-youtube-content) | YouTube transcripts to summaries, threads, blogs. | `media/youtube-content` | - -## mlops - -| Skill | Description | Path | -|-------|-------------|------| -| [`evaluating-llms-harness`](/docs/user-guide/skills/bundled/mlops/mlops-evaluation-evaluating-llms-harness) | lm-eval-harness: benchmark LLMs (MMLU, GSM8K, etc.). | `mlops/evaluation/evaluating-llms-harness` | -| [`huggingface-hub`](/docs/user-guide/skills/bundled/mlops/mlops-huggingface-hub) | HuggingFace hf CLI: search/download/upload models, datasets. | `mlops/huggingface-hub` | -| [`llama-cpp`](/docs/user-guide/skills/bundled/mlops/mlops-inference-llama-cpp) | llama.cpp local GGUF inference + HF Hub model discovery. | `mlops/inference/llama-cpp` | -| [`serving-llms-vllm`](/docs/user-guide/skills/bundled/mlops/mlops-inference-serving-llms-vllm) | vLLM: high-throughput LLM serving, OpenAI API, quantization. | `mlops/inference/serving-llms-vllm` | -| [`weights-and-biases`](/docs/user-guide/skills/bundled/mlops/mlops-evaluation-weights-and-biases) | W&B: log ML experiments, sweeps, model registry, dashboards. | `mlops/evaluation/weights-and-biases` | +| [`gif-search`](/docs/user-guide/skills/bundled/media/media-gif-search) | Search/download GIFs from Tenor via curl + jq. | `media\gif-search` | +| [`songsee`](/docs/user-guide/skills/bundled/media/media-songsee) | Audio spectrograms/features (mel, chroma, MFCC) via CLI. | `media\songsee` | +| [`youtube-content`](/docs/user-guide/skills/bundled/media/media-youtube-content) | YouTube transcripts to summaries, threads, blogs. | `media\youtube-content` | ## note-taking | Skill | Description | Path | |-------|-------------|------| -| [`obsidian`](/docs/user-guide/skills/bundled/note-taking/note-taking-obsidian) | Read, search, create, and edit notes in the Obsidian vault. | `note-taking/obsidian` | +| [`obsidian`](/docs/user-guide/skills/bundled/note-taking/note-taking-obsidian) | Read, search, create, and edit notes in the Obsidian vault. | `note-taking\obsidian` | ## productivity | Skill | Description | Path | |-------|-------------|------| -| [`airtable`](/docs/user-guide/skills/bundled/productivity/productivity-airtable) | Airtable REST API via curl. Records CRUD, filters, upserts. | `productivity/airtable` | -| [`box`](/docs/user-guide/skills/bundled/productivity/productivity-box) | Box manages cloud files, sharing, search, and metadata. | `productivity/box` | -| [`document-to-action-items`](/docs/user-guide/skills/bundled/productivity/productivity-document-to-action-items) | Extract cited obligations, deadlines, tasks from documents. | `productivity/document-to-action-items` | -| [`docx`](/docs/user-guide/skills/bundled/productivity/productivity-docx) | Create, read, edit, and template Word .docx files. | `productivity/docx` | -| [`google-workspace`](/docs/user-guide/skills/bundled/productivity/productivity-google-workspace) | Gmail, Calendar, Drive, Docs, Sheets via gws CLI or Python. | `productivity/google-workspace` | -| [`maps`](/docs/user-guide/skills/bundled/productivity/productivity-maps) | Geocode, POIs, routes, timezones via OpenStreetMap/OSRM. | `productivity/maps` | -| [`meeting-action-items`](/docs/user-guide/skills/bundled/productivity/productivity-meeting-action-items) | Turn meeting notes into cited decisions, owners, tickets. | `productivity/meeting-action-items` | -| [`nano-pdf`](/docs/user-guide/skills/bundled/productivity/productivity-nano-pdf) | Edit text in existing PDFs via natural-language prompts. | `productivity/nano-pdf` | -| [`notion`](/docs/user-guide/skills/bundled/productivity/productivity-notion) | Notion API + ntn CLI: pages, databases, markdown, Workers. | `productivity/notion` | -| [`ocr-and-documents`](/docs/user-guide/skills/bundled/productivity/productivity-ocr-and-documents) | Extract text from PDFs/scans (pymupdf, marker-pdf). | `productivity/ocr-and-documents` | -| [`pdf`](/docs/user-guide/skills/bundled/productivity/productivity-pdf) | Create, read, merge, fill, and secure PDF files. | `productivity/pdf` | -| [`powerpoint`](/docs/user-guide/skills/bundled/productivity/productivity-powerpoint) | Create, read, edit .pptx decks with python-pptx. | `productivity/powerpoint` | -| [`product-price-monitor`](/docs/user-guide/skills/bundled/productivity/productivity-product-price-monitor) | Watch product, flight, or listing prices; alert on target. | `productivity/product-price-monitor` | -| [`session-librarian`](/docs/user-guide/skills/bundled/productivity/productivity-session-librarian) | Organize sessions by prompt: find, rename, archive, prune. | `productivity/session-librarian` | -| [`teams-meeting-pipeline`](/docs/user-guide/skills/bundled/productivity/productivity-teams-meeting-pipeline) | Teams meeting summaries, job replay, Graph subscriptions. | `productivity/teams-meeting-pipeline` | -| [`weekly-review-planning`](/docs/user-guide/skills/bundled/productivity/productivity-weekly-review-planning) | Weekly reset: commitments, stalled work, next-week plan. | `productivity/weekly-review-planning` | -| [`xlsx`](/docs/user-guide/skills/bundled/productivity/productivity-xlsx) | Create, read, edit Excel .xlsx workbooks and CSVs. | `productivity/xlsx` | +| [`airtable`](/docs/user-guide/skills/bundled/productivity/productivity-airtable) | Airtable REST API via curl. Records CRUD, filters, upserts. | `productivity\airtable` | +| [`box`](/docs/user-guide/skills/bundled/productivity/productivity-box) | Box manages cloud files, sharing, search, and metadata. | `productivity\box` | +| [`document-to-action-items`](/docs/user-guide/skills/bundled/productivity/productivity-document-to-action-items) | Extract cited obligations, deadlines, tasks from documents. | `productivity\document-to-action-items` | +| [`docx`](/docs/user-guide/skills/bundled/productivity/productivity-docx) | Create, read, edit, template, and review Word .docx files. | `productivity\docx` | +| [`google-workspace`](/docs/user-guide/skills/bundled/productivity/productivity-google-workspace) | Gmail, Calendar, Drive, Docs, Sheets via gws CLI or Python. | `productivity\google-workspace` | +| [`maps`](/docs/user-guide/skills/bundled/productivity/productivity-maps) | Geocode, POIs, routes, timezones via OpenStreetMap/OSRM. | `productivity\maps` | +| [`meeting-action-items`](/docs/user-guide/skills/bundled/productivity/productivity-meeting-action-items) | Turn meeting notes into cited decisions, owners, tickets. | `productivity\meeting-action-items` | +| [`notion`](/docs/user-guide/skills/bundled/productivity/productivity-notion) | Notion API + ntn CLI: pages, databases, markdown, Workers. | `productivity\notion` | +| [`pdf`](/docs/user-guide/skills/bundled/productivity/productivity-pdf) | PDF files: create, read, merge, fill, OCR, edit text. | `productivity\pdf` | +| [`powerpoint`](/docs/user-guide/skills/bundled/productivity/productivity-powerpoint) | Create, read, edit .pptx decks with python-pptx. | `productivity\powerpoint` | +| [`product-price-monitor`](/docs/user-guide/skills/bundled/productivity/productivity-product-price-monitor) | Watch product, flight, or listing prices; alert on target. | `productivity\product-price-monitor` | +| [`teams-meeting-pipeline`](/docs/user-guide/skills/bundled/productivity/productivity-teams-meeting-pipeline) | Teams meeting summaries, job replay, Graph subscriptions. | `productivity\teams-meeting-pipeline` | +| [`weekly-review-planning`](/docs/user-guide/skills/bundled/productivity/productivity-weekly-review-planning) | Weekly reset: commitments, stalled work, next-week plan. | `productivity\weekly-review-planning` | +| [`xlsx`](/docs/user-guide/skills/bundled/productivity/productivity-xlsx) | Create, read, edit Excel .xlsx workbooks and CSVs. | `productivity\xlsx` | ## research | Skill | Description | Path | |-------|-------------|------| -| [`arxiv`](/docs/user-guide/skills/bundled/research/research-arxiv) | Search arXiv papers by keyword, author, category, or ID. | `research/arxiv` | -| [`blocked-page-recovery`](/docs/user-guide/skills/bundled/research/research-blocked-page-recovery) | Recover blocked/paywalled/WAF'd pages via archive snapshots and reader fallbacks. Use when web_extract or the browser hits 403/429/challenge pages, paywalls, or bot-detection interstitials. | `research/blocked-page-recovery` | -| [`blogwatcher`](/docs/user-guide/skills/bundled/research/research-blogwatcher) | Monitor blogs and RSS/Atom feeds via blogwatcher-cli tool. | `research/blogwatcher` | -| [`competitor-news-monitor`](/docs/user-guide/skills/bundled/research/research-competitor-news-monitor) | Watch named companies for material news; cited digests. | `research/competitor-news-monitor` | -| [`grounded-citations`](/docs/user-guide/skills/bundled/research/research-grounded-citations) | Ground answers and documents in cited, verifiable sources. | `research/grounded-citations` | -| [`llm-wiki`](/docs/user-guide/skills/bundled/research/research-llm-wiki) | Karpathy's LLM Wiki: build/query interlinked markdown KB. | `research/llm-wiki` | -| [`research-paper-writing`](/docs/user-guide/skills/bundled/research/research-research-paper-writing) | Write ML papers for NeurIPS/ICML/ICLR: design→submit. | `research/research-paper-writing` | - -## smart-home - -| Skill | Description | Path | -|-------|-------------|------| -| [`openhue`](/docs/user-guide/skills/bundled/smart-home/smart-home-openhue) | Control Philips Hue lights, scenes, rooms via OpenHue CLI. | `smart-home/openhue` | +| [`arxiv`](/docs/user-guide/skills/bundled/research/research-arxiv) | Search arXiv papers by keyword, author, category, or ID. | `research\arxiv` | +| [`competitor-news-monitor`](/docs/user-guide/skills/bundled/research/research-competitor-news-monitor) | Watch named companies for material news; cited digests. | `research\competitor-news-monitor` | +| [`grounded-citations`](/docs/user-guide/skills/bundled/research/research-grounded-citations) | Ground answers and documents in cited, verifiable sources. | `research\grounded-citations` | +| [`llm-wiki`](/docs/user-guide/skills/bundled/research/research-llm-wiki) | Karpathy's LLM Wiki: build/query interlinked markdown KB. | `research\llm-wiki` | ## social-media | Skill | Description | Path | |-------|-------------|------| -| [`xurl`](/docs/user-guide/skills/bundled/social-media/social-media-xurl) | X/Twitter via xurl CLI: raw post search, posting, DM, media. | `social-media/xurl` | +| [`xurl`](/docs/user-guide/skills/bundled/social-media/social-media-xurl) | X/Twitter via xurl CLI: raw post search, posting, DM, media. | `social-media\xurl` | ## software-development | Skill | Description | Path | |-------|-------------|------| -| [`dogfood`](/docs/user-guide/skills/bundled/software-development/software-development-dogfood) | Exploratory QA of web apps: find bugs, evidence, reports. | `software-development/dogfood` | -| [`hermes-agent-skill-authoring`](/docs/user-guide/skills/bundled/software-development/software-development-hermes-agent-skill-authoring) | Author in-repo SKILL.md files: frontmatter and structure. | `software-development/hermes-agent-skill-authoring` | -| [`inspecting-hermes-desktop-dom`](/docs/user-guide/skills/bundled/software-development/software-development-inspecting-hermes-desktop-dom) | Read the live Hermes desktop DOM/CSS over CDP. | `software-development/inspecting-hermes-desktop-dom` | -| [`node-inspect-debugger`](/docs/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger) | Debug Node.js via --inspect + Chrome DevTools Protocol CLI. | `software-development/node-inspect-debugger` | -| [`python-debugpy`](/docs/user-guide/skills/bundled/software-development/software-development-python-debugpy) | Debug Python: pdb REPL + debugpy remote (DAP). | `software-development/python-debugpy` | -| [`requesting-code-review`](/docs/user-guide/skills/bundled/software-development/software-development-requesting-code-review) | Pre-commit review: security scan, quality gates, auto-fix. | `software-development/requesting-code-review` | -| [`simplify-code`](/docs/user-guide/skills/bundled/software-development/software-development-simplify-code) | Parallel 4-agent cleanup of recent code changes. | `software-development/simplify-code` | -| [`spike`](/docs/user-guide/skills/bundled/software-development/software-development-spike) | Throwaway experiments to validate an idea before build. | `software-development/spike` | -| [`systematic-debugging`](/docs/user-guide/skills/bundled/software-development/software-development-systematic-debugging) | 4-phase root cause debugging: understand bugs before fixing. | `software-development/systematic-debugging` | -| [`test-driven-development`](/docs/user-guide/skills/bundled/software-development/software-development-test-driven-development) | TDD: enforce RED-GREEN-REFACTOR, tests before code. | `software-development/test-driven-development` | +| [`codebase-inspection`](/docs/user-guide/skills/bundled/software-development/software-development-codebase-inspection) | Inspect codebases w/ pygount: LOC, languages, ratios. | `software-development\codebase-inspection` | +| [`dogfood`](/docs/user-guide/skills/bundled/software-development/software-development-dogfood) | Exploratory QA of web apps: find bugs, evidence, reports. | `software-development\dogfood` | +| [`github`](/docs/user-guide/skills/bundled/software-development/software-development-github) | GitHub via gh CLI: PRs, issues, reviews, repos, auth. | `software-development\github` | +| [`hermes-agent-skill-authoring`](/docs/user-guide/skills/bundled/software-development/software-development-hermes-agent-skill-authoring) | Author in-repo SKILL.md files: frontmatter and structure. | `software-development\hermes-agent-skill-authoring` | +| [`inspecting-hermes-desktop-dom`](/docs/user-guide/skills/bundled/software-development/software-development-inspecting-hermes-desktop-dom) | Read the live Hermes desktop DOM/CSS over CDP. | `software-development\inspecting-hermes-desktop-dom` | +| [`node-inspect-debugger`](/docs/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger) | Debug Node.js via --inspect + Chrome DevTools Protocol CLI. | `software-development\node-inspect-debugger` | +| [`python-debugpy`](/docs/user-guide/skills/bundled/software-development/software-development-python-debugpy) | Debug Python: pdb REPL + debugpy remote (DAP). | `software-development\python-debugpy` | +| [`requesting-code-review`](/docs/user-guide/skills/bundled/software-development/software-development-requesting-code-review) | Pre-commit review: security scan, quality gates, auto-fix. | `software-development\requesting-code-review` | +| [`simplify-code`](/docs/user-guide/skills/bundled/software-development/software-development-simplify-code) | Parallel 4-agent cleanup of recent code changes. | `software-development\simplify-code` | +| [`spike`](/docs/user-guide/skills/bundled/software-development/software-development-spike) | Throwaway experiments to validate an idea before build. | `software-development\spike` | +| [`systematic-debugging`](/docs/user-guide/skills/bundled/software-development/software-development-systematic-debugging) | 4-phase root cause debugging: understand bugs before fixing. | `software-development\systematic-debugging` | +| [`test-driven-development`](/docs/user-guide/skills/bundled/software-development/software-development-test-driven-development) | TDD: enforce RED-GREEN-REFACTOR, tests before code. | `software-development\test-driven-development` | + +## web + +| Skill | Description | Path | +|-------|-------------|------| +| [`blocked-page-recovery`](/docs/user-guide/skills/bundled/web/web-blocked-page-recovery) | Use when a fetch fails: 403/429, paywall, WAF, bot wall. | `web\blocked-page-recovery` | diff --git a/website/docs/user-guide/skills/bundled/apple/apple-apple-notes.md b/website/docs/user-guide/skills/bundled/apple/apple-apple-notes.md index ac3ecdfff6..31587b5e9f 100644 --- a/website/docs/user-guide/skills/bundled/apple/apple-apple-notes.md +++ b/website/docs/user-guide/skills/bundled/apple/apple-apple-notes.md @@ -15,7 +15,7 @@ Manage Apple Notes via memo CLI: create, search, edit. | | | |---|---| | Source | Bundled (installed by default) | -| Path | `skills/apple/apple-notes` | +| Path | `skills/apple\apple-notes` | | Version | `1.0.1` | | Author | Hermes Agent | | License | MIT | diff --git a/website/docs/user-guide/skills/bundled/apple/apple-apple-reminders.md b/website/docs/user-guide/skills/bundled/apple/apple-apple-reminders.md index 9ab15d6b54..d3aa2e1e8b 100644 --- a/website/docs/user-guide/skills/bundled/apple/apple-apple-reminders.md +++ b/website/docs/user-guide/skills/bundled/apple/apple-apple-reminders.md @@ -15,7 +15,7 @@ Apple Reminders via remindctl: add, list, complete. | | | |---|---| | Source | Bundled (installed by default) | -| Path | `skills/apple/apple-reminders` | +| Path | `skills/apple\apple-reminders` | | Version | `1.0.0` | | Author | Hermes Agent | | License | MIT | diff --git a/website/docs/user-guide/skills/bundled/apple/apple-findmy.md b/website/docs/user-guide/skills/bundled/apple/apple-findmy.md index 0d4647e447..6637f08a9d 100644 --- a/website/docs/user-guide/skills/bundled/apple/apple-findmy.md +++ b/website/docs/user-guide/skills/bundled/apple/apple-findmy.md @@ -15,7 +15,7 @@ Track Apple devices/AirTags via FindMy.app on macOS. | | | |---|---| | Source | Bundled (installed by default) | -| Path | `skills/apple/findmy` | +| Path | `skills/apple\findmy` | | Version | `1.0.0` | | Author | Hermes Agent | | License | MIT | diff --git a/website/docs/user-guide/skills/bundled/apple/apple-imessage.md b/website/docs/user-guide/skills/bundled/apple/apple-imessage.md index d29fab6ebc..0b84453616 100644 --- a/website/docs/user-guide/skills/bundled/apple/apple-imessage.md +++ b/website/docs/user-guide/skills/bundled/apple/apple-imessage.md @@ -15,7 +15,7 @@ Send and receive iMessages/SMS via the imsg CLI on macOS. | | | |---|---| | Source | Bundled (installed by default) | -| Path | `skills/apple/imessage` | +| Path | `skills/apple\imessage` | | Version | `1.0.0` | | Author | Hermes Agent | | License | MIT | diff --git a/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code.md b/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code.md index 4310d1b074..a46b7045de 100644 --- a/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code.md +++ b/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code.md @@ -15,7 +15,7 @@ Delegate coding to Claude Code CLI (features, PRs). | | | |---|---| | Source | Bundled (installed by default) | -| Path | `skills/autonomous-ai-agents/claude-code` | +| Path | `skills/autonomous-ai-agents\claude-code` | | Version | `2.2.1` | | Author | Hermes Agent + Teknium | | License | MIT | @@ -230,7 +230,7 @@ Parse `structured_output` from the JSON result. Claude validates output against terminal(command="claude -p 'Start refactoring the database layer' --output-format json --max-turns 10 > /tmp/session.json", workdir="/project", timeout=180) # Resume with session ID -terminal(command="claude -p 'Continue and add connection pooling' --resume $(cat /tmp/session.json | python3 -c 'import json,sys; print(json.load(sys.stdin)[\"session_id\"])') --max-turns 5", workdir="/project", timeout=120) +terminal(command="claude -p 'Continue and add connection pooling' --resume $(cat /tmp/session.json | python -c 'import json,sys; print(json.load(sys.stdin)[\"session_id\"])') --max-turns 5", workdir="/project", timeout=120) # Or resume the most recent session in the same directory terminal(command="claude -p 'What did you do last time?' --continue --max-turns 1", workdir="/project", timeout=30) @@ -740,7 +740,7 @@ Use `/context` in interactive mode to see a colored grid of context usage. Key t 2. **`--dangerously-skip-permissions` dialog defaults to "No, exit"** — you must send Down then Enter to accept. Print mode (`-p`) skips this entirely. 3. **`--max-budget-usd` minimum is ~$0.05** — system prompt cache creation alone costs this much. Setting lower will error immediately. 4. **`--max-turns` is print-mode only** — ignored in interactive sessions. -5. **Claude may use `python` instead of `python3`** — on systems without a `python` symlink, Claude's bash commands will fail on first try but it self-corrects. +5. **Claude may use `python` instead of `python`** — on systems without a `python` symlink, Claude's bash commands will fail on first try but it self-corrects. 6. **Session resumption requires same directory** — `--continue` finds the most recent session for the current working directory. 7. **`--json-schema` needs enough `--max-turns`** — Claude must read files before producing structured output, which takes multiple turns. 8. **Trust dialog only appears once per directory** — first-time only, then cached. diff --git a/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex.md b/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex.md index 503774e553..359743a65e 100644 --- a/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex.md +++ b/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex.md @@ -15,7 +15,7 @@ Delegate coding to OpenAI Codex CLI (features, PRs). | | | |---|---| | Source | Bundled (installed by default) | -| Path | `skills/autonomous-ai-agents/codex` | +| Path | `skills/autonomous-ai-agents\codex` | | Version | `1.0.1` | | Author | Hermes Agent | | License | MIT | diff --git a/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-computer-use.md b/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-computer-use.md index 0e5f22a117..e907255c2b 100644 --- a/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-computer-use.md +++ b/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-computer-use.md @@ -15,7 +15,7 @@ Drive the desktop background-first; escalate on signal. | | | |---|---| | Source | Bundled (installed by default) | -| Path | `skills/autonomous-ai-agents/computer-use` | +| Path | `skills/autonomous-ai-agents\computer-use` | | Version | `2.0.0` | | Author | Francesco Bonacci (f-trycua), Hermes Agent | | License | MIT | diff --git a/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent.md b/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent.md index ed894fba0b..6e31b32dc9 100644 --- a/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent.md +++ b/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent.md @@ -15,12 +15,12 @@ Use, configure, theme, extend, and orchestrate Hermes Agent. | | | |---|---| | Source | Bundled (installed by default) | -| Path | `skills/autonomous-ai-agents/hermes-agent` | -| Version | `3.1.0` | +| Path | `skills/autonomous-ai-agents\hermes-agent` | +| Version | `3.2.0` | | Author | Hermes Agent + Teknium | | License | MIT | | Platforms | linux, macos, windows | -| Tags | `hermes`, `setup`, `configuration`, `multi-agent`, `spawning`, `cli`, `gateway`, `themes`, `skins`, `desktop-plugins`, `tui-widgets`, `petdex`, `development` | +| Tags | `hermes`, `setup`, `configuration`, `multi-agent`, `spawning`, `cli`, `gateway`, `bots`, `bot-mode`, `features`, `themes`, `skins`, `desktop-plugins`, `tui-widgets`, `petdex`, `development` | | Related skills | [`claude-code`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code), [`codex`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex), [`opencode`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-opencode) | ## Reference: full SKILL.md @@ -51,12 +51,14 @@ What makes Hermes different: This skill is a concise operating guide, not the complete source of truth for every Hermes feature. If a Hermes feature, command, or setting is not mentioned here or in a reference, do not treat that absence as evidence that it does not exist. Check the live repository and official docs before giving a negative answer. -Good verification targets: +Good verification targets, cheapest first: +- **Every shipped feature, one line each: https://hermes-agent.nousresearch.com/docs/llms.txt.** Start here for any "can Hermes do X?" or "how do I do X?" — it indexes the entire documentation set with a link to the page that answers. It is generated from the docs tree on every build, so it is never behind the product. Fetch it with `web_extract`, or `curl -s https://hermes-agent.nousresearch.com/docs/llms.txt` when web tools are off. The whole documentation set in one file is at `/docs/llms-full.txt`. - CLI commands: `hermes --help`, `hermes <command> --help`, and `hermes_cli/main.py` -- User documentation: https://hermes-agent.nousresearch.com/docs/ - Source tree: https://github.com/NousResearch/hermes-agent +Never answer "Hermes can't do that" from memory. Hermes ships far more than this skill body describes, and the index exists so a negative answer is always checkable. + ## Quick Start ```bash @@ -103,6 +105,8 @@ Profiles use `~/.hermes/profiles/<name>/` with the same layout. When a profile i | User wants... | Load | |---|---| +| **Anything not listed below — "can Hermes do X?", "how do I set up X?"** | **https://hermes-agent.nousresearch.com/docs/llms.txt** | +| Bots that chat, run routines, or message each other; the Bots tab | docs: `/user-guide/bot-mode` | | CLI commands, subcommands, flags, "how do I run X" | `references/cli-reference.md` | | In-session slash commands | `references/slash-commands.md` | | Provider setup, API keys, OAuth | `references/providers-and-models.md` | @@ -121,6 +125,11 @@ Profiles use `~/.hermes/profiles/<name>/` with the same layout. When a profile i | Contributing code: adding tools, slash commands, tests | `references/contributor-guide.md` | | delegate_task "capped at N" reports | `references/delegate-task-concurrency-diagnosis.md` | | "Can app X use my Nous Portal subscription/OAuth?" | `references/portal-auth-for-third-party-apps.md` | +| Connecting a messaging platform (Telegram, Discord, Slack, WhatsApp, …) | docs: `/user-guide/messaging` | + +The reference list above is not the feature list — it is the set of topics that +need more than their docs page. For everything else Hermes ships, fetch +`llms.txt` and it maps the question to the page that answers it. Two theming rules that hold even without loading the reference: **you apply skins yourself** (`hermes config set display.skin <name>` — every surface repaints live within ~a second; don't tell the user to run `/skin`), and **to tweak one color, edit the ACTIVE skin** (`hermes skin set <key> <hex>`) — never fork `default`, which drops the palette and resets the background. diff --git a/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-merge-reconciler.md b/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-merge-reconciler.md new file mode 100644 index 0000000000..4cb8e1fea8 --- /dev/null +++ b/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-merge-reconciler.md @@ -0,0 +1,176 @@ +--- +title: "Merge Reconciler — Neutral third-party resolution of agent merge conflicts" +sidebar_label: "Merge Reconciler" +description: "Neutral third-party resolution of agent merge conflicts" +--- + +{/* 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. */} + +# Merge Reconciler + +Neutral third-party resolution of agent merge conflicts. + +## Skill metadata + +| | | +|---|---| +| Source | Bundled (installed by default) | +| Path | `skills/autonomous-ai-agents\merge-reconciler` | +| Version | `1.0.0` | +| Author | Hermes Agent | +| License | MIT | +| Platforms | linux, macos, windows | +| Tags | `Multi-Agent`, `Git`, `Merge-Conflict`, `Kanban`, `Arbitration` | +| Related skills | [`hermes-agent`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent) | + +## 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. +::: + +# Merge Reconciler + +Resolve a git merge conflict between two AGENTS' branches as an impartial third +party. Agents resolving conflicts against a peer's work reliably either +overwrite the peer or abandon their own change — they lack the peer's context +and are biased toward their own side. This skill is the fix: a neutral +reconciler that receives both diffs plus both sides' stated intents and +produces a merged result, like a merge-queue arbiter. + +## When to Use + +- Two agent branches/worktrees collide during a parallel campaign (kanban + engineering pipeline, parallel-PR wave, multi-worktree refactor). +- `git merge` or `git rebase` halts on conflicts between two agents' work and + neither original agent should self-adjudicate. +- Do NOT use for conflicts within a single agent's own work, or for trivial + lockfile/generated-file conflicts (regenerate those instead). + +## Prerequisites + +- A repo checkout containing the halted merge, or the two branch names plus + permission to run the merge yourself. +- Both sides' intent sources: kanban completion summaries (`terminal` running + `hermes kanban show <task-id>`), PR bodies, or at minimum each branch's + commit messages. +- The project's build/test command, if one exists. + +## How to Run + +**Standalone** — a human (or agent) invokes this skill inside the conflicted +repo: load the skill, then follow the Procedure top to bottom. + +**Spawned neutral agent** — the preferred shape in multi-agent campaigns: + +- `delegate_task`: spawn a subagent whose task message contains the repo path, + both branch names, and both sides' intent summaries verbatim, plus an + instruction to follow this skill. +- Kanban-native: create a reconciliation card assigned to a **third profile** + (not either worker's profile) with BOTH conflicted cards linked as parents — + `kanban_create(title="reconcile branch-a x branch-b", assignee="reconciler", + parents=["t_a", "t_b"])`. The parent links carry both sides' completion + summaries into the reconciler's context automatically; the card body should + name the repo path and the two branches. + +## Quick Reference + +| Hunk class | Definition | Resolution | +|---|---|---| +| disjoint-intent | The two changes serve different goals and can coexist | Combine both | +| same-question-different-answer | Both sides answered one design question differently | Pick ONE per stated intents; surface the decision | +| superseded | One side's premise no longer holds after the other's change | Keep the surviving side; note why | + +Impartiality contract: never favor the side that spawned you; touch ONLY +conflicted regions (no drive-by edits); every design-question pick must appear +explicitly in the hand-back summary. + +## Procedure + +### 1. Gather both sides + +- Run via `terminal`: `git status` (confirm the conflicted state and list + conflicted files), `git merge-base <A> <B>`, then for each side + `git log --oneline <base>..<side>` and `git diff <base>..<side> -- <file>` + for every conflicted file. In a halted merge, `HEAD` is one side and + `MERGE_HEAD` is the other. +- Collect each side's intent: `hermes kanban show <task-id>` for completion + summaries/metadata, or the PR body, or the commit messages from the log + above. Write down one sentence of intent per side before touching any file. +- Done when: you can state both intents in your own words and have both diffs + for every conflicted file. + +### 2. Classify every conflicted hunk + +- Open each conflicted file with `read_file` and locate each + `<<<<<<<`/`=======`/`>>>>>>>` block. +- Assign each hunk exactly one class from the Quick Reference table, judging + by the stated intents — not by which change looks nicer. +- If a single hunk contains multiple independent decisions (e.g., new logic + that combines cleanly PLUS a styling/rounding choice both sides answered + differently), decompose it into sub-decisions and classify each one. +- A single file often mixes classes: one hunk may be a design collision while + a neighboring hunk is disjoint. Classify per hunk, not per file. +- Done when: every hunk has a written class and a one-line rationale. + +### 3. Resolve under the impartiality contract + +- Edit each hunk with `patch` (or `write_file` for whole-file rewrites): + - disjoint-intent → merge both changes so each intent is fully served. + - same-question-different-answer → pick the answer that best serves the + STATED intents (e.g., an intent of "strict validation" beats "quick + default" if the task required correctness). Never split the difference + into a hybrid neither side asked for. + - superseded → keep the surviving side; delete the dead premise. +- Never favor the side that spawned you. If intents genuinely tie, escalate + (block the kanban card / report back) rather than guess. +- Change nothing outside conflict markers — no formatting, renames, or + opportunistic fixes. +- `git add` each resolved file via `terminal`. +- Done when: `search_files` finds no `<<<<<<<` markers in the repo and every + resolved file is staged. + +### 4. Verify + +- Run the project's build/tests via `terminal`; at minimum import/execute the + touched modules. Both intents must be observable in the merged behavior + (e.g., side A's new semantics AND side B's disjoint addition both present). +- Complete the merge: `git commit` (the default merge message plus a body + listing hunk decisions is fine). +- Done when: verification passes and the merge commit exists. + +### 5. Hand back + +- Produce a completion summary naming EVERY hunk decision: + `file:lines — class — which side(s) kept — rationale`. For every + same-question-different-answer hunk, state the design question and the + answer you picked so a human can veto it — never bury a design call. +- Kanban: `kanban_complete(summary=...)`. Standalone: print the summary. +- Done when: the summary is delivered and lists all hunks. + +## Pitfalls + +- **Self-favoring**: if you were spawned by one of the conflicting agents, + you are structurally biased — state this and weigh the other side's intent + deliberately. Prefer the third-profile shape so this never arises. +- **Splitting the difference** on a design collision produces a hybrid nobody + designed; pick one answer and surface it. +- **Per-file classification**: files usually mix hunk classes; classifying a + whole file as one class silently drops a disjoint change. +- **Drive-by edits** make the merge unreviewable and steal decisions from the + original agents. +- **Missing intents**: commit messages alone can be thin; prefer kanban + completion summaries or PR bodies. If neither side's intent is recoverable, + escalate instead of guessing. +- **Repeat offenders**: repeated conflicts on the SAME file across rounds are + a hotspot signal, not routine reconciliation work — flag it (e.g. a + `hotspot: <path> — <reason>` kanban comment) so the orchestrator decomposes + that file, rather than serially reconciling every new collision on it. + +## Verification + +- `git status` shows a clean tree on the target branch with a merge commit. +- No conflict markers remain (`search_files` pattern `<<<<<<<`). +- Build/tests pass; both sides' intents are demonstrably present or the + dropped one is explicitly named in the summary. +- The hand-back summary enumerates every hunk with class and rationale. diff --git a/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-opencode.md b/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-opencode.md index 37c6c1d15d..e8a027d382 100644 --- a/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-opencode.md +++ b/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-opencode.md @@ -15,7 +15,7 @@ Delegate coding to OpenCode CLI (features, PR review). | | | |---|---| | Source | Bundled (installed by default) | -| Path | `skills/autonomous-ai-agents/opencode` | +| Path | `skills/autonomous-ai-agents\opencode` | | Version | `1.2.0` | | Author | Hermes Agent | | License | MIT | diff --git a/website/docs/user-guide/skills/bundled/creative/creative-architecture-diagram.md b/website/docs/user-guide/skills/bundled/creative/creative-architecture-diagram.md index ad816a370a..a4bf8cfc18 100644 --- a/website/docs/user-guide/skills/bundled/creative/creative-architecture-diagram.md +++ b/website/docs/user-guide/skills/bundled/creative/creative-architecture-diagram.md @@ -15,13 +15,13 @@ Dark-themed SVG architecture/cloud/infra diagrams as HTML. | | | |---|---| | Source | Bundled (installed by default) | -| Path | `skills/creative/architecture-diagram` | +| Path | `skills/creative\architecture-diagram` | | Version | `1.0.0` | | Author | Cocoon AI (hello@cocoon-ai.com), ported by Hermes Agent | | License | MIT | | Platforms | linux, macos, windows | | Tags | `architecture`, `diagrams`, `SVG`, `HTML`, `visualization`, `infrastructure`, `cloud` | -| Related skills | [`concept-diagrams`](/docs/user-guide/skills/optional/creative/creative-concept-diagrams), [`excalidraw`](/docs/user-guide/skills/bundled/creative/creative-excalidraw) | +| Related skills | [`concept-diagrams`](/docs/user-guide/skills/optional/creative/creative-concept-diagrams), [`excalidraw`](/docs/user-guide/skills/optional/creative/creative-excalidraw) | ## Reference: full SKILL.md diff --git a/website/docs/user-guide/skills/bundled/creative/creative-ascii-video.md b/website/docs/user-guide/skills/bundled/creative/creative-ascii-video.md index 73eb134110..0a4214bdb8 100644 --- a/website/docs/user-guide/skills/bundled/creative/creative-ascii-video.md +++ b/website/docs/user-guide/skills/bundled/creative/creative-ascii-video.md @@ -15,7 +15,7 @@ ASCII video: convert video/audio to colored ASCII MP4/GIF. | | | |---|---| | Source | Bundled (installed by default) | -| Path | `skills/creative/ascii-video` | +| Path | `skills/creative\ascii-video` | | Version | `1.0.0` | | Author | SHL0MS, Hermes Agent | | License | MIT | diff --git a/website/docs/user-guide/skills/bundled/creative/creative-baoyu-infographic.md b/website/docs/user-guide/skills/bundled/creative/creative-baoyu-infographic.md index e915f2ce63..fc09379e3e 100644 --- a/website/docs/user-guide/skills/bundled/creative/creative-baoyu-infographic.md +++ b/website/docs/user-guide/skills/bundled/creative/creative-baoyu-infographic.md @@ -15,7 +15,7 @@ Infographics: 21 layouts x 21 styles (信息图, 可视化). | | | |---|---| | Source | Bundled (installed by default) | -| Path | `skills/creative/baoyu-infographic` | +| Path | `skills/creative\baoyu-infographic` | | Version | `1.56.1` | | Author | 宝玉 (JimLiu) | | License | MIT | diff --git a/website/docs/user-guide/skills/bundled/creative/creative-claude-design.md b/website/docs/user-guide/skills/bundled/creative/creative-claude-design.md index c20dd7dceb..95fdaac6e7 100644 --- a/website/docs/user-guide/skills/bundled/creative/creative-claude-design.md +++ b/website/docs/user-guide/skills/bundled/creative/creative-claude-design.md @@ -15,13 +15,13 @@ Design one-off HTML artifacts (landing, deck, prototype). | | | |---|---| | Source | Bundled (installed by default) | -| Path | `skills/creative/claude-design` | +| Path | `skills/creative\claude-design` | | Version | `1.1.0` | | Author | BadTechBandit | | License | MIT | | Platforms | linux, macos, windows | | Tags | `design`, `html`, `prototype`, `ux`, `ui`, `creative`, `artifact`, `deck`, `motion`, `design-system` | -| Related skills | [`design-md`](/docs/user-guide/skills/bundled/creative/creative-design-md), [`popular-web-designs`](/docs/user-guide/skills/bundled/creative/creative-popular-web-designs), [`excalidraw`](/docs/user-guide/skills/bundled/creative/creative-excalidraw), [`architecture-diagram`](/docs/user-guide/skills/bundled/creative/creative-architecture-diagram) | +| Related skills | [`design-md`](/docs/user-guide/skills/bundled/creative/creative-design-md), [`popular-web-designs`](/docs/user-guide/skills/bundled/creative/creative-popular-web-designs), [`excalidraw`](/docs/user-guide/skills/optional/creative/creative-excalidraw), [`architecture-diagram`](/docs/user-guide/skills/bundled/creative/creative-architecture-diagram) | ## Reference: full SKILL.md diff --git a/website/docs/user-guide/skills/bundled/creative/creative-design-md.md b/website/docs/user-guide/skills/bundled/creative/creative-design-md.md index 2e83398a2c..d85492d8fd 100644 --- a/website/docs/user-guide/skills/bundled/creative/creative-design-md.md +++ b/website/docs/user-guide/skills/bundled/creative/creative-design-md.md @@ -15,13 +15,13 @@ Author/validate/export Google's DESIGN.md token spec files. | | | |---|---| | Source | Bundled (installed by default) | -| Path | `skills/creative/design-md` | +| Path | `skills/creative\design-md` | | Version | `1.1.0` | | Author | Hermes Agent | | License | MIT | | Platforms | linux, macos, windows | | Tags | `design`, `design-system`, `tokens`, `ui`, `accessibility`, `wcag`, `tailwind`, `dtcg`, `google` | -| Related skills | [`popular-web-designs`](/docs/user-guide/skills/bundled/creative/creative-popular-web-designs), [`claude-design`](/docs/user-guide/skills/bundled/creative/creative-claude-design), [`excalidraw`](/docs/user-guide/skills/bundled/creative/creative-excalidraw), [`architecture-diagram`](/docs/user-guide/skills/bundled/creative/creative-architecture-diagram) | +| Related skills | [`popular-web-designs`](/docs/user-guide/skills/bundled/creative/creative-popular-web-designs), [`claude-design`](/docs/user-guide/skills/bundled/creative/creative-claude-design), [`excalidraw`](/docs/user-guide/skills/optional/creative/creative-excalidraw), [`architecture-diagram`](/docs/user-guide/skills/bundled/creative/creative-architecture-diagram) | ## Reference: full SKILL.md diff --git a/website/docs/user-guide/skills/bundled/creative/creative-humanizer.md b/website/docs/user-guide/skills/bundled/creative/creative-humanizer.md index 4474c11114..e36d984c0d 100644 --- a/website/docs/user-guide/skills/bundled/creative/creative-humanizer.md +++ b/website/docs/user-guide/skills/bundled/creative/creative-humanizer.md @@ -15,7 +15,7 @@ Humanize text: strip AI-isms and add real voice. | | | |---|---| | Source | Bundled (installed by default) | -| Path | `skills/creative/humanizer` | +| Path | `skills/creative\humanizer` | | Version | `2.5.1` | | Author | Siqi Chen (@blader, https://github.com/blader/humanizer), ported by Hermes Agent | | License | MIT | diff --git a/website/docs/user-guide/skills/bundled/creative/creative-manim-video.md b/website/docs/user-guide/skills/bundled/creative/creative-manim-video.md index f22a7005d8..272a08fed7 100644 --- a/website/docs/user-guide/skills/bundled/creative/creative-manim-video.md +++ b/website/docs/user-guide/skills/bundled/creative/creative-manim-video.md @@ -15,7 +15,7 @@ Manim CE animations: 3Blue1Brown math/algo videos. | | | |---|---| | Source | Bundled (installed by default) | -| Path | `skills/creative/manim-video` | +| Path | `skills/creative\manim-video` | | Version | `1.0.0` | | Author | SHL0MS, Hermes Agent | | License | MIT | diff --git a/website/docs/user-guide/skills/bundled/creative/creative-p5js.md b/website/docs/user-guide/skills/bundled/creative/creative-p5js.md index 46ecfa9299..f819e3c69e 100644 --- a/website/docs/user-guide/skills/bundled/creative/creative-p5js.md +++ b/website/docs/user-guide/skills/bundled/creative/creative-p5js.md @@ -15,13 +15,13 @@ p5.js sketches: gen art, shaders, interactive, 3D. | | | |---|---| | Source | Bundled (installed by default) | -| Path | `skills/creative/p5js` | +| Path | `skills/creative\p5js` | | Version | `1.0.0` | | Author | SHL0MS, Hermes Agent | | License | MIT | | Platforms | linux, macos, windows | | Tags | `creative-coding`, `generative-art`, `p5js`, `canvas`, `interactive`, `visualization`, `webgl`, `shaders`, `animation` | -| Related skills | [`ascii-video`](/docs/user-guide/skills/bundled/creative/creative-ascii-video), [`manim-video`](/docs/user-guide/skills/bundled/creative/creative-manim-video), [`excalidraw`](/docs/user-guide/skills/bundled/creative/creative-excalidraw) | +| Related skills | [`ascii-video`](/docs/user-guide/skills/bundled/creative/creative-ascii-video), [`manim-video`](/docs/user-guide/skills/bundled/creative/creative-manim-video), [`excalidraw`](/docs/user-guide/skills/optional/creative/creative-excalidraw) | ## Reference: full SKILL.md @@ -274,7 +274,7 @@ Key implementation patterns: ### Step 4: Preview & Iterate - Open HTML file directly in browser — no server needed for basic sketches -- For `loadImage()`/`loadFont()` from local files: use `scripts/serve.sh` or `python3 -m http.server` +- For `loadImage()`/`loadFont()` from local files: use `scripts/serve.sh` or `python -m http.server` - Chrome DevTools Performance tab to verify 60fps - Test at target export resolution, not just the window size - Adjust parameters until the visual matches the concept from Step 1 @@ -506,7 +506,7 @@ When building p5.js sketches: 1. **Write the HTML file** — single self-contained file, all code inline 2. **Open in browser** — `open sketch.html` (macOS) or `xdg-open sketch.html` (Linux) -3. **Local assets** (fonts, images) require a server: `python3 -m http.server 8080` in the project directory, then open `http://localhost:8080/sketch.html` +3. **Local assets** (fonts, images) require a server: `python -m http.server 8080` in the project directory, then open `http://localhost:8080/sketch.html` 4. **Export PNG/GIF** — add `keyPressed()` shortcuts as shown above, tell the user which key to press 5. **Headless export** — `node scripts/export-frames.js sketch.html --frames 300` for automated frame capture (sketch must use `noLoop()` + `_p5Ready`) 6. **MP4 rendering** — `bash scripts/render.sh sketch.html output.mp4 --duration 30` diff --git a/website/docs/user-guide/skills/bundled/creative/creative-popular-web-designs.md b/website/docs/user-guide/skills/bundled/creative/creative-popular-web-designs.md index 5352e47502..f4c1e1256a 100644 --- a/website/docs/user-guide/skills/bundled/creative/creative-popular-web-designs.md +++ b/website/docs/user-guide/skills/bundled/creative/creative-popular-web-designs.md @@ -15,7 +15,7 @@ description: "54 real design systems (Stripe, Linear, Vercel) as HTML/CSS" | | | |---|---| | Source | Bundled (installed by default) | -| Path | `skills/creative/popular-web-designs` | +| Path | `skills/creative\popular-web-designs` | | Version | `1.0.0` | | Author | Hermes Agent + Teknium (design systems sourced from VoltAgent/awesome-design-md) | | License | MIT | diff --git a/website/docs/user-guide/skills/bundled/creative/creative-songwriting-and-ai-music.md b/website/docs/user-guide/skills/bundled/creative/creative-songwriting-and-ai-music.md index db3781f7e6..f2270be8e2 100644 --- a/website/docs/user-guide/skills/bundled/creative/creative-songwriting-and-ai-music.md +++ b/website/docs/user-guide/skills/bundled/creative/creative-songwriting-and-ai-music.md @@ -15,7 +15,7 @@ Songwriting craft and Suno AI music prompts. | | | |---|---| | Source | Bundled (installed by default) | -| Path | `skills/creative/songwriting-and-ai-music` | +| Path | `skills/creative\songwriting-and-ai-music` | | Version | `1.0.0` | | Author | Teknium (teknium1), Hermes Agent | | License | MIT | diff --git a/website/docs/user-guide/skills/bundled/devops/devops-sdlc-review.md b/website/docs/user-guide/skills/bundled/devops/devops-sdlc-review.md new file mode 100644 index 0000000000..4ef2403ac1 --- /dev/null +++ b/website/docs/user-guide/skills/bundled/devops/devops-sdlc-review.md @@ -0,0 +1,195 @@ +--- +title: "Sdlc Review — Review Kanban handoffs and route verified outcomes" +sidebar_label: "Sdlc Review" +description: "Review Kanban handoffs and route verified outcomes" +--- + +{/* 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. */} + +# Sdlc Review + +Review Kanban handoffs and route verified outcomes. + +## Skill metadata + +| | | +|---|---| +| Source | Bundled (installed by default) | +| Path | `skills/devops\sdlc-review` | +| Version | `1.1.0` | +| Author | Jakub Wolniewicz (@frizikk) + Hermes Agent | +| License | MIT | +| Platforms | linux, macos, windows | +| Tags | `kanban`, `review`, `quality`, `verification` | + +## 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. +::: + +# SDLC Review Skill + +Independently verify work handed from a Kanban implementation run to the review lane, then approve it, request changes, or escalate. This skill reviews the deliverable and its evidence; it does not take over the implementer's work. + +## When to Use + +Use this skill when all of the following are true: + +- the dispatcher spawned you for a task claimed from the `review` lane; +- an implementer submitted a `review_requested` handoff; +- the task needs an independent verdict before it can be completed. + +Do not use it for a separate downstream review card. A downstream card is ordinary implementation work with a review-oriented specification and completes through its own lifecycle. + +## Prerequisites + +- A Kanban worker context with the current task and run identifiers. +- Native Kanban tools: `kanban_show`, `kanban_comment`, `kanban_complete`, `kanban_request_changes`, and `kanban_block`. +- Workspace access through `read_file`, `search_files`, and `terminal` when the deliverable is code. +- The task's original specification, acceptance criteria, handoff summary, and prior run history must be available through `kanban_show`. + +## How to Run + +This skill is loaded automatically by the review dispatcher. Start with `kanban_show` before inspecting files or choosing a verdict. + +1. Read the task specification and the latest `review_requested` handoff. +2. Inspect the actual deliverable and run relevant verification. +3. Choose exactly one verdict: approve, request changes, or escalate. +4. Record concrete evidence in the terminal Kanban transition. + +## Quick Reference + +| Verdict | When | Final action | +|---|---|---| +| Approve | Acceptance criteria and verification pass | `kanban_complete` | +| Request changes | Correctable implementation defects remain | `kanban_comment`, then `kanban_request_changes` | +| Escalate | A human decision or external prerequisite is required | `kanban_block` | + +A requested-changes transition returns the task to its original implementer. When that implementer requests review again without naming a reviewer, the persisted reviewer provenance routes the re-review back to the same reviewer profile. + +## Review Lenses + +Vary how you look at the work on each round instead of repeating the same inspection. Decorrelated lenses catch different defect classes: a cold read of the artifact surfaces design and correctness problems that the implementer's narrative would have framed away, execution surfaces claims that do not reproduce, and a strict contract audit surfaces quiet scope drift. Repeating the round-1 lens on round 3 mostly re-finds what round 1 already found. + +Determine the current round from the history the task record already gives you: count the `changes_requested` entries in the "Prior attempts on this task" section of your worker context (also visible as prior runs in `kanban_show`). The current review round is that count plus one. Round 1 therefore shows zero `changes_requested` attempts; round 2 shows one; and so on. + +| Round | Lens | How to apply it | +|---|---|---| +| 1 | Artifact | Read the diff or deliverable cold, before the implementer's summary. Form an independent judgment, then compare it against the handoff narrative and investigate every mismatch. | +| 2 | Execution | Check out the work and actually run it via `terminal`: build, test, and exercise the reported behavior yourself. Verify each handoff claim empirically instead of re-reading the artifact. | +| 3+ | Contract | Re-read the ORIGINAL task body and acceptance criteria, then audit the deliverable strictly against them. Also verify that every item from every prior `kanban_request_changes` round actually landed. | + +The baseline duties in the Procedure section still apply on every round; the lens sets which inspection you lead with and weight most heavily. + +### Lens variation for ad-hoc review fan-outs + +The same principle applies outside the Kanban review lane. When spawning multiple parallel reviewers via `delegate_task`, give each reviewer a different lens — one diff-only brief, one full-context brief, one checkout-and-run brief — rather than identical briefs. Identical briefs produce correlated verdicts and duplicate findings; varied briefs cover more defect classes for the same review spend. + +## Procedure + +### 1. Orient from the durable task record + +Call `kanban_show` and identify: + +- the original task body and acceptance criteria; +- the latest implementation summary and structured metadata; +- changed files, commit identifiers, and test evidence; +- comments and decisions from earlier runs; +- findings from prior review rounds. + +Treat the handoff as a claim to verify, not as proof that the work is correct. + +### 2. Compare requested behavior with delivered behavior + +Map every acceptance criterion to concrete implementation or output evidence. Note omissions, changed semantics, and unrelated scope before deciding whether to run deeper checks. + +For code work: + +1. Use `read_file` and `search_files` to inspect the changed paths and their callers. +2. Use `terminal` to inspect the diff and run the project's existing focused tests, lint, type checks, or build commands. +3. Exercise the reported failure path and at least one ordinary control path when practical. +4. Check error handling, edge cases, concurrency boundaries, data preservation, security boundaries, and cross-platform behavior relevant to the change. +5. Confirm that tests assert behavior rather than merely snapshotting source text or constants. + +For non-code work: + +1. Inspect the complete deliverable rather than only its summary. +2. Check correctness, completeness, formatting, and provenance. +3. Validate referenced URLs or external facts with the appropriate native tools when they affect the verdict. + +### 3. Choose one verdict + +#### Approve + +Approve only when the acceptance criteria are satisfied and the evidence is sufficient. Call: + +```text +kanban_complete( + summary="Reviewed and approved. <what was verified>", + metadata={"review_outcome": "approved", "reviewer_checks": [...]} +) +``` + +Include the exact checks that passed and any bounded caveat that does not block acceptance. + +#### Request changes + +Use this for specific, correctable defects. First record actionable findings: + +```text +kanban_comment( + task_id="<current-task-id>", + body="Changes requested:\n1. <file or artifact + defect>\n2. <required correction>", +) +``` + +Then return the same task to its implementer: + +```text +kanban_request_changes( + reason="<concise summary of the required corrections>" +) +``` + +State where the defect is, how it reproduces, why it violates the task, and what minimum outcome would resolve it. The transition does not use blocker recurrence accounting. + +#### Escalate + +Use escalation only when the reviewer and implementer cannot resolve the problem without a human decision or external prerequisite: + +```text +kanban_block( + reason="escalation: <decision or prerequisite required>" +) +``` + +Explain the blocked decision and the smallest information needed to continue. + +### 4. Preserve role separation + +Do not edit the implementation while acting as reviewer. Request changes and let the implementer produce the next candidate; then independently verify that candidate in the next review run. + +## Pitfalls + +- **Rubber-stamping:** A passing handoff summary is not independent evidence. +- **Reviewer implementation:** Editing the deliverable hides ownership and weakens the re-review boundary. +- **Vague findings:** “Needs work” does not give the implementer a reproducible correction target. +- **Style-only blocking:** Do not request changes for preference-level nits when behavior and repository standards are satisfied. +- **Skipping prior rounds:** Re-review must confirm both the requested corrections and preservation of previously passing behavior. +- **Using blockers for ordinary rework:** Correctable defects belong in `kanban_request_changes`; reserve `kanban_block` for genuine external blockers or human decisions. +- **Completing without evidence:** Every approval summary must name the checks or artifacts actually inspected. + +## Verification + +Before submitting the verdict, confirm: + +- [ ] `kanban_show` was read for the current task and run. +- [ ] Every acceptance criterion was mapped to evidence. +- [ ] The actual deliverable was inspected. +- [ ] Relevant focused checks were run or an explicit reason was recorded when execution was impossible. +- [ ] Prior requested changes were re-tested on re-review. +- [ ] Unrelated regressions and scope changes were considered. +- [ ] The verdict uses exactly one terminal action. +- [ ] The summary contains concrete, non-secret evidence. +- [ ] No implementation files were edited by the reviewer. diff --git a/website/docs/user-guide/skills/bundled/email/email-email-inbox-triage.md b/website/docs/user-guide/skills/bundled/email/email-email-inbox-triage.md index a19dfed71f..3c68833eec 100644 --- a/website/docs/user-guide/skills/bundled/email/email-email-inbox-triage.md +++ b/website/docs/user-guide/skills/bundled/email/email-email-inbox-triage.md @@ -15,7 +15,7 @@ Triage an inbox: prioritize threads, draft replies safely. | | | |---|---| | Source | Bundled (installed by default) | -| Path | `skills/email/email-inbox-triage` | +| Path | `skills/email\email-inbox-triage` | | Version | `0.1.0` | | Author | Ben Barclay (benbarclay), Hermes Agent | | License | MIT | diff --git a/website/docs/user-guide/skills/bundled/email/email-himalaya.md b/website/docs/user-guide/skills/bundled/email/email-himalaya.md index 3876828468..4289ccfd18 100644 --- a/website/docs/user-guide/skills/bundled/email/email-himalaya.md +++ b/website/docs/user-guide/skills/bundled/email/email-himalaya.md @@ -15,7 +15,7 @@ Himalaya CLI: IMAP/SMTP email from terminal. | | | |---|---| | Source | Bundled (installed by default) | -| Path | `skills/email/himalaya` | +| Path | `skills/email\himalaya` | | Version | `1.1.0` | | Author | community | | License | MIT | diff --git a/website/docs/user-guide/skills/bundled/media/media-gif-search.md b/website/docs/user-guide/skills/bundled/media/media-gif-search.md index 31d0e03eb8..8d71c12184 100644 --- a/website/docs/user-guide/skills/bundled/media/media-gif-search.md +++ b/website/docs/user-guide/skills/bundled/media/media-gif-search.md @@ -15,7 +15,7 @@ Search/download GIFs from Tenor via curl + jq. | | | |---|---| | Source | Bundled (installed by default) | -| Path | `skills/media/gif-search` | +| Path | `skills/media\gif-search` | | Version | `1.1.0` | | Author | Hermes Agent | | License | MIT | @@ -103,4 +103,4 @@ Each result has multiple formats under `.media_formats`: - URL-encode the query: spaces as `+`, special chars as `%XX` - For sending in chat, `tinygif` URLs are lighter weight -- GIF URLs can be used directly in markdown: `![alt](https://github.com/NousResearch/hermes-agent/blob/main/skills/media/gif-search/url)` +- GIF URLs can be used directly in markdown: `![alt](https://github.com/NousResearch/hermes-agent/blob/main/skills/media\gif-search/url)` diff --git a/website/docs/user-guide/skills/bundled/media/media-songsee.md b/website/docs/user-guide/skills/bundled/media/media-songsee.md index dd1e1d3d5e..b0d86f2ab6 100644 --- a/website/docs/user-guide/skills/bundled/media/media-songsee.md +++ b/website/docs/user-guide/skills/bundled/media/media-songsee.md @@ -15,7 +15,7 @@ Audio spectrograms/features (mel, chroma, MFCC) via CLI. | | | |---|---| | Source | Bundled (installed by default) | -| Path | `skills/media/songsee` | +| Path | `skills/media\songsee` | | Version | `1.0.0` | | Author | community | | License | MIT | diff --git a/website/docs/user-guide/skills/bundled/media/media-youtube-content.md b/website/docs/user-guide/skills/bundled/media/media-youtube-content.md index 47cc4acc46..6324aca041 100644 --- a/website/docs/user-guide/skills/bundled/media/media-youtube-content.md +++ b/website/docs/user-guide/skills/bundled/media/media-youtube-content.md @@ -15,7 +15,7 @@ YouTube transcripts to summaries, threads, blogs. | | | |---|---| | Source | Bundled (installed by default) | -| Path | `skills/media/youtube-content` | +| Path | `skills/media\youtube-content` | | Version | `1.0.0` | | Author | Teknium (teknium1), Hermes Agent | | License | MIT | @@ -51,16 +51,16 @@ uv pip install youtube-transcript-api ```bash # JSON output with metadata -uv run python3 SKILL_DIR/scripts/fetch_transcript.py "https://youtube.com/watch?v=VIDEO_ID" +uv run python SKILL_DIR/scripts/fetch_transcript.py "https://youtube.com/watch?v=VIDEO_ID" # Plain text (good for piping into further processing) -uv run python3 SKILL_DIR/scripts/fetch_transcript.py "URL" --text-only +uv run python SKILL_DIR/scripts/fetch_transcript.py "URL" --text-only # With timestamps -uv run python3 SKILL_DIR/scripts/fetch_transcript.py "URL" --timestamps +uv run python SKILL_DIR/scripts/fetch_transcript.py "URL" --timestamps # Specific language with fallback chain -uv run python3 SKILL_DIR/scripts/fetch_transcript.py "URL" --language tr,en +uv run python SKILL_DIR/scripts/fetch_transcript.py "URL" --language tr,en ``` ## Output Formats @@ -86,7 +86,7 @@ After fetching the transcript, format it based on what the user asks for: ## Workflow -1. **Fetch** the transcript using the helper script with `--text-only --timestamps` via `uv run python3`. +1. **Fetch** the transcript using the helper script with `--text-only --timestamps` via `uv run python`. 2. **Validate**: confirm the output is non-empty and in the expected language. If empty, retry without `--language` to get any available transcript. If still empty, tell the user the video likely has transcripts disabled. 3. **Chunk if needed**: if the transcript exceeds ~50K characters, split into overlapping chunks (~40K with 2K overlap) and summarize each chunk before merging. 4. **Transform** into the requested output format. If the user did not specify a format, default to a summary. diff --git a/website/docs/user-guide/skills/bundled/note-taking/note-taking-obsidian.md b/website/docs/user-guide/skills/bundled/note-taking/note-taking-obsidian.md index 22e5178a68..34d311f206 100644 --- a/website/docs/user-guide/skills/bundled/note-taking/note-taking-obsidian.md +++ b/website/docs/user-guide/skills/bundled/note-taking/note-taking-obsidian.md @@ -15,7 +15,7 @@ Read, search, create, and edit notes in the Obsidian vault. | | | |---|---| | Source | Bundled (installed by default) | -| Path | `skills/note-taking/obsidian` | +| Path | `skills/note-taking\obsidian` | | Version | `1.0.0` | | Author | Teknium (teknium1), Hermes Agent | | License | MIT | diff --git a/website/docs/user-guide/skills/bundled/productivity/productivity-airtable.md b/website/docs/user-guide/skills/bundled/productivity/productivity-airtable.md index 05a3e13fba..f0363db1fb 100644 --- a/website/docs/user-guide/skills/bundled/productivity/productivity-airtable.md +++ b/website/docs/user-guide/skills/bundled/productivity/productivity-airtable.md @@ -15,7 +15,7 @@ Airtable REST API via curl. Records CRUD, filters, upserts. | | | |---|---| | Source | Bundled (installed by default) | -| Path | `skills/productivity/airtable` | +| Path | `skills/productivity\airtable` | | Version | `1.1.0` | | Author | community | | License | MIT | @@ -58,10 +58,10 @@ Work with Airtable's REST API directly via `curl` using the `terminal` tool. No Base curl pattern: ```bash curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE?maxRecords=5" \ - -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool + -H "Authorization: Bearer $AIRTABLE_API_KEY" | python -m json.tool ``` -`-s` suppresses curl's progress bar — keep it set for every call so the tool output stays clean for Hermes. Pipe through `python3 -m json.tool` (always present) or `jq` (if installed) for readable JSON. +`-s` suppresses curl's progress bar — keep it set for every call so the tool output stays clean for Hermes. Pipe through `python -m json.tool` (always present) or `jq` (if installed) for readable JSON. ## Field Types (request body shapes) @@ -87,35 +87,35 @@ Pass `"typecast": true` at the top level of a create/update body to let Airtable ### List bases the token can see ```bash curl -s "https://api.airtable.com/v0/meta/bases" \ - -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool + -H "Authorization: Bearer $AIRTABLE_API_KEY" | python -m json.tool ``` ### List tables + schema for a base ```bash curl -s "https://api.airtable.com/v0/meta/bases/$BASE_ID/tables" \ - -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool + -H "Authorization: Bearer $AIRTABLE_API_KEY" | python -m json.tool ``` Use this BEFORE mutating — confirms exact field names and IDs, surfaces `options.choices` for select fields, and shows primary-field names. ### List records (first 10) ```bash curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE?maxRecords=10" \ - -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool + -H "Authorization: Bearer $AIRTABLE_API_KEY" | python -m json.tool ``` ### Get a single record ```bash curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE/$RECORD_ID" \ - -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool + -H "Authorization: Bearer $AIRTABLE_API_KEY" | python -m json.tool ``` ### Filter records (filterByFormula) Airtable formulas must be URL-encoded. Let Python stdlib do it — never hand-encode: ```bash FORMULA="{Status}='Todo'" -ENC=$(python3 -c 'import sys, urllib.parse; print(urllib.parse.quote(sys.argv[1], safe=""))' "$FORMULA") +ENC=$(python -c 'import sys, urllib.parse; print(urllib.parse.quote(sys.argv[1], safe=""))' "$FORMULA") curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE?filterByFormula=$ENC&maxRecords=20" \ - -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool + -H "Authorization: Bearer $AIRTABLE_API_KEY" | python -m json.tool ``` Useful formula patterns: @@ -129,14 +129,14 @@ Useful formula patterns: ### Sort + select specific fields ```bash curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE?sort%5B0%5D%5Bfield%5D=Priority&sort%5B0%5D%5Bdirection%5D=asc&fields%5B%5D=Name&fields%5B%5D=Status" \ - -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool + -H "Authorization: Bearer $AIRTABLE_API_KEY" | python -m json.tool ``` Square brackets in query params MUST be URL-encoded (`%5B` / `%5D`). ### Use a named view ```bash curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE?view=Grid%20view&maxRecords=50" \ - -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool + -H "Authorization: Bearer $AIRTABLE_API_KEY" | python -m json.tool ``` Views apply their saved filter + sort server-side. @@ -147,7 +147,7 @@ Views apply their saved filter + sort server-side. curl -s -X POST "https://api.airtable.com/v0/$BASE_ID/$TABLE" \ -H "Authorization: Bearer $AIRTABLE_API_KEY" \ -H "Content-Type: application/json" \ - -d '{"fields":{"Name":"New task","Status":"Todo","Priority":"High"}}' | python3 -m json.tool + -d '{"fields":{"Name":"New task","Status":"Todo","Priority":"High"}}' | python -m json.tool ``` ### Create up to 10 records in one call @@ -161,7 +161,7 @@ curl -s -X POST "https://api.airtable.com/v0/$BASE_ID/$TABLE" \ {"fields": {"Name": "Task A", "Status": "Todo"}}, {"fields": {"Name": "Task B", "Status": "In progress"}} ] - }' | python3 -m json.tool + }' | python -m json.tool ``` Batch endpoints are capped at **10 records per request**. For larger inserts, loop in batches of 10 with a short sleep to respect 5 req/sec/base. @@ -170,7 +170,7 @@ Batch endpoints are capped at **10 records per request**. For larger inserts, lo curl -s -X PATCH "https://api.airtable.com/v0/$BASE_ID/$TABLE/$RECORD_ID" \ -H "Authorization: Bearer $AIRTABLE_API_KEY" \ -H "Content-Type: application/json" \ - -d '{"fields":{"Status":"Done"}}' | python3 -m json.tool + -d '{"fields":{"Status":"Done"}}' | python -m json.tool ``` ### Upsert by a merge field (no ID needed) @@ -183,20 +183,20 @@ curl -s -X PATCH "https://api.airtable.com/v0/$BASE_ID/$TABLE" \ "records": [ {"fields": {"Email": "user@example.com", "Status": "Active"}} ] - }' | python3 -m json.tool + }' | python -m json.tool ``` `performUpsert` creates records whose merge-field values are new, patches records whose merge-field values already exist. Great for idempotent syncs. ### Delete a record ```bash curl -s -X DELETE "https://api.airtable.com/v0/$BASE_ID/$TABLE/$RECORD_ID" \ - -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool + -H "Authorization: Bearer $AIRTABLE_API_KEY" | python -m json.tool ``` ### Delete up to 10 records in one call ```bash curl -s -X DELETE "https://api.airtable.com/v0/$BASE_ID/$TABLE?records%5B%5D=rec1&records%5B%5D=rec2" \ - -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool + -H "Authorization: Bearer $AIRTABLE_API_KEY" | python -m json.tool ``` ## Pagination @@ -209,8 +209,8 @@ while :; do URL="https://api.airtable.com/v0/$BASE_ID/$TABLE?pageSize=100" [ -n "$OFFSET" ] && URL="$URL&offset=$OFFSET" RESP=$(curl -s "$URL" -H "Authorization: Bearer $AIRTABLE_API_KEY") - echo "$RESP" | python3 -c 'import json,sys; d=json.load(sys.stdin); [print(r["id"], r["fields"].get("Name","")) for r in d["records"]]' - OFFSET=$(echo "$RESP" | python3 -c 'import json,sys; d=json.load(sys.stdin); print(d.get("offset",""))') + echo "$RESP" | python -c 'import json,sys; d=json.load(sys.stdin); [print(r["id"], r["fields"].get("Name","")) for r in d["records"]]' + OFFSET=$(echo "$RESP" | python -c 'import json,sys; d=json.load(sys.stdin); print(d.get("offset",""))') [ -z "$OFFSET" ] && break done ``` @@ -237,7 +237,7 @@ done - **Always use the `terminal` tool with `curl`.** Do NOT use `web_extract` (it can't send auth headers) or `browser_navigate` (needs UI auth and is slow). - **`AIRTABLE_API_KEY` flows from `${HERMES_HOME:-~/.hermes}/.env` into the subprocess automatically** when this skill is loaded — no need to re-export it before each `curl` call. -- **Escape curly braces in formulas carefully.** In a heredoc body, `{Status}` is literal. In a shell argument, `{Status}` is safe outside `{...}` brace-expansion context — but pass dynamic strings through `python3 urllib.parse.quote` before splicing into a URL. -- **Pretty-print with `python3 -m json.tool`** (always present) rather than `jq` (optional). Only reach for `jq` when you need filtering/projection. +- **Escape curly braces in formulas carefully.** In a heredoc body, `{Status}` is literal. In a shell argument, `{Status}` is safe outside `{...}` brace-expansion context — but pass dynamic strings through `python urllib.parse.quote` before splicing into a URL. +- **Pretty-print with `python -m json.tool`** (always present) rather than `jq` (optional). Only reach for `jq` when you need filtering/projection. - **Pagination is per-page, not global.** Airtable's 100-record cap is a hard limit; there is no way to bump it. Loop with `offset` until the field is absent. - **Read the `errors` array** on non-2xx responses — Airtable returns structured error codes like `AUTHENTICATION_REQUIRED`, `INVALID_PERMISSIONS`, `MODEL_ID_NOT_FOUND`, `INVALID_MULTIPLE_CHOICE_OPTIONS` that tell you exactly what's wrong. diff --git a/website/docs/user-guide/skills/bundled/productivity/productivity-box.md b/website/docs/user-guide/skills/bundled/productivity/productivity-box.md index ed5f012031..770fdc958f 100644 --- a/website/docs/user-guide/skills/bundled/productivity/productivity-box.md +++ b/website/docs/user-guide/skills/bundled/productivity/productivity-box.md @@ -15,7 +15,7 @@ Box manages cloud files, sharing, search, and metadata. | | | |---|---| | Source | Bundled (installed by default) | -| Path | `skills/productivity/box` | +| Path | `skills/productivity\box` | | Version | `1.0.0` | | Author | Chris Kim (iskysun96), Hermes Agent | | License | MIT | @@ -55,24 +55,24 @@ Start normal CLI work with the official Box CLI OAuth app. It covers ordinary co When a user selects an authentication path or asks Hermes to connect Box, perform the setup through `terminal`; do not turn the next response into instructions for the user to copy. Take the next safe action yourself, and pause only for an approval, browser sign-in, administrator action, or secret that Hermes cannot safely supply. -- If `box` is missing, ask for any terminal approval required to install `@box/cli` under the current Hermes home at `tools/box-cli`; then verify it with the shell-appropriate command in [CLI guide](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity/box/references/cli-guide.md). Do not attempt a global npm install, use `sudo`, change npm's global prefix, or change `PATH`. -- Before OAuth, ask: **“Is Hermes running on the same computer as the browser you will use to authorize Box, or on a remote host such as a VPS, container, or cloud VM?”** Use normal `box login` only for the same-computer path. Use `box login --code` only for the remote/headless path. Do not infer runtime topology from the operating system alone; read [OAuth setup](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity/box/references/oauth-setup.md) after the user answers. +- If `box` is missing, ask for any terminal approval required to install `@box/cli` under the current Hermes home at `tools/box-cli`; then verify it with the shell-appropriate command in [CLI guide](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity\box/references/cli-guide.md). Do not attempt a global npm install, use `sudo`, change npm's global prefix, or change `PATH`. +- Before OAuth, ask: **“Is Hermes running on the same computer as the browser you will use to authorize Box, or on a remote host such as a VPS, container, or cloud VM?”** Use normal `box login` only for the same-computer path. Use `box login --code` only for the remote/headless path. Do not infer runtime topology from the operating system alone; read [OAuth setup](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity\box/references/oauth-setup.md) after the user answers. - Before starting browser authorization, state that Hermes will act as the Box account signed in there. If the user wants narrower access, they can authorize an account that is invited only to the required files, folders, or Hubs. Do not make that account an administrator to unlock an exceptional operation. - If a custom OAuth Platform App is necessary, use the CLI's interactive Platform App flow. Ask the user to enter its client secret only in the local CLI prompt; never request it in chat, write it to Hermes configuration, or commit it. - If an install, browser authorization, environment switch, or permission change needs approval, request that approval and resume the setup after it is granted. Do not replace the action with a command list. ## Start each task -1. Confirm the CLI and current actor. Probe with `command -v box` on POSIX shells or `Get-Command box -ErrorAction SilentlyContinue` in PowerShell. If `box` is on `PATH`, use it. If Hermes installed the CLI under its current home, use the shell-appropriate verified runner in [CLI guide](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity/box/references/cli-guide.md) in place of every leading `box`. Then run `box users:get me --json --fields id,name,login` with that runner. - If this succeeds, record the actor and continue. Do not ask about authentication again. Treat `folders:items 0` only as a listing of the actor's root; it is not proof that a shared file, folder, or Hub is inaccessible. For a known file or folder, verify its ID directly; for a Hub, use the Hubs discovery path in [Box Hubs](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity/box/references/hubs.md). -2. If authentication is absent, ask to connect a Box account with OAuth, then ask whether Hermes and the authorization browser run on the same computer or on separate hosts. Read [OAuth setup](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity/box/references/oauth-setup.md). +1. Confirm the CLI and current actor. Probe with `command -v box` on POSIX shells or `Get-Command box -ErrorAction SilentlyContinue` in PowerShell. If `box` is on `PATH`, use it. If Hermes installed the CLI under its current home, use the shell-appropriate verified runner in [CLI guide](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity\box/references/cli-guide.md) in place of every leading `box`. Then run `box users:get me --json --fields id,name,login` with that runner. + If this succeeds, record the actor and continue. Do not ask about authentication again. Treat `folders:items 0` only as a listing of the actor's root; it is not proof that a shared file, folder, or Hub is inaccessible. For a known file or folder, verify its ID directly; for a Hub, use the Hubs discovery path in [Box Hubs](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity\box/references/hubs.md). +2. If authentication is absent, ask to connect a Box account with OAuth, then ask whether Hermes and the authorization browser run on the same computer or on separate hosts. Read [OAuth setup](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity\box/references/oauth-setup.md). 3. Read the relevant reference before operating. Use documented commands first; only run subcommand help when the request needs an option not covered by the reference or the installed CLI rejects the documented form. Examples labeled `bash` use POSIX continuation syntax. In PowerShell, run the Box command on one line or replace each trailing `\` with PowerShell's backtick continuation. Do not paste POSIX variable assignments into PowerShell. ## Extend the CLI without pausing -When the Box CLI lacks a dedicated subcommand, use `box request` for the matching REST endpoint and continue the ordinary operation. Do not ask the user to choose merely because the implementation uses REST; it is the same Box task and preserves the configured CLI identity. Read [REST API fallback](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity/box/references/rest-api.md) when the endpoint needs a request body or custom header. +When the Box CLI lacks a dedicated subcommand, use `box request` for the matching REST endpoint and continue the ordinary operation. Do not ask the user to choose merely because the implementation uses REST; it is the same Box task and preserves the configured CLI identity. Read [REST API fallback](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity\box/references/rest-api.md) when the endpoint needs a request body or custom header. Ask before a delete, a collaboration/shared-link or permission change, an identity change, a broad or costly batch mutation, or when the target or scope is ambiguous. Otherwise perform the requested operation and verify it. @@ -80,15 +80,15 @@ Ask before a delete, a collaboration/shared-link or permission change, an identi | Need | Read | | --- | --- | -| CLI conventions, environments, JSON, or REST escape hatch | [CLI guide](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity/box/references/cli-guide.md) | -| Files, folders, versions, links, or collaborations | [Content workflows](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity/box/references/content-workflows.md) | -| Search, metadata, Box AI, or AI units | [Search and AI](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity/box/references/search-and-ai.md) | -| Curated large-scale Q&A or a reusable knowledge base | [Box Hubs](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity/box/references/hubs.md) | -| Many files or a resumable batch | [Bulk operations](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity/box/references/bulk-operations.md) | -| Application code or a Box SDK | [SDK development](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity/box/references/sdk-development.md) | -| Webhooks or Events API | [Webhooks and events](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity/box/references/webhooks-and-events.md) | -| CLI unavailable or a missing CLI operation | [REST API fallback](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity/box/references/rest-api.md) | -| Auth, permissions, rate limits, or API errors | [Troubleshooting](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity/box/references/troubleshooting.md) | +| CLI conventions, environments, JSON, or REST escape hatch | [CLI guide](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity\box/references/cli-guide.md) | +| Files, folders, versions, links, or collaborations | [Content workflows](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity\box/references/content-workflows.md) | +| Search, metadata, Box AI, or AI units | [Search and AI](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity\box/references/search-and-ai.md) | +| Curated large-scale Q&A or a reusable knowledge base | [Box Hubs](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity\box/references/hubs.md) | +| Many files or a resumable batch | [Bulk operations](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity\box/references/bulk-operations.md) | +| Application code or a Box SDK | [SDK development](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity\box/references/sdk-development.md) | +| Webhooks or Events API | [Webhooks and events](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity\box/references/webhooks-and-events.md) | +| CLI unavailable or a missing CLI operation | [REST API fallback](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity\box/references/rest-api.md) | +| Auth, permissions, rate limits, or API errors | [Troubleshooting](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity\box/references/troubleshooting.md) | ## Content handling policy @@ -101,13 +101,13 @@ Use existing Box metadata or metadata queries for deterministic lookups. Otherwi - `ai:extract` for flexible key-value extraction - `ai:text-gen` for writing grounded in one Box file -For Q&A over more than 25 files or a reusable curated knowledge base, prefer Box AI for Hubs. Discover an existing accessible Hub first; only create or populate one after the user approves the shared-resource change. If no Hub is available and the user does not want one created, narrow a one-off request with search or metadata. Do not use a Hub for metadata extraction or text generation. Read [Box Hubs](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity/box/references/hubs.md). +For Q&A over more than 25 files or a reusable curated knowledge base, prefer Box AI for Hubs. Discover an existing accessible Hub first; only create or populate one after the user approves the shared-resource change. If no Hub is available and the user does not want one created, narrow a one-off request with search or metadata. Do not use a Hub for metadata extraction or text generation. Read [Box Hubs](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity\box/references/hubs.md). When the user asks to extract metadata from a Box file, treat it as a request to persist the result unless they ask for a preview. Use structured extraction with inline fields when the desired schema is known and freeform extraction when the fields are exploratory. Reuse a compatible existing enterprise template when one represents every requested field. Otherwise store flat scalar results in the built-in `global.properties` metadata instance, or upload a JSON sidecar beside the source file when the result contains nested objects, tables, or values that must retain their types. Read every write back and compare it with the intended result. Never silently substitute a file description, attach a partial or unrelated template, truncate fields, or discard fields. -Do not create or change metadata templates. Box does not permit creation of global templates, and enterprise-template administration is outside Hermes' normal OAuth content workflow. If the user needs reusable typed enterprise metadata and no compatible template exists, explain that a Box Admin or authorized Co-Admin must create it separately, leave existing structured metadata unchanged, and report the persisted `global.properties` instance or JSON sidecar instead. Read [Search and AI](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity/box/references/search-and-ai.md) for the complete extraction and writeback workflow. +Do not create or change metadata templates. Box does not permit creation of global templates, and enterprise-template administration is outside Hermes' normal OAuth content workflow. If the user needs reusable typed enterprise metadata and no compatible template exists, explain that a Box Admin or authorized Co-Admin must create it separately, leave existing structured metadata unchanged, and report the persisted `global.properties` instance or JSON sidecar instead. Read [Search and AI](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity\box/references/search-and-ai.md) for the complete extraction and writeback workflow. -Before the first Box AI request, state that Box AI must be enabled, consumes AI units, and remains limited to the current actor's permissions; do not wait for acknowledgement. An AI response returned to Hermes can still contain sensitive information. Confirm only when a material batch's file scope or expected AI-unit use is ambiguous, or when the user has not explicitly requested that scale. See [Search and AI](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity/box/references/search-and-ai.md). +Before the first Box AI request, state that Box AI must be enabled, consumes AI units, and remains limited to the current actor's permissions; do not wait for acknowledgement. An AI response returned to Hermes can still contain sensitive information. Confirm only when a material batch's file scope or expected AI-unit use is ambiguous, or when the user has not explicitly requested that scale. See [Search and AI](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity\box/references/search-and-ai.md). ## Operate safely diff --git a/website/docs/user-guide/skills/bundled/productivity/productivity-document-to-action-items.md b/website/docs/user-guide/skills/bundled/productivity/productivity-document-to-action-items.md index 5ba166e1d7..f0a886f02e 100644 --- a/website/docs/user-guide/skills/bundled/productivity/productivity-document-to-action-items.md +++ b/website/docs/user-guide/skills/bundled/productivity/productivity-document-to-action-items.md @@ -15,13 +15,13 @@ Extract cited obligations, deadlines, tasks from documents. | | | |---|---| | Source | Bundled (installed by default) | -| Path | `skills/productivity/document-to-action-items` | +| Path | `skills/productivity\document-to-action-items` | | Version | `0.1.0` | | Author | Ben Barclay (benbarclay), Hermes Agent | | License | MIT | | Platforms | linux, macos, windows | | Tags | `Documents`, `OCR`, `Action-Items`, `Deadlines`, `Extraction` | -| Related skills | [`ocr-and-documents`](/docs/user-guide/skills/bundled/productivity/productivity-ocr-and-documents), [`pdf`](/docs/user-guide/skills/bundled/productivity/productivity-pdf), [`docx`](/docs/user-guide/skills/bundled/productivity/productivity-docx), [`notion`](/docs/user-guide/skills/bundled/productivity/productivity-notion) | +| Related skills | [`pdf`](/docs/user-guide/skills/bundled/productivity/productivity-pdf), [`pdf`](/docs/user-guide/skills/bundled/productivity/productivity-pdf), [`docx`](/docs/user-guide/skills/bundled/productivity/productivity-docx), [`notion`](/docs/user-guide/skills/bundled/productivity/productivity-notion) | ## Reference: full SKILL.md @@ -31,7 +31,7 @@ The following is the complete skill definition that Hermes loads when this skill # Document to Action Items -Turn documents into cited facts and proposed actions. Extraction is not legal advice, and low-confidence OCR or ambiguous language must remain visible. The `ocr-and-documents` / `pdf` / `docx` skills own extraction mechanics; this skill owns what happens to the extracted content. +Turn documents into cited facts and proposed actions. Extraction is not legal advice, and low-confidence OCR or ambiguous language must remain visible. The `pdf` / `pdf` / `docx` skills own extraction mechanics; this skill owns what happens to the extracted content. ## When to Use @@ -40,7 +40,7 @@ Turn documents into cited facts and proposed actions. Extraction is not legal ad - "Read these scanned forms and structure the data." - "Find risks, owners, and follow-ups in these attachments." -Don't use for: plain text extraction with no downstream structuring (load `ocr-and-documents` directly). +Don't use for: plain text extraction with no downstream structuring (load `pdf` directly). ## Procedure @@ -50,7 +50,7 @@ Use `read_file` for local files and `web_extract` for URLs to identify files, ve ### 2. Extract with provenance -Load `ocr-and-documents`, `pdf`, or `docx`. Extract text/tables while retaining file and page/section coordinates. For scans, record OCR confidence or visible quality issues. Done when every extracted field can cite its source location. +Load `pdf`, `pdf`, or `docx`. Extract text/tables while retaining file and page/section coordinates. For scans, record OCR confidence or visible quality issues. Done when every extracted field can cite its source location. ### 3. Classify evidence diff --git a/website/docs/user-guide/skills/bundled/productivity/productivity-docx.md b/website/docs/user-guide/skills/bundled/productivity/productivity-docx.md index c00e2fc023..5b27f0f0b4 100644 --- a/website/docs/user-guide/skills/bundled/productivity/productivity-docx.md +++ b/website/docs/user-guide/skills/bundled/productivity/productivity-docx.md @@ -1,26 +1,26 @@ --- -title: "Docx — Create, read, edit, and template Word .docx files" +title: "Docx — Create, read, edit, template, and review Word .docx files" sidebar_label: "Docx" -description: "Create, read, edit, and template Word .docx files" +description: "Create, read, edit, template, and review Word .docx files" --- {/* 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. */} # Docx -Create, read, edit, and template Word .docx files. +Create, read, edit, template, and review Word .docx files. ## Skill metadata | | | |---|---| | Source | Bundled (installed by default) | -| Path | `skills/productivity/docx` | -| Version | `1.0.0` | +| Path | `skills/productivity\docx` | +| Version | `1.1.0` | | Author | Nous Research | | License | MIT | | Platforms | linux, macos, windows | -| Tags | `word`, `docx`, `documents`, `office`, `templates` | +| Tags | `word`, `docx`, `documents`, `office`, `templates`, `revisions`, `comments` | | Related skills | [`pdf`](/docs/user-guide/skills/bundled/productivity/productivity-pdf), [`xlsx`](/docs/user-guide/skills/bundled/productivity/productivity-xlsx), [`powerpoint`](/docs/user-guide/skills/bundled/productivity/productivity-powerpoint) | ## Reference: full SKILL.md @@ -32,24 +32,31 @@ The following is the complete skill definition that Hermes loads when this skill # Docx Skill Create, read, edit, and template Microsoft Word `.docx` files with -python-docx via four small CLIs. It handles text, styles, lists, tables, -images, headers/footers, and `{{token}}` templating. It does not render -documents to PDF, edit legacy `.doc` binaries, or accept/reject tracked -changes (it only detects them — see Pitfalls). +python-docx via small CLIs. It handles text, styles, lists, tables, +images, headers/footers, `{{token}}` templating, tracked changes +(list/accept/reject), comments (list/add/delete), TOC and page-number +fields, and package health checks. It does not render documents itself +(PDF needs LibreOffice — see Converting to PDF) or edit legacy `.doc`. ## When to Use - The user asks to generate a Word document (report, letter, contract). - You need the text, outline, styles, or embedded images of a `.docx`. - You must change an existing `.docx`: replace text, edit table cells, - insert/delete paragraphs, apply styles. + insert/delete paragraphs, apply styles, merge fragmented runs. - You have a `.docx` template with `{{placeholders}}` to fill from data. -- Not for: `.doc` (legacy), `.odt`, PDF conversion, or WYSIWYG layout work. +- The document has tracked changes to review, accept, or reject. +- You need to read reviewers' comments, or add/delete comments. +- A `.docx` won't open or behaves oddly and you need corruption triage. +- The document needs a table of contents or "Page X of Y" footers. +- Not for: `.doc` (legacy), `.odt`, or WYSIWYG layout work. ## Prerequisites - Python 3.10+ with `python-docx` installed: - `pip install python-docx` (import name is `docx`). + `pip install python-docx` (import name is `docx`; lxml comes with it). +- Comments `add` uses the native API on python-docx >= 1.2 and an XML + fallback on older versions — both are automatic. - For image blocks: the image files must exist locally (PNG/JPEG). ## How to Run @@ -62,6 +69,9 @@ python scripts/docx_create.py spec.json out.docx python scripts/docx_read.py out.docx --text python scripts/docx_edit.py replace out.docx --find old --replace new python scripts/docx_template.py tpl.docx values.json filled.docx +python scripts/docx_revisions.py list out.docx +python scripts/docx_comments.py list out.docx +python scripts/docx_validate.py out.docx ``` ## Quick Reference @@ -79,20 +89,31 @@ python scripts/docx_template.py tpl.docx values.json filled.docx | Insert paragraph before index N | `docx_edit.py insert f.docx --index N --text X --style Normal` | | Delete paragraph N | `docx_edit.py delete f.docx --index N` | | Apply style to paragraph N | `docx_edit.py style f.docx --index N --style "Heading 1"` | +| Merge equal-format adjacent runs | `docx_edit.py normalize f.docx -o out.docx` | +| Insert TOC field before para N | `docx_edit.py toc f.docx --index N -o out.docx` | +| "Page X of Y" footer fields | `docx_edit.py page-numbers f.docx` | | Fill `{{tokens}}` | `docx_template.py tpl.docx values.json out.docx --strict` | +| List revisions (id/author/date/text) | `docx_revisions.py list f.docx` | +| Accept / reject all revisions | `docx_revisions.py accept-all f.docx -o out.docx` (or `reject-all`) | +| Accept / reject one revision | `docx_revisions.py accept f.docx --id 3 -o out.docx` | +| List comments (+anchored text) | `docx_comments.py list f.docx` | +| Add comment anchored to text | `docx_comments.py add f.docx --target "phrase" --text "note" --author You` | +| Delete comment by id | `docx_comments.py delete f.docx --id 0` | +| Health-check the package | `docx_validate.py f.docx` (exit 1 on errors) | ## Procedure 1. **Create.** Write a JSON spec with `write_file`, then run `scripts/docx_create.py`. The spec supports: `page` (size + margins in - mm), `header`/`footer` strings, `styles` (custom paragraph styles with + mm), `header`/`footer` strings, `footer_page_numbers` (adds a + "Page X of Y" field footer), `styles` (custom paragraph styles with font, size, bold/italic, hex `color`), and `blocks` — `heading` (level 1-9), `paragraph` (either `text` or a `runs` list where each run may set `bold`/`italic`/`underline`), `bullet_list`, `numbered_list`, `table` (`header` row rendered bold, `rows`, optional built-in table `style` such as `Table Grid`), `image` (`path`, optional `width_mm`), - and `page_break`. The full spec format is documented at the top of - `scripts/docx_create.py` — read it with `read_file` when composing. + `toc` (Table of Contents field), and `page_break`. The full spec + format is documented at the top of `scripts/docx_create.py`. 2. **Read.** Use `scripts/docx_read.py` with exactly one mode flag. `--text` returns body paragraphs, all table cell text, and header/footer text as JSON. `--structure` returns the heading outline @@ -102,34 +123,72 @@ python scripts/docx_template.py tpl.docx values.json filled.docx (nested included), headers and footers, and preserves run formatting; add `--body-only` to skip headers/footers. Pass `-o out.docx` to keep the original; omit it to edit in place. Paragraph indices for - `insert`/`delete`/`style` refer to `--structure`/`--text` body order. -4. **Template.** Put `{{name}}`-style tokens in the document (letters, - digits, `_`, `.`, `-`; optional inner spaces like `{{ name }}` are - accepted). Run `scripts/docx_template.py` with a JSON object of - values. Use `--strict` to fail when tokens remain unfilled; the JSON - output lists `filled` counts and `unfilled_tokens` either way. -5. **Verify** (always): re-read the output with `--text` or - `--structure` and confirm the expected content is present. + `insert`/`delete`/`style`/`toc` refer to `--structure`/`--text` body + order. Run `normalize` first on documents that came out of heavy Word + editing — it merges adjacent runs with identical formatting so later + find-replace matches reliably. +4. **Review revisions.** `docx_revisions.py list` reports every `w:ins` + and `w:del` (id, author, date, affected text) anywhere in body, + tables, headers, or footers. `accept-all` / `reject-all` resolve them + in bulk; `accept`/`reject --id N` handles a single revision. Accept + keeps insertions and drops deleted text; reject does the reverse. +5. **Comments.** `docx_comments.py list` returns each comment's id, + author, date, body text, and the document text it is anchored to. + `add --target "some phrase"` anchors a new comment to the first + occurrence of that phrase (runs are split as needed; formatting is + preserved). `delete --id N` removes the comment and its markers + without touching document text. +6. **Template.** Put `{{name}}`-style tokens in the document. Run + `scripts/docx_template.py` with a JSON object of values. Use + `--strict` to fail when tokens remain unfilled; the JSON output lists + `filled` counts and `unfilled_tokens` either way. +7. **Verify** (always): re-read the output with `--text` or + `--structure`, and run `docx_validate.py` on anything you produced + via revision/comment surgery. + +## Converting to PDF + +No script needed. When LibreOffice is installed, convert headlessly: + +```bash +soffice --headless --convert-to pdf --outdir outdir/ file.docx +``` + +Check availability first (`command -v soffice || command -v +libreoffice`). If neither exists, tell the user PDF conversion is +unavailable in this environment rather than improvising — python-docx +cannot render PDFs, and layout fidelity requires a real renderer. ## Pitfalls -- **Tokens split across runs.** Word often fragments `{{name}}` into - several runs. The replace helpers handle this by collapsing the runs; - the replacement inherits the formatting of the run where the match - starts. Mid-token formatting changes are therefore flattened. -- **Tracked changes.** `--revisions` only *detects* insertions, - deletions, format changes, and comments. Text extraction returns the - as-is body (insertions included, deletions omitted, i.e. roughly the - accepted view), but this skill cannot accept/reject revisions or read - comment text. Say so to the user rather than guessing. +- **Tokens split across runs.** Word often fragments text into several + runs. The replace helpers collapse matched runs (replacement inherits + the first run's formatting); running `docx_edit.py normalize` first + reduces fragmentation for all later edits. +- **Revision coverage.** `docx_revisions.py` resolves run-level + insertions and deletions (the overwhelming majority). Paragraph-mark + and table-row revisions, format-change records, and moves are detected + by `--revisions` but not auto-resolved — see + `references/revisions-and-comments.md` and hand those to Word. +- **Comment threading.** Replies and "resolved" status live in + `commentsExtended.xml`, which this skill ignores; comments it adds are + plain top-level comments. +- **Field results are computed by Word.** `toc`, `page-numbers`, and the + `toc`/`footer_page_numbers` spec options write *field codes*. + Word/LibreOffice populates the actual entries and numbers when the + file is opened (Word may prompt to update fields); python-docx never + computes them, so placeholder text shows until then. +- **Validation is a health check, not schema validation.** + `docx_validate.py` verifies the zip, required parts, relationship + targets, image magic bytes, and referenced styles. It is NOT XSD + validation — a file can pass and still contain XML Word dislikes. - **Style names must exist.** Applying a style that isn't defined in the document raises `KeyError`. Built-ins like `Heading 1`, `List Bullet`, `List Number`, `Table Grid` exist in the default template; custom styles must be declared in the create spec first. - **Numbered lists restart.** `List Number` relies on Word's default numbering; separate lists in one document may continue numbering - instead of restarting. Acceptable for simple docs; warn users needing - precise multi-list numbering. + instead of restarting. Warn users needing precise multi-list numbering. - **Cell writes replace formatting.** `set-cell` uses `cell.text = ...`, which resets runs in that cell to plain formatting. - **Encoding.** All JSON specs/values files are read as UTF-8 explicitly; @@ -143,8 +202,12 @@ python scripts/docx_template.py tpl.docx values.json filled.docx - After create/edit/template, run `docx_read.py out.docx --text` and check the expected strings appear (and old strings are gone). +- After accept/reject, `docx_revisions.py list` should return `[]` (or + only the ids you intentionally left); after comment surgery, + `docx_comments.py list` should reflect the change and `--text` output + must be unchanged. +- `docx_validate.py out.docx` exits 0 with `"ok": true` on a healthy + package — run it after any revision/comment/field manipulation. - For templates run with `--strict`, or check `unfilled_tokens == []`. - Structure checks: `--structure` should show the expected heading outline and table shapes; `--styles` confirms custom styles applied. -- A valid `.docx` opens with `Document(path)` without exception — the - read script exiting 0 is itself a sanity check. diff --git a/website/docs/user-guide/skills/bundled/productivity/productivity-google-workspace.md b/website/docs/user-guide/skills/bundled/productivity/productivity-google-workspace.md index 23c1245764..9e8c327674 100644 --- a/website/docs/user-guide/skills/bundled/productivity/productivity-google-workspace.md +++ b/website/docs/user-guide/skills/bundled/productivity/productivity-google-workspace.md @@ -15,7 +15,7 @@ Gmail, Calendar, Drive, Docs, Sheets via gws CLI or Python. | | | |---|---| | Source | Bundled (installed by default) | -| Path | `skills/productivity/google-workspace` | +| Path | `skills/productivity\google-workspace` | | Version | `1.2.0` | | Author | Nous Research | | License | MIT | diff --git a/website/docs/user-guide/skills/bundled/productivity/productivity-maps.md b/website/docs/user-guide/skills/bundled/productivity/productivity-maps.md index 7fdc002cc3..d6ff985af3 100644 --- a/website/docs/user-guide/skills/bundled/productivity/productivity-maps.md +++ b/website/docs/user-guide/skills/bundled/productivity/productivity-maps.md @@ -15,7 +15,7 @@ Geocode, POIs, routes, timezones via OpenStreetMap/OSRM. | | | |---|---| | Source | Bundled (installed by default) | -| Path | `skills/productivity/maps` | +| Path | `skills/productivity\maps` | | Version | `1.2.0` | | Author | Mibayy | | License | MIT | @@ -65,8 +65,8 @@ MAPS=~/.hermes/skills/maps/scripts/maps_client.py ### search — Geocode a place name ```bash -python3 $MAPS search "Eiffel Tower" -python3 $MAPS search "1600 Pennsylvania Ave, Washington DC" +python $MAPS search "Eiffel Tower" +python $MAPS search "1600 Pennsylvania Ave, Washington DC" ``` Returns: lat, lon, display name, type, bounding box, importance score. @@ -74,7 +74,7 @@ Returns: lat, lon, display name, type, bounding box, importance score. ### reverse — Coordinates to address ```bash -python3 $MAPS reverse 48.8584 2.2945 +python $MAPS reverse 48.8584 2.2945 ``` Returns: full address breakdown (street, city, state, country, postcode). @@ -83,15 +83,15 @@ Returns: full address breakdown (street, city, state, country, postcode). ```bash # By coordinates (from a Telegram location pin, for example) -python3 $MAPS nearby 48.8584 2.2945 restaurant --limit 10 -python3 $MAPS nearby 40.7128 -74.0060 hospital --radius 2000 +python $MAPS nearby 48.8584 2.2945 restaurant --limit 10 +python $MAPS nearby 40.7128 -74.0060 hospital --radius 2000 # By address / city / zip / landmark — --near auto-geocodes -python3 $MAPS nearby --near "Times Square, New York" --category cafe -python3 $MAPS nearby --near "90210" --category pharmacy +python $MAPS nearby --near "Times Square, New York" --category cafe +python $MAPS nearby --near "90210" --category pharmacy # Multiple categories merged into one query -python3 $MAPS nearby --near "downtown austin" --category restaurant --category bar --limit 10 +python $MAPS nearby --near "downtown austin" --category restaurant --category bar --limit 10 ``` 46 categories: restaurant, cafe, bar, hospital, pharmacy, hotel, guest_house, @@ -110,9 +110,9 @@ directions from the search point), and promoted tags when available — ### distance — Travel distance and time ```bash -python3 $MAPS distance "Paris" --to "Lyon" -python3 $MAPS distance "New York" --to "Boston" --mode driving -python3 $MAPS distance "Big Ben" --to "Tower Bridge" --mode walking +python $MAPS distance "Paris" --to "Lyon" +python $MAPS distance "New York" --to "Boston" --mode driving +python $MAPS distance "Big Ben" --to "Tower Bridge" --mode walking ``` Modes: driving (default), walking, cycling. Returns road distance, duration, @@ -121,8 +121,8 @@ and straight-line distance for comparison. ### directions — Turn-by-turn navigation ```bash -python3 $MAPS directions "Eiffel Tower" --to "Louvre Museum" --mode walking -python3 $MAPS directions "JFK Airport" --to "Times Square" --mode driving +python $MAPS directions "Eiffel Tower" --to "Louvre Museum" --mode walking +python $MAPS directions "JFK Airport" --to "Times Square" --mode driving ``` Returns numbered steps with instruction, distance, duration, road name, and @@ -131,8 +131,8 @@ maneuver type (turn, depart, arrive, etc.). ### timezone — Timezone for coordinates ```bash -python3 $MAPS timezone 48.8584 2.2945 -python3 $MAPS timezone 35.6762 139.6503 +python $MAPS timezone 48.8584 2.2945 +python $MAPS timezone 35.6762 139.6503 ``` Returns timezone name, UTC offset, and current local time. @@ -140,8 +140,8 @@ Returns timezone name, UTC offset, and current local time. ### area — Bounding box and area for a place ```bash -python3 $MAPS area "Manhattan, New York" -python3 $MAPS area "London" +python $MAPS area "Manhattan, New York" +python $MAPS area "London" ``` Returns bounding box coordinates, width/height in km, and approximate area. @@ -150,7 +150,7 @@ Useful as input for the bbox command. ### bbox — Search within a bounding box ```bash -python3 $MAPS bbox 40.75 -74.00 40.77 -73.98 restaurant --limit 20 +python $MAPS bbox 40.75 -74.00 40.77 -73.98 restaurant --limit 20 ``` Finds POIs within a geographic rectangle. Use `area` first to get the @@ -163,7 +163,7 @@ When a user sends a location pin, the message contains `latitude:` and ```bash # User sent a pin at 36.17, -115.14 and asked "find cafes nearby" -python3 $MAPS nearby 36.17 -115.14 cafe --radius 1500 +python $MAPS nearby 36.17 -115.14 cafe --radius 1500 ``` Present results as a numbered list with names, distances, and the @@ -202,9 +202,9 @@ current. ## Verification ```bash -python3 ~/.hermes/skills/maps/scripts/maps_client.py search "Statue of Liberty" +python ~/.hermes/skills/maps/scripts/maps_client.py search "Statue of Liberty" # Should return lat ~40.689, lon ~-74.044 -python3 ~/.hermes/skills/maps/scripts/maps_client.py nearby --near "Times Square" --category restaurant --limit 3 +python ~/.hermes/skills/maps/scripts/maps_client.py nearby --near "Times Square" --category restaurant --limit 3 # Should return a list of restaurants within ~500m of Times Square ``` diff --git a/website/docs/user-guide/skills/bundled/productivity/productivity-meeting-action-items.md b/website/docs/user-guide/skills/bundled/productivity/productivity-meeting-action-items.md index ce07cee2bc..1a595783f4 100644 --- a/website/docs/user-guide/skills/bundled/productivity/productivity-meeting-action-items.md +++ b/website/docs/user-guide/skills/bundled/productivity/productivity-meeting-action-items.md @@ -15,7 +15,7 @@ Turn meeting notes into cited decisions, owners, tickets. | | | |---|---| | Source | Bundled (installed by default) | -| Path | `skills/productivity/meeting-action-items` | +| Path | `skills/productivity\meeting-action-items` | | Version | `0.1.0` | | Author | Ben Barclay (benbarclay), Hermes Agent | | License | MIT | diff --git a/website/docs/user-guide/skills/bundled/productivity/productivity-notion.md b/website/docs/user-guide/skills/bundled/productivity/productivity-notion.md index 985240ca41..1bfcdec700 100644 --- a/website/docs/user-guide/skills/bundled/productivity/productivity-notion.md +++ b/website/docs/user-guide/skills/bundled/productivity/productivity-notion.md @@ -15,7 +15,7 @@ Notion API + ntn CLI: pages, databases, markdown, Workers. | | | |---|---| | Source | Bundled (installed by default) | -| Path | `skills/productivity/notion` | +| Path | `skills/productivity\notion` | | Version | `2.0.0` | | Author | community | | License | MIT | diff --git a/website/docs/user-guide/skills/bundled/productivity/productivity-pdf.md b/website/docs/user-guide/skills/bundled/productivity/productivity-pdf.md index 20950d56e4..a375340613 100644 --- a/website/docs/user-guide/skills/bundled/productivity/productivity-pdf.md +++ b/website/docs/user-guide/skills/bundled/productivity/productivity-pdf.md @@ -1,27 +1,27 @@ --- -title: "Pdf — Create, read, merge, fill, and secure PDF files" +title: "Pdf — PDF files: create, read, merge, fill, OCR, edit text" sidebar_label: "Pdf" -description: "Create, read, merge, fill, and secure PDF files" +description: "PDF files: create, read, merge, fill, OCR, edit text" --- {/* 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. */} # Pdf -Create, read, merge, fill, and secure PDF files. +PDF files: create, read, merge, fill, OCR, edit text. ## Skill metadata | | | |---|---| | Source | Bundled (installed by default) | -| Path | `skills/productivity/pdf` | -| Version | `1.0.0` | +| Path | `skills/productivity\pdf` | +| Version | `1.1.0` | | Author | Nous Research | | License | MIT | | Platforms | linux, macos, windows | -| Tags | `pdf`, `documents`, `forms`, `reportlab`, `pypdf`, `pdfplumber` | -| Related skills | [`docx`](/docs/user-guide/skills/bundled/productivity/productivity-docx), [`xlsx`](/docs/user-guide/skills/bundled/productivity/productivity-xlsx), [`powerpoint`](/docs/user-guide/skills/bundled/productivity/productivity-powerpoint), [`ocr-and-documents`](/docs/user-guide/skills/bundled/productivity/productivity-ocr-and-documents) | +| Tags | `pdf`, `documents`, `forms`, `ocr`, `text-extraction`, `reportlab`, `pypdf`, `pdfplumber`, `pymupdf`, `marker` | +| Related skills | [`docx`](/docs/user-guide/skills/bundled/productivity/productivity-docx), [`xlsx`](/docs/user-guide/skills/bundled/productivity/productivity-xlsx), [`powerpoint`](/docs/user-guide/skills/bundled/productivity/productivity-powerpoint) | ## Reference: full SKILL.md @@ -31,20 +31,26 @@ The following is the complete skill definition that Hermes loads when this skill # PDF Skill -Create PDFs from structured specs, extract text/tables/metadata, merge/split/rotate/watermark pages, fill AcroForm form fields, and encrypt/decrypt — using pypdf, reportlab, and pdfplumber. Scanned (image-only) PDFs contain no text layer: OCR is explicitly out of scope here — when a page is image-only, stop and use the `ocr-and-documents` skill instead of pretending to extract text. +Create PDFs from structured specs, build and fill AcroForm forms (with layout linting and visual overlays), extract text/tables/metadata, merge/split/rotate/watermark/stamp pages, export page images, manage metadata and attachments, and encrypt/decrypt — using pypdf, reportlab, and pdfplumber. Two absorbed capabilities live in references/ (read the matching file before those tasks): + +- **Scanned/image-only PDFs and OCR** (pymupdf fast path, marker-pdf quality path, scripts/extract_pymupdf.py + scripts/extract_marker.py): `references/ocr-extraction.md` +- **Editing text inside an existing PDF via natural-language prompts** (nano-pdf CLI): `references/nano-pdf-editing.md` ## When to Use - Generate a report, invoice, or multi-page document as PDF. +- Build a fillable AcroForm (text/checkbox/radio/dropdown) from a JSON spec, linting the layout first. - Pull text, tables (JSON/CSV), metadata, or form-field values out of a PDF. -- Merge, split, rotate, extract page subsets, watermark, bookmark, or compress PDFs. +- Merge, split, rotate, extract page subsets, watermark, stamp text/images at coordinates, bookmark, or compress PDFs. +- Export pages as PNGs for visual review or for OCR hand-off; set/clear document metadata; add/extract file attachments. - Fill or flatten AcroForm forms; encrypt or decrypt with passwords. -- NOT for scanned/image-only PDFs (use `ocr-and-documents`) and NOT for pixel-perfect HTML-to-PDF rendering (use a headless browser). +- NOT for scanned/image-only PDFs (use `references/ocr-extraction.md`) and NOT for pixel-perfect HTML-to-PDF rendering (use a headless browser). ## Prerequisites - Python 3.10+ with `pypdf`, `reportlab`, `pdfplumber`: - `python3 -m pip install pypdf reportlab pdfplumber` + `python -m pip install pypdf reportlab pdfplumber` +- Optional, for page rasterization (`pdf_page_image.py`, overlay rendering): `python -m pip install pypdfium2`, or poppler's `pdftoppm` on PATH. Scripts fall back pypdfium2 → pdftoppm and report `{"rendered": false, "missing": [...]}` (exit 0) when neither exists. - Each helper script checks imports lazily and prints an install hint if a dependency is missing. ## How to Run @@ -52,17 +58,27 @@ Create PDFs from structured specs, extract text/tables/metadata, merge/split/rot All helpers live in `scripts/` and are argparse CLIs — run them with the `terminal` tool; every one supports `--help`. They read/write JSON strictly as UTF-8, print JSON results to stdout, and exit non-zero on failure. ```bash -python3 scripts/pdf_create.py spec.json -o out.pdf # build PDF from JSON spec -python3 scripts/pdf_read.py doc.pdf --text # per-page text (JSON) -python3 scripts/pdf_read.py doc.pdf --tables --csv-dir t/ # tables to JSON + CSV files -python3 scripts/pdf_read.py doc.pdf --meta # metadata, page sizes, encrypted/scanned flags -python3 scripts/pdf_read.py form.pdf --fields # form fields: name, type, value -python3 scripts/pdf_merge.py a.pdf b.pdf -o merged.pdf [--bookmarks] -python3 scripts/pdf_split.py doc.pdf --pages 1-3,7 -o part.pdf [--rotate 90] -python3 scripts/pdf_fill_form.py form.pdf --fields-json values.json -o filled.pdf [--flatten] -python3 scripts/pdf_secure.py doc.pdf --encrypt -o enc.pdf --user-password your-password -python3 scripts/pdf_secure.py enc.pdf --decrypt -o dec.pdf --password your-password -python3 scripts/pdf_watermark.py doc.pdf --stamp mark.pdf -o stamped.pdf [--under] +python scripts/pdf_create.py spec.json -o out.pdf # build PDF from JSON spec +python scripts/pdf_make_form.py formspec.json -o form.pdf # build fillable AcroForm from JSON spec +python scripts/pdf_form_layout.py formspec.json # lint form layout BEFORE building +python scripts/pdf_form_layout.py formspec.json --render-overlay boxes.png [--pdf form.pdf] +python scripts/pdf_read.py doc.pdf --text # per-page text (JSON) +python scripts/pdf_read.py doc.pdf --tables --csv-dir t/ # tables to JSON + CSV files +python scripts/pdf_read.py doc.pdf --meta # metadata, page sizes, encrypted/scanned flags +python scripts/pdf_read.py form.pdf --fields # form fields: name, type, value +python scripts/pdf_merge.py a.pdf b.pdf -o merged.pdf [--bookmarks] +python scripts/pdf_split.py doc.pdf --pages 1-3,7 -o part.pdf [--rotate 90] +python scripts/pdf_fill_form.py form.pdf --fields-json values.json -o filled.pdf [--flatten] +python scripts/pdf_secure.py doc.pdf --encrypt -o enc.pdf --user-password your-password +python scripts/pdf_secure.py enc.pdf --decrypt -o dec.pdf --password your-password +python scripts/pdf_watermark.py doc.pdf --stamp mark.pdf -o stamped.pdf [--under] +python scripts/pdf_stamp.py doc.pdf -o out.pdf --text "DRAFT" --x 150 --y 400 \ + --font-size 60 --rotation 45 --opacity 0.3 --color "#cc0000" [--pages 1-3] +python scripts/pdf_stamp.py doc.pdf -o out.pdf --image sig.png --x 400 --y 60 --width 120 +python scripts/pdf_page_image.py doc.pdf --pages 1-3 --dpi 150 --out-dir imgs/ +python scripts/pdf_meta.py doc.pdf --set-meta --title "T" --author "A" -o out.pdf +python scripts/pdf_meta.py doc.pdf --attach data.csv -o out.pdf +python scripts/pdf_meta.py doc.pdf --list-attachments | --extract-attachments dir/ ``` ## Quick Reference @@ -70,6 +86,8 @@ python3 scripts/pdf_watermark.py doc.pdf --stamp mark.pdf -o stamped.pdf [--unde | Task | Tool | Command / API | |---|---|---| | Create doc (headings, tables, images) | reportlab platypus | `pdf_create.py spec.json -o out.pdf` | +| Build fillable form | reportlab acroForm | `pdf_make_form.py formspec.json -o form.pdf` | +| Lint form layout / overlay image | pure python + PIL | `pdf_form_layout.py formspec.json [--render-overlay o.png]` | | Per-page text | pdfplumber | `pdf_read.py f.pdf --text` | | Tables → JSON/CSV | pdfplumber | `pdf_read.py f.pdf --tables` | | Metadata / sizes / encrypted / scanned | pypdf + pdfplumber | `pdf_read.py f.pdf --meta` | @@ -77,22 +95,27 @@ python3 scripts/pdf_watermark.py doc.pdf --stamp mark.pdf -o stamped.pdf [--unde | Split / extract / rotate | pypdf | `pdf_split.py f.pdf --pages 2-5 --rotate 90` | | List / fill / flatten form | pypdf | `pdf_read.py --fields`, `pdf_fill_form.py` | | Encrypt / decrypt (AES-256) | pypdf | `pdf_secure.py --encrypt/--decrypt` | -| Watermark / stamp | pypdf | `pdf_watermark.py f.pdf --stamp w.pdf` | +| Watermark / stamp PDF page | pypdf | `pdf_watermark.py f.pdf --stamp w.pdf` | +| Stamp text/image at coordinates | reportlab + pypdf | `pdf_stamp.py f.pdf --text "Sign here" --x 400 --y 60` | +| Pages → PNG (review / OCR hand-off) | pypdfium2 or pdftoppm | `pdf_page_image.py f.pdf --pages 1-3 --out-dir imgs/` | +| Set/clear metadata, attachments | pypdf | `pdf_meta.py --set-meta / --attach / --extract-attachments` | | Compress content streams | pypdf | `pdf_split.py f.pdf --pages 1-N --compress` | ## Procedure -1. **Inspect first.** Run `pdf_read.py file.pdf --meta`. Check `encrypted` (if true, decrypt first with `pdf_secure.py --decrypt`) and `likely_scanned_pages`. If pages are image-only, hand off to the `ocr-and-documents` skill — do not report empty text as "no content". +1. **Inspect first.** Run `pdf_read.py file.pdf --meta`. Check `encrypted` (if true, decrypt first with `pdf_secure.py --decrypt`) and `likely_scanned_pages`. If pages are image-only, export them with `pdf_page_image.py --pages <scanned> --dpi 300 --out-dir imgs/` and hand the PNGs to the `references/ocr-extraction.md` skill — do not report empty text as "no content". 2. **Create.** Write a JSON spec with `write_file` (elements: `heading`, `paragraph`, `table`, `image`, `pagebreak`; optional `title`/`author` metadata; page numbers are added automatically), then run `pdf_create.py`. Verify visually with `vision_analyze` on a rendered page image if layout matters. 3. **Extract.** `--text` gives a JSON list of per-page strings; `--tables` gives row arrays per page and can also emit CSV files. Read results with `read_file`; never eyeball a binary PDF directly. -4. **Manipulate.** `pdf_merge.py` concatenates and can add one bookmark per source file; `pdf_split.py` handles page ranges (1-based, e.g. `1-3,5,9-`), rotation in 90° steps, and `--compress`. Watermark by preparing a single-page stamp PDF (e.g. via `pdf_create.py`) and overlaying it with `pdf_watermark.py`. -5. **Forms.** List fields (`--fields`) to learn exact names and types, write a UTF-8 JSON of `{"FieldName": "value"}` with `write_file` (checkboxes accept `true`/`false`; radio/choice values must match the field's export options), then `pdf_fill_form.py`. Re-read with `--fields` to confirm values landed. -6. **Secure.** Encrypt with distinct user/owner passwords and AES-256. To remove a password you know, `--decrypt` writes an unencrypted copy. -7. **Verify** (see below) before reporting success. +4. **Manipulate.** `pdf_merge.py` concatenates and can add one bookmark per source file; `pdf_split.py` handles page ranges (1-based, e.g. `1-3,5,9-`), rotation in 90° steps, and `--compress`. Watermark by preparing a single-page stamp PDF (e.g. via `pdf_create.py`) and overlaying it with `pdf_watermark.py`; for one-liner stamps ("sign here", diagonal DRAFT, corner labels) use `pdf_stamp.py` with text or an image at explicit coordinates. +5. **Build forms.** Write one form-spec JSON (fields with `label_box`/`entry_box` in PDF points — see `references/forms.md`), lint it with `pdf_form_layout.py` and fix every reported problem, optionally review the `--render-overlay` PNG with `vision_analyze`, then build with `pdf_make_form.py` and confirm with `pdf_read.py --fields`. +6. **Fill forms.** List fields (`--fields`) to learn exact names and types, write a UTF-8 JSON of `{"FieldName": "value"}` with `write_file` (checkboxes accept `true`/`false`; radio/choice values must match the field's export options), then `pdf_fill_form.py`. Re-read with `--fields` to confirm values landed. +7. **Metadata & attachments.** `pdf_meta.py --set-meta` writes Title/Author/Subject/Keywords (DocInfo); `--clear-meta` drops them; `--attach`/`--list-attachments`/`--extract-attachments` round-trip embedded files. +8. **Secure.** Encrypt with distinct user/owner passwords and AES-256. To remove a password you know, `--decrypt` writes an unencrypted copy. +9. **Verify** (see below) before reporting success. ## Pitfalls -- **Scanned PDFs**: empty `extract_text()` plus page images means there is no text layer. Route to `ocr-and-documents`; do not fabricate text. +- **Scanned PDFs**: empty `extract_text()` plus page images means there is no text layer. Route to `references/ocr-extraction.md`; do not fabricate text. - **Flattening limits**: `pdf_fill_form.py --flatten` uses pypdf's flatten support, which converts widget appearances into page content. It is reliable for plain text fields and checkboxes but can drop or misrender exotic widgets (rich text, custom appearance streams, some radio groups). Verify the flattened output visually with `vision_analyze`; for bulletproof flattening use an external renderer (e.g. Ghostscript or `pdftoppm`+reassembly) as a fallback. - **NeedAppearances**: after filling, viewers only render values if appearance streams exist. The fill script sets the AcroForm `NeedAppearances` flag so conforming viewers regenerate them; some minimal viewers ignore it — flatten if display fidelity matters. - **Non-Latin form values**: values are stored correctly (UTF-16), but the field's default font may lack glyphs, so a viewer can show blanks even though the data round-trips. Verify with `--fields`, not just visually. @@ -100,12 +123,20 @@ python3 scripts/pdf_watermark.py doc.pdf --stamp mark.pdf -o stamped.pdf [--unde - **Permission flags don't enforce**: owner-password permission bits (no-print, no-copy) are polite requests that viewers may honor; any library (including pypdf) can read and strip them. Only the user password actually gates content via encryption. Never present permission flags as security. - **Table extraction is heuristic**: pdfplumber detects tables from ruling lines/word alignment; borderless or merged-cell tables may need `table_settings` tuning or manual cleanup. - **Page indexing**: helper CLIs take 1-based pages; pypdf APIs are 0-based. The scripts convert — don't double-convert. +- **Rotated stamp text extraction**: pdfplumber's line grouping scrambles rotated glyphs (a 45° "DRAFT" extracts as stray letters); verify rotated stamps with `pypdf`'s `extract_text()` or a rendered image instead. +- **Radio groups**: reportlab needs ≥2 `radio()` widgets per group, fills need the slashed export value (`"/red"`), and flatten fidelity is worst for radios — see `references/forms.md`. +- **Metadata scope**: `pdf_meta.py` writes the classic DocInfo dictionary only; embedded XMP metadata (if any) is left untouched and may show different values in some viewers. +- **PDF/A is out of scope**: pypdf/reportlab cannot produce or validate conformant PDF/A. If archival conformance is required, run Ghostscript via the `terminal` tool (e.g. `gs -dPDFA=2 -dPDFACompatibilityPolicy=1 -sColorConversionStrategy=UseDeviceIndependentColor -sDEVICE=pdfwrite -o out.pdf in.pdf` with a suitable ICC profile) and validate with veraPDF — both are external installs, and the result still needs validation, not assumption. - Rotation must be a multiple of 90; encrypted inputs must be decrypted before any other operation. ## Verification - After create/merge/split: `pdf_read.py out.pdf --meta` — confirm `page_count`, and per-page `rotation` when you rotated. - After extraction: check the JSON is non-empty and spot-check a known string or cell. +- Form design loop: `pdf_form_layout.py spec.json` must exit 0; then `--render-overlay boxes.png --pdf form.pdf` and review the PNG with `vision_analyze` (red = entry boxes with field names, blue = label boxes) asking about overlaps, misalignment, and labels detached from their fields. Iterate spec → lint → overlay until clean. +- After building a form: `pdf_read.py form.pdf --fields` lists every spec field with the right type and options. - After form fill: `pdf_read.py filled.pdf --fields` and compare values (exact match, including non-ASCII). +- After stamping: re-extract text (pypdf for rotated stamps) or render the page with `pdf_page_image.py` and inspect with `vision_analyze`. +- After metadata/attachment edits: `pdf_read.py --meta` / `pdf_meta.py --list-attachments`, and re-extract an attachment to byte-compare. - After encrypt: `--meta` shows `"encrypted": true` and opening without a password fails; after decrypt, text extraction matches the original. - For anything visual (watermarks, flattened forms), render and inspect with `vision_analyze`. diff --git a/website/docs/user-guide/skills/bundled/productivity/productivity-powerpoint.md b/website/docs/user-guide/skills/bundled/productivity/productivity-powerpoint.md index fad7d26eaf..72e4dc8e75 100644 --- a/website/docs/user-guide/skills/bundled/productivity/productivity-powerpoint.md +++ b/website/docs/user-guide/skills/bundled/productivity/productivity-powerpoint.md @@ -15,8 +15,8 @@ Create, read, edit .pptx decks with python-pptx. | | | |---|---| | Source | Bundled (installed by default) | -| Path | `skills/productivity/powerpoint` | -| Version | `1.0.0` | +| Path | `skills/productivity\powerpoint` | +| Version | `1.1.0` | | Author | Nous Research | | License | MIT | | Platforms | linux, macos, windows | @@ -32,17 +32,18 @@ The following is the complete skill definition that Hermes loads when this skill # Powerpoint Skill Create, inspect, and edit PowerPoint (.pptx) presentations using the -python-pptx library. Four helper scripts cover deck creation from a JSON -spec, structured read-back, in-place edits, and template-driven brand -decks — all offline, no PowerPoint installation required. +python-pptx library. Five helper scripts cover deck creation from a JSON +spec, structured read-back, in-place edits, template-driven brand decks, +and slide rendering — all offline, no PowerPoint installation required. ## When to Use - The user asks to build a slide deck, report presentation, or pitch deck. - You need to extract text, notes, tables, chart data, or images from a .pptx someone shared. -- You need to update an existing deck: replace text, refresh chart data, - swap a logo, remove or reorder slides. +- You need to update an existing deck: replace text, refresh or patch + chart data, swap a logo, duplicate/remove/reorder slides, set + backgrounds, footers, hyperlinks, or speaker notes. - You must produce an on-brand deck from a company .pptx template. - Do NOT use this for .ppt (legacy binary) files — convert them first with `soffice --convert-to pptx old.ppt` if LibreOffice is available. @@ -50,13 +51,14 @@ decks — all offline, no PowerPoint installation required. ## Prerequisites - Python 3.10+ with `python-pptx` installed - (`pip install python-pptx`). Pillow is optional (only if you need to - probe image dimensions yourself). -- Optional: LibreOffice (`soffice`) for rendering slides to images for - visual verification. Degrade gracefully if absent — all create/read/edit - operations work without it. + (`pip install python-pptx`). +- Optional: LibreOffice (`soffice`) plus poppler (`pdftoppm` or + `pdftocairo`) for rendering slides to PNGs and for PDF export. + `pptx_render.py` detects both with `shutil.which` and degrades + gracefully (reports `{"rendered": false, "missing": [...]}`, exit 0) + when absent — all create/read/edit operations work without them. - Check availability via `terminal`: - `python3 -c "import pptx; print(pptx.__version__)"` and `which soffice`. + `python -c "import pptx; print(pptx.__version__)"` and `which soffice pdftoppm`. ## How to Run @@ -64,14 +66,16 @@ All scripts live in `scripts/`, take `--help`, print JSON to stdout, and exit non-zero on failure. Run them with `terminal`: ```bash -python3 scripts/pptx_create.py deck.json out.pptx -python3 scripts/pptx_read.py deck.pptx --outline # full JSON outline -python3 scripts/pptx_read.py deck.pptx --notes # speaker notes -python3 scripts/pptx_read.py deck.pptx --images ./img # export pictures -python3 scripts/pptx_edit.py deck.pptx --replace-text "Old Corp" "New Corp" -python3 scripts/pptx_edit.py deck.pptx --chart-data update.json -python3 scripts/pptx_edit.py deck.pptx --remove-slide 3 --move-slide 2 0 -python3 scripts/pptx_from_template.py brand.pptx out.pptx --values vals.json +python scripts/pptx_create.py deck.json out.pptx +python scripts/pptx_read.py deck.pptx --outline # full JSON outline +python scripts/pptx_read.py deck.pptx --notes # speaker notes +python scripts/pptx_read.py deck.pptx --images ./img # export pictures +python scripts/pptx_edit.py deck.pptx --replace-text "Old Corp" "New Corp" +python scripts/pptx_edit.py deck.pptx --chart-data update.json +python scripts/pptx_edit.py deck.pptx --duplicate-slide 2 +python scripts/pptx_edit.py deck.pptx --remove-slide 3 --move-slide 2 0 +python scripts/pptx_from_template.py brand.pptx out.pptx --values vals.json +python scripts/pptx_render.py deck.pptx --outdir ./render # slide PNGs ``` Author JSON specs with `write_file`; inspect script output and generated @@ -86,11 +90,20 @@ JSON with `read_file`. | Outline as JSON | `pptx_read.py deck.pptx --outline` | | Export images | `pptx_read.py deck.pptx --images DIR` | | Replace text | `pptx_edit.py deck.pptx --replace-text OLD NEW` | -| Update chart | `pptx_edit.py deck.pptx --chart-data spec.json` | +| Replace chart data | `pptx_edit.py deck.pptx --chart-data spec.json` | +| Patch one series | same flag, spec with `"ops"` (see below) | | Swap picture | `pptx_edit.py deck.pptx --swap-image N NAME new.png` | +| Duplicate slide | `pptx_edit.py deck.pptx --duplicate-slide N` | | Remove slide | `pptx_edit.py deck.pptx --remove-slide N` | | Reorder slide | `pptx_edit.py deck.pptx --move-slide FROM TO` | +| Slide background | `pptx_edit.py deck.pptx --set-background N RRGGBB` | +| Hyperlink runs | `pptx_edit.py deck.pptx --hyperlink N TEXT URL` | +| Slide number on | `pptx_edit.py deck.pptx --enable-slide-number N` | +| Footer text | `pptx_edit.py deck.pptx --set-footer N TEXT` | +| Set notes | `pptx_edit.py deck.pptx --set-notes N TEXT` | +| Append notes | `pptx_edit.py deck.pptx --append-notes N TEXT` | | Fill template | `pptx_from_template.py tpl.pptx out.pptx --values v.json` | +| Render slide PNGs | `pptx_render.py deck.pptx --outdir DIR` | ## Procedure @@ -100,11 +113,14 @@ Write a JSON spec (see `pptx_create.py --help` for the full format), then run `pptx_create.py`. Per slide you can set: `layout` (title, title_content, section, two_content, title_only, blank), `title`, `subtitle`, `bullets` (strings, or dicts with `level` 0-4, `size` pt, -`bold`, `italic`, `font`, `color` hex), `images` (path + left/top/width/ -height in inches), `tables` (`rows` as list-of-lists), `shapes` -(rectangle, rounded_rectangle, oval, diamond, right_arrow, chevron, with -`fill` hex + optional `text`), `charts` (bar, bar_h, line, pie with -`categories` + `series`), and `notes` (speaker notes). +`bold`, `italic`, `font`, `color` hex, `link` URL for a hyperlink), +`background` (solid hex), `footer` (text; enables the layout's footer +placeholder), `slide_number` (true; enables the layout's slide-number +placeholder), `images` (path + left/top/width/height in inches), `tables` +(`rows` as list-of-lists), `shapes` (rectangle, rounded_rectangle, oval, +diamond, right_arrow, chevron, with `fill` hex + optional `text`), +`charts` (bar, bar_h, line, pie with `categories` + `series`), and +`notes` (speaker notes). ### 2. Read a deck @@ -118,12 +134,27 @@ Use `--images DIR` to dump embedded pictures to files, then `pptx_edit.py` combines operations in one pass; use `--output` to keep the original. Text replacement scans slide shapes, table cells, and notes. -Chart update uses `chart.replace_data()` with a JSON spec naming the -slide/chart index and new categories/series. Image swap retargets the -picture's relationship id so position and size are preserved. Slide -removal drops the relationship and the `<p:sldId>` entry; reorder moves -the `<p:sldId>` element within `<p:sldIdLst>` (python-pptx has no public -API for either — the script does the XML-level work). +Image swap retargets the picture's relationship id so position and size +are preserved. Slide removal drops the relationship and the `<p:sldId>` +entry; reorder moves the `<p:sldId>` element within `<p:sldIdLst>` +(python-pptx has no public API for either — the script does the XML-level +work). `--duplicate-slide N` appends an independent deep copy of slide N: +shape XML plus image/media/hyperlink relationships are cloned and rIds +remapped, so editing the copy never touches the original. Chart slides +are refused (see Pitfalls). `--set-notes`/`--append-notes` edit speaker +notes; `--set-background`, `--hyperlink`, `--enable-slide-number`, and +`--set-footer` handle deck polish. + +Chart updates take a JSON spec via `--chart-data`. Full replace: +`{"slide": 0, "chart": 0, "categories": [...], "series": {...}}`. For +surgical edits, pass `"ops"` instead — a list of +`{"op": "update_series", "name": ..., "values": [...]}`, +`add_series`, `remove_series`, `rename_category` (`from`/`to` or +`index`), and `set_title`. python-pptx can only swap a chart's entire +dataset (`replace_data`), so ops are implemented as read-existing → +modify → replace; the per-part UX is a wrapper, and any chart data not +expressible as categories + numeric series will be normalized by the +round-trip. ### 4. Build from a template @@ -134,36 +165,56 @@ so they inherit the master's fonts and colors. Tip: to start from a template with zero slides, delete existing ones afterward with `pptx_edit.py --remove-slide`. -### 5. Visual verification (optional) +### 5. Visual verification -If `soffice` exists, render slides to PNG and inspect with -`vision_analyze`: +`pptx_render.py deck.pptx --outdir ./render` converts the deck to PDF +with `soffice --headless` and splits it into one PNG per slide with +`pdftoppm` (or `pdftocairo`). Output JSON lists the PNG paths — review +each with `vision_analyze`. When either tool is missing the script exits +0 with `{"rendered": false, "missing": [...]}` and guidance; fall back to +the JSON outline from `pptx_read.py`, which verifies content and +structure, just not visuals. + +## Converting to PDF + +If LibreOffice is installed, export the finished deck to PDF directly: ```bash -soffice --headless --convert-to png --outdir ./render deck.pptx # slide 1 -soffice --headless --convert-to pdf --outdir ./render deck.pptx # all slides +soffice --headless --convert-to pdf --outdir ./out deck.pptx ``` -PNG export renders only the first slide; convert to PDF for all slides -(then `pdftoppm -png render/deck.pdf render/slide` if poppler is -available). When `soffice` is absent, rely on the JSON outline from -`pptx_read.py` — it verifies content and structure, just not visuals. +The output lands at `./out/deck.pdf`. Fonts not installed on the host are +substituted, so render-verify (Procedure step 5) before shipping the PDF. +There is no offline pure-Python .pptx→PDF path; if `soffice` is absent, +say so rather than approximating. ## Pitfalls -- **Run splitting**: PowerPoint fragments paragraph text into multiple - runs at spell-check and formatting boundaries. `--replace-text` - preserves formatting exactly when a match lies within one run; when the - match spans runs, the paragraph is rewritten with only the first run's - formatting. Verify important slides after replacement. +- **Run splitting**: PowerPoint fragments paragraph text into runs at + spell-check and edit boundaries. `--replace-text` first merges adjacent + runs whose formatting is identical, so matches split across such runs + are replaced with formatting fully preserved. Only when a match spans + *genuinely differently-formatted* runs is the paragraph rewritten with + the first run's formatting — verify those slides after replacement. +- **Chart slides cannot be duplicated**: each chart relationship embeds a + separate XLSX workbook part; cloning that graph reliably is not + supported, so `--duplicate-slide` refuses chart slides cleanly instead + of corrupting the deck. Rebuild the chart on a new slide instead. + External-hyperlink and image/media rels are carried over; layout and + notes rels are recreated fresh. +- **Chart ops are a wrapper**: python-pptx replaces the whole dataset; + `"ops"` round-trips existing plot data through `replace_data`, and + changing chart *type* is not possible. - **Reordering is XML-level**: python-pptx has no supported reorder API. - `--move-slide` manipulates `<p:sldIdLst>` directly; it is safe for - ordinary decks but re-read the deck afterward to confirm. -- **Copying slides between decks is unsupported** — layouts, images, and - relationships would need deep cloning. Rebuild the slide in the target - deck instead. -- Chart edits replace the whole data set; you cannot patch a single cell. - Adding/removing series works, but changing chart *type* does not. + `--move-slide` manipulates `<p:sldIdLst>` directly; safe for ordinary + decks but re-read the deck afterward to confirm. +- **Copying slides between decks is unsupported** — duplication works + only within one deck, where layouts and masters are shared. +- Footer/slide-number enablement copies the placeholder from the slide's + layout; on layouts without those placeholders, `--set-footer` fails + with a clear message (add a textbox instead). +- Hyperlinks apply to whole runs; `--hyperlink` links every run + containing the given text on that slide. - The default python-pptx template is 4:3; the create script sets 16:9 unless the spec says otherwise. Custom templates keep their own size. - Layout indexes vary by template. For brand templates, list layout names @@ -178,7 +229,9 @@ available). When `soffice` is absent, rely on the JSON outline from 1. After any create/edit, run `pptx_read.py OUT.pptx --outline` and check slide count, texts, tables, notes, and chart values match intent. 2. `--images DIR` then file-size check confirms pictures embedded. -3. For high-stakes decks, render via `soffice` (see Procedure step 5) and - review each slide image with `vision_analyze`. +3. Render every slide with `pptx_render.py deck.pptx --outdir ./render` + and review each PNG with `vision_analyze` — this catches overlapping + shapes, truncated text, and color problems the outline cannot. If the + render tools are missing, the script says so; rely on the outline. 4. The bundled test suite is the full contract: - `python3 -m pytest tests/ -q` (requires python-pptx + pytest). + `python -m pytest tests/ -q` (requires python-pptx + pytest). diff --git a/website/docs/user-guide/skills/bundled/productivity/productivity-product-price-monitor.md b/website/docs/user-guide/skills/bundled/productivity/productivity-product-price-monitor.md index f0349effb9..d757afe4eb 100644 --- a/website/docs/user-guide/skills/bundled/productivity/productivity-product-price-monitor.md +++ b/website/docs/user-guide/skills/bundled/productivity/productivity-product-price-monitor.md @@ -15,7 +15,7 @@ Watch product, flight, or listing prices; alert on target. | | | |---|---| | Source | Bundled (installed by default) | -| Path | `skills/productivity/product-price-monitor` | +| Path | `skills/productivity\product-price-monitor` | | Version | `0.1.0` | | Author | Ben Barclay (benbarclay), Hermes Agent | | License | MIT | diff --git a/website/docs/user-guide/skills/bundled/productivity/productivity-teams-meeting-pipeline.md b/website/docs/user-guide/skills/bundled/productivity/productivity-teams-meeting-pipeline.md index 60eb2d6a3c..ff5476a053 100644 --- a/website/docs/user-guide/skills/bundled/productivity/productivity-teams-meeting-pipeline.md +++ b/website/docs/user-guide/skills/bundled/productivity/productivity-teams-meeting-pipeline.md @@ -15,7 +15,7 @@ Teams meeting summaries, job replay, Graph subscriptions. | | | |---|---| | Source | Bundled (installed by default) | -| Path | `skills/productivity/teams-meeting-pipeline` | +| Path | `skills/productivity\teams-meeting-pipeline` | | Version | `1.1.0` | | Author | Hermes Agent + Teknium | | License | MIT | diff --git a/website/docs/user-guide/skills/bundled/productivity/productivity-weekly-review-planning.md b/website/docs/user-guide/skills/bundled/productivity/productivity-weekly-review-planning.md index 1d932c05e2..353389b4ae 100644 --- a/website/docs/user-guide/skills/bundled/productivity/productivity-weekly-review-planning.md +++ b/website/docs/user-guide/skills/bundled/productivity/productivity-weekly-review-planning.md @@ -15,7 +15,7 @@ Weekly reset: commitments, stalled work, next-week plan. | | | |---|---| | Source | Bundled (installed by default) | -| Path | `skills/productivity/weekly-review-planning` | +| Path | `skills/productivity\weekly-review-planning` | | Version | `0.1.0` | | Author | Ben Barclay (benbarclay), Hermes Agent | | License | MIT | diff --git a/website/docs/user-guide/skills/bundled/productivity/productivity-xlsx.md b/website/docs/user-guide/skills/bundled/productivity/productivity-xlsx.md index 7315c346ec..e0d51ec0b9 100644 --- a/website/docs/user-guide/skills/bundled/productivity/productivity-xlsx.md +++ b/website/docs/user-guide/skills/bundled/productivity/productivity-xlsx.md @@ -15,8 +15,8 @@ Create, read, edit Excel .xlsx workbooks and CSVs. | | | |---|---| | Source | Bundled (installed by default) | -| Path | `skills/productivity/xlsx` | -| Version | `1.0.0` | +| Path | `skills/productivity\xlsx` | +| Version | `1.1.0` | | Author | Nous Research | | License | MIT | | Platforms | linux, macos, windows | @@ -40,11 +40,15 @@ scripts are argparse CLIs that print JSON and use explicit UTF-8 I/O. - Creating .xlsx reports: multiple sheets, number formats, styling, merged cells, freeze panes, autofilter, conditional formatting, - charts, data-validation dropdowns. + charts, data-validation dropdowns, native Excel tables, defined + names, hyperlinks, cell notes, sheet protection. - Reading a workbook: sheet inventory, dumping data as JSON or CSV, - listing formulas vs cached values. + listing formulas vs cached values, notes, defined names, tables. - Editing existing files: set cells, append rows, insert/delete - rows/columns, copy/rename sheets. + rows/columns (reference-aware via `xlsx_restructure.py`), + copy/rename sheets, tables, names, notes, protection. +- Recalculating formulas headlessly via LibreOffice + (`xlsx_recalc.py`). - CSV interop with type inference and non-UTF-8 encodings. - Not for the legacy .xls binary format (use LibreOffice to convert first: `soffice --headless --convert-to xlsx old.xls`). @@ -67,6 +71,8 @@ python scripts/xlsx_read.py report.xlsx --sheets # inventory python scripts/xlsx_read.py report.xlsx --json --sheet Data python scripts/xlsx_read.py report.xlsx --formulas python scripts/xlsx_edit.py report.xlsx --sheet Data --set B2=42 --recalc +python scripts/xlsx_restructure.py report.xlsx --sheet Data --insert-rows 3:2 +python scripts/xlsx_recalc.py report.xlsx python scripts/csv_to_xlsx.py data.csv out.xlsx --encoding utf-8 python scripts/xlsx_to_csv.py report.xlsx out.csv --sheet Data ``` @@ -85,7 +91,17 @@ Author the JSON spec with `write_file`, inspect script JSON output with | List formulas + cached values | `xlsx_read.py f.xlsx --formulas` | | Set a cell / formula | `xlsx_edit.py f.xlsx --set "A1==SUM(B:B)"` | | Append a row | `xlsx_edit.py f.xlsx --append '[1,"x",true]'` | -| Insert 2 rows before row 3 | `xlsx_edit.py f.xlsx --insert-rows 3:2` | +| Insert 2 rows, refs NOT shifted | `xlsx_edit.py f.xlsx --insert-rows 3:2` | +| Insert 2 rows, refs shifted | `xlsx_restructure.py f.xlsx --insert-rows 3:2` | +| Delete a column, refs shifted | `xlsx_restructure.py f.xlsx --delete-cols B` | +| Create a native table | `xlsx_edit.py f.xlsx --add-table Sales:A1:C9` | +| Append inside a table | `--table-append 'Sales=["West",5]'` | +| List tables | `xlsx_edit.py f.xlsx --list-tables` | +| Defined names | `--define-name "Rates='Data'!$B$2:$B$9"` / `--delete-name Rates` / `xlsx_read.py f.xlsx --names` | +| Hyperlink | `--hyperlink "A1=https://example.com|Docs"` | +| Cell note | `--note "B2=Check this|Reviewer"`; read via `xlsx_read.py f.xlsx --notes` | +| Protect sheet (see Pitfalls) | `--protect your-password --unlock B2:B9` | +| Recalculate via LibreOffice | `xlsx_recalc.py f.xlsx` | | Copy / rename sheet | `--copy-sheet Src:New --rename-sheet Old:New` | | Force recalc on open | `xlsx_edit.py f.xlsx --recalc` | | CSV -> styled xlsx | `csv_to_xlsx.py in.csv out.xlsx` | @@ -98,8 +114,11 @@ Author the JSON spec with `write_file`, inspect script JSON output with `rows` (scalars or styled cell objects), sparse `cells` overrides, `column_widths`, `row_heights`, `merges`, `freeze_panes`, `autofilter`, `conditional_formats` (cell_is rules and color - scales), `charts` (bar/line/pie from cell ranges), and - `validations` (list dropdowns). Typed values: JSON numbers/bools + scales), `charts` (bar/line/pie from cell ranges), + `validations` (list dropdowns), `tables` (native Excel tables with + a style name), and `protection`. Workbook-level `defined_names` + maps names to refs. Cell objects also take `hyperlink` and `note`. + Typed values: JSON numbers/bools pass through; dates use `{"value": "2026-01-31", "type": "date"}`. Number formats are Excel format strings: currency `"$#,##0.00"`, percent `"0.0%"`, date `"yyyy-mm-dd"`. @@ -109,32 +128,62 @@ Author the JSON spec with `write_file`, inspect script JSON output with the workbook's `fullCalcOnLoad` flag so Excel/LibreOffice recompute everything on open. openpyxl itself NEVER evaluates formulas. 3. **Read**: `--sheets` for inventory (names, dimensions, merged - ranges, chart count), `--json`/`--csv` for data, `--formulas` to - pair each formula string with its cached result. Cached results + ranges, chart count, tables, protection, defined names), + `--json`/`--csv` for data, `--formulas` to + pair each formula string with its cached result, `--notes` for + cell comments, `--names` for defined names. Cached results exist only if the file was last saved by a real spreadsheet app; files fresh from openpyxl return `null` there. To materialize - results headlessly: `soffice --headless --convert-to xlsx file.xlsx` - then reload with `--data-only`. + results headlessly run `xlsx_recalc.py file.xlsx` (uses + LibreOffice; prints `{"recalculated": false, ...}` and exits 0 + when `soffice` is absent), then reload with `--data-only`. 4. **Edit**: `xlsx_edit.py` applies renames/copies first, then structural row/column changes, then `--set`/`--append`. It edits in place unless `--out` is given — copy the file first if you need the original. -5. **CSV interop**: `csv_to_xlsx.py` infers int/float/bool/ISO-date +5. **Restructure**: for insert/delete on sheets that have formulas, + merges, tables, or filters, use `xlsx_restructure.py` instead of + `xlsx_edit.py`. It rewrites formula references on ALL sheets + (absolute `$` refs, ranges, cross-sheet refs), shifts merges, + autofilter, freeze panes, validation and conditional-format + ranges, table refs, defined names, and row/column dimensions, then + prints a JSON report including a `not_shifted` list. Rules and + limits: `references/restructuring.md`. +6. **CSV interop**: `csv_to_xlsx.py` infers int/float/bool/ISO-date per cell and styles the header row; `xlsx_to_csv.py` writes ISO dates and blank strings for empty cells. Both default to UTF-8 and accept `--encoding` (e.g. `utf-8-sig` for Excel-friendly BOM, `cp1252` for legacy Windows exports). +## Converting to PDF + +LibreOffice converts headlessly (also works for CSV export of a single +sheet): + +```bash +soffice --headless --convert-to pdf report.xlsx --outdir out/ +soffice --headless --convert-to csv report.xlsx --outdir out/ # 1st sheet only +``` + +Only the first sheet lands in a CSV; for other sheets use +`xlsx_to_csv.py --sheet NAME`. If `soffice` is missing, install +LibreOffice or hand the file to the user unconverted. + ## Pitfalls - **openpyxl does not calculate.** Formula results are available only via `load_workbook(path, data_only=True)` and only when the file was previously saved by Excel/LibreOffice. Otherwise you get `None`. -- **Insert/delete does not shift references.** `insert_rows`, - `delete_cols`, etc. move cell values but do NOT update merged-cell - ranges, formula references, chart anchors, or conditional-format - ranges. After structural edits on sheets with merges or formulas, - re-check them with `--sheets` and `--formulas` and fix manually. +- **`xlsx_edit.py` insert/delete does not shift references** (raw + openpyxl behavior). Use `xlsx_restructure.py`, which does — but even + it cannot move chart anchors, images, or conditional-format RULE + formulas; read its JSON report's `not_shifted` list and + `references/restructuring.md`. +- **Sheet protection is NOT security.** `--protect` sets the standard + xlsx sheet-protection hash: it signals "don't edit this" to + well-behaved apps and nothing more. Anyone can strip it by editing + the zip's XML or unchecking it in LibreOffice. Never rely on it for + confidentiality or integrity; it does not encrypt anything. - **`data_only=True` then save** silently discards all formulas (cached values replace them). Never save a workbook loaded that way unless that is the goal. @@ -157,5 +206,8 @@ Author the JSON spec with `write_file`, inspect script JSON output with - Dump data with `--json` and compare against the source values. - After edits: re-dump the touched range; if formulas were written, confirm `--formulas` lists them and that `--recalc` was applied. +- After `xlsx_restructure.py`: read its JSON report, then re-run + `--formulas` and `--sheets` to confirm references and ranges landed + where expected. - For a full visual check, open in LibreOffice: `soffice --headless --convert-to pdf out.xlsx` and inspect the PDF. diff --git a/website/docs/user-guide/skills/bundled/research/research-arxiv.md b/website/docs/user-guide/skills/bundled/research/research-arxiv.md index 4425858d74..f41cfcbfc9 100644 --- a/website/docs/user-guide/skills/bundled/research/research-arxiv.md +++ b/website/docs/user-guide/skills/bundled/research/research-arxiv.md @@ -15,13 +15,13 @@ Search arXiv papers by keyword, author, category, or ID. | | | |---|---| | Source | Bundled (installed by default) | -| Path | `skills/research/arxiv` | +| Path | `skills/research\arxiv` | | Version | `1.0.0` | | Author | Hermes Agent | | License | MIT | | Platforms | linux, macos, windows | | Tags | `Research`, `Arxiv`, `Papers`, `Academic`, `Science`, `API` | -| Related skills | [`ocr-and-documents`](/docs/user-guide/skills/bundled/productivity/productivity-ocr-and-documents) | +| Related skills | `ocr-and-documents` | ## Reference: full SKILL.md @@ -44,7 +44,7 @@ Search and retrieve academic papers from arXiv via their free REST API. No API k ## Searching Papers -The API returns Atom XML. Parse with `grep`/`sed` or pipe through `python3` for clean output. +The API returns Atom XML. Parse with `grep`/`sed` or pipe through `python` for clean output. ### Basic search @@ -55,7 +55,7 @@ curl -s "https://export.arxiv.org/api/query?search_query=all:GRPO+reinforcement+ ### Clean output (parse XML to readable format) ```bash -curl -s "https://export.arxiv.org/api/query?search_query=all:GRPO+reinforcement+learning&max_results=5&sortBy=submittedDate&sortOrder=descending" | python3 -c " +curl -s "https://export.arxiv.org/api/query?search_query=all:GRPO+reinforcement+learning&max_results=5&sortBy=submittedDate&sortOrder=descending" | python -c " import sys, xml.etree.ElementTree as ET ns = {'a': 'http://www.w3.org/2005/Atom'} root = ET.parse(sys.stdin).getroot() @@ -135,7 +135,7 @@ After fetching metadata for a paper, generate a BibTeX entry: {% raw %} ```bash -curl -s "https://export.arxiv.org/api/query?id_list=1706.03762" | python3 -c " +curl -s "https://export.arxiv.org/api/query?id_list=1706.03762" | python -c " import sys, xml.etree.ElementTree as ET ns = {'a': 'http://www.w3.org/2005/Atom', 'arxiv': 'http://arxiv.org/schemas/atom'} root = ET.parse(sys.stdin).getroot() @@ -215,7 +215,7 @@ arXiv doesn't provide citation data or recommendations. Use the **Semantic Schol ```bash # By arXiv ID -curl -s "https://api.semanticscholar.org/graph/v1/paper/arXiv:2402.03300?fields=title,authors,citationCount,referenceCount,influentialCitationCount,year,abstract" | python3 -m json.tool +curl -s "https://api.semanticscholar.org/graph/v1/paper/arXiv:2402.03300?fields=title,authors,citationCount,referenceCount,influentialCitationCount,year,abstract" | python -m json.tool # By Semantic Scholar paper ID or DOI curl -s "https://api.semanticscholar.org/graph/v1/paper/DOI:10.1234/example?fields=title,citationCount" @@ -224,19 +224,19 @@ curl -s "https://api.semanticscholar.org/graph/v1/paper/DOI:10.1234/example?fiel ### Get citations OF a paper (who cited it) ```bash -curl -s "https://api.semanticscholar.org/graph/v1/paper/arXiv:2402.03300/citations?fields=title,authors,year,citationCount&limit=10" | python3 -m json.tool +curl -s "https://api.semanticscholar.org/graph/v1/paper/arXiv:2402.03300/citations?fields=title,authors,year,citationCount&limit=10" | python -m json.tool ``` ### Get references FROM a paper (what it cites) ```bash -curl -s "https://api.semanticscholar.org/graph/v1/paper/arXiv:2402.03300/references?fields=title,authors,year,citationCount&limit=10" | python3 -m json.tool +curl -s "https://api.semanticscholar.org/graph/v1/paper/arXiv:2402.03300/references?fields=title,authors,year,citationCount&limit=10" | python -m json.tool ``` ### Search papers (alternative to arXiv search, returns JSON) ```bash -curl -s "https://api.semanticscholar.org/graph/v1/paper/search?query=GRPO+reinforcement+learning&limit=5&fields=title,authors,year,citationCount,externalIds" | python3 -m json.tool +curl -s "https://api.semanticscholar.org/graph/v1/paper/search?query=GRPO+reinforcement+learning&limit=5&fields=title,authors,year,citationCount,externalIds" | python -m json.tool ``` ### Get paper recommendations @@ -244,13 +244,13 @@ curl -s "https://api.semanticscholar.org/graph/v1/paper/search?query=GRPO+reinfo ```bash curl -s -X POST "https://api.semanticscholar.org/recommendations/v1/papers/" \ -H "Content-Type: application/json" \ - -d '{"positivePaperIds": ["arXiv:2402.03300"], "negativePaperIds": []}' | python3 -m json.tool + -d '{"positivePaperIds": ["arXiv:2402.03300"], "negativePaperIds": []}' | python -m json.tool ``` ### Author profile ```bash -curl -s "https://api.semanticscholar.org/graph/v1/author/search?query=Yann+LeCun&fields=name,hIndex,citationCount,paperCount" | python3 -m json.tool +curl -s "https://api.semanticscholar.org/graph/v1/author/search?query=Yann+LeCun&fields=name,hIndex,citationCount,paperCount" | python -m json.tool ``` ### Useful Semantic Scholar fields @@ -279,7 +279,7 @@ curl -s "https://api.semanticscholar.org/graph/v1/author/search?query=Yann+LeCun ## Notes - arXiv returns Atom XML — use the helper script or parsing snippet for clean output -- Semantic Scholar returns JSON — pipe through `python3 -m json.tool` for readability +- Semantic Scholar returns JSON — pipe through `python -m json.tool` for readability - arXiv IDs: old format (`hep-th/0601001`) vs new (`2402.03300`) - PDF: `https://arxiv.org/pdf/{id}` — Abstract: `https://arxiv.org/abs/{id}` - HTML (when available): `https://arxiv.org/html/{id}` diff --git a/website/docs/user-guide/skills/bundled/research/research-competitor-news-monitor.md b/website/docs/user-guide/skills/bundled/research/research-competitor-news-monitor.md index bc31b958ed..dd756be8a9 100644 --- a/website/docs/user-guide/skills/bundled/research/research-competitor-news-monitor.md +++ b/website/docs/user-guide/skills/bundled/research/research-competitor-news-monitor.md @@ -15,13 +15,13 @@ Watch named companies for material news; cited digests. | | | |---|---| | Source | Bundled (installed by default) | -| Path | `skills/research/competitor-news-monitor` | +| Path | `skills/research\competitor-news-monitor` | | Version | `0.1.0` | | Author | Ben Barclay (benbarclay), Hermes Agent | | License | MIT | | Platforms | linux, macos, windows | | Tags | `Competitors`, `News`, `Market-Research`, `Monitoring` | -| Related skills | [`blogwatcher`](/docs/user-guide/skills/bundled/research/research-blogwatcher) | +| Related skills | [`blogwatcher`](/docs/user-guide/skills/optional/research/research-blogwatcher) | ## Reference: full SKILL.md diff --git a/website/docs/user-guide/skills/bundled/research/research-grounded-citations.md b/website/docs/user-guide/skills/bundled/research/research-grounded-citations.md index 487e06a6b6..938e223a68 100644 --- a/website/docs/user-guide/skills/bundled/research/research-grounded-citations.md +++ b/website/docs/user-guide/skills/bundled/research/research-grounded-citations.md @@ -15,13 +15,13 @@ Ground answers and documents in cited, verifiable sources. | | | |---|---| | Source | Bundled (installed by default) | -| Path | `skills/research/grounded-citations` | +| Path | `skills/research\grounded-citations` | | Version | `1.1.0` | | Author | Hermes Agent + Teknium | | License | MIT | | Platforms | linux, macos, windows | | Tags | `Research`, `Citations`, `Grounding`, `Sources`, `Web`, `Reports` | -| Related skills | [`research-paper-writing`](/docs/user-guide/skills/bundled/research/research-research-paper-writing), [`arxiv`](/docs/user-guide/skills/bundled/research/research-arxiv), [`ocr-and-documents`](/docs/user-guide/skills/bundled/productivity/productivity-ocr-and-documents) | +| Related skills | [`arxiv`](/docs/user-guide/skills/bundled/research/research-arxiv), [`arxiv`](/docs/user-guide/skills/bundled/research/research-arxiv), `ocr-and-documents` | ## Reference: full SKILL.md @@ -43,7 +43,7 @@ and `verify --evidence` fails any draft whose cited sources carry no evidence. This skill covers answers in chat, written documents (markdown, PDF, docx, slides), and research reports. It does not cover academic BibTeX pipelines — -for conference papers use the `research-paper-writing` skill, which this skill +for conference papers use the `arxiv` skill, which this skill feeds (see `references/citation-formats.md`). ## When to Use @@ -75,12 +75,12 @@ Override per task with `--ledger <path>` or `HERMES_CITATION_LEDGER`. ```bash S=~/.hermes/skills/research/grounded-citations/scripts/sources.py -python3 "$S" reset # start a clean ledger -python3 "$S" add https://example.com/a --title "A" # prints: [1] -python3 "$S" add https://example.com/b --title "B" # prints: [2] -python3 "$S" list # ledger table -python3 "$S" render # Sources: block -python3 "$S" verify draft.md # catch bad citations +python "$S" reset # start a clean ledger +python "$S" add https://example.com/a --title "A" # prints: [1] +python "$S" add https://example.com/b --title "B" # prints: [2] +python "$S" list # ledger table +python "$S" render # Sources: block +python "$S" verify draft.md # catch bad citations ``` `add` is idempotent and URL-normalized: the same page always returns the same @@ -153,7 +153,7 @@ upgrade from citations to evidence: text to a file and attach the sentence(s) that carry each claim: ```bash -python3 "$S" quote 1 --text "Ice is about 9% less dense than liquid water." --from page1.txt +python "$S" quote 1 --text "Ice is about 9% less dense than liquid water." --from page1.txt ``` The quote is rejected unless it appears verbatim in the evidence text @@ -185,8 +185,8 @@ corroboration. ④ **Verify with the evidence gate and render the evidence block:** ```bash -python3 "$S" verify report.md --evidence --min-coverage 0.5 -python3 "$S" render --style evidence --replace-in report.md +python "$S" verify report.md --evidence --min-coverage 0.5 +python "$S" render --style evidence --replace-in report.md ``` `--evidence` fails the draft if any cited source has no attached quote. The @@ -239,7 +239,7 @@ and read the `info: stats:` line to see the counts before picking a number. ## Verification ```bash -python3 "$S" verify report.md --strict --min-coverage 0.5 +python "$S" verify report.md --strict --min-coverage 0.5 ``` Green means: every `[n]` in the draft exists in the ledger, the Sources block diff --git a/website/docs/user-guide/skills/bundled/research/research-llm-wiki.md b/website/docs/user-guide/skills/bundled/research/research-llm-wiki.md index 566c7378b9..6d97ac2893 100644 --- a/website/docs/user-guide/skills/bundled/research/research-llm-wiki.md +++ b/website/docs/user-guide/skills/bundled/research/research-llm-wiki.md @@ -15,7 +15,7 @@ Karpathy's LLM Wiki: build/query interlinked markdown KB. | | | |---|---| | Source | Bundled (installed by default) | -| Path | `skills/research/llm-wiki` | +| Path | `skills/research\llm-wiki` | | Version | `2.1.0` | | Author | Hermes Agent | | License | MIT | diff --git a/website/docs/user-guide/skills/bundled/social-media/social-media-xurl.md b/website/docs/user-guide/skills/bundled/social-media/social-media-xurl.md index c88091157f..7e42b4f9e7 100644 --- a/website/docs/user-guide/skills/bundled/social-media/social-media-xurl.md +++ b/website/docs/user-guide/skills/bundled/social-media/social-media-xurl.md @@ -15,7 +15,7 @@ X/Twitter via xurl CLI: raw post search, posting, DM, media. | | | |---|---| | Source | Bundled (installed by default) | -| Path | `skills/social-media/xurl` | +| Path | `skills/social-media\xurl` | | Version | `1.1.3` | | Author | xdevplatform + openclaw + Hermes Agent | | License | MIT | diff --git a/website/docs/user-guide/skills/bundled/software-development/software-development-codebase-inspection.md b/website/docs/user-guide/skills/bundled/software-development/software-development-codebase-inspection.md new file mode 100644 index 0000000000..e4d49e9d14 --- /dev/null +++ b/website/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. diff --git a/website/docs/user-guide/skills/bundled/software-development/software-development-dogfood.md b/website/docs/user-guide/skills/bundled/software-development/software-development-dogfood.md index 953add5b00..ea01fcc03b 100644 --- a/website/docs/user-guide/skills/bundled/software-development/software-development-dogfood.md +++ b/website/docs/user-guide/skills/bundled/software-development/software-development-dogfood.md @@ -15,7 +15,7 @@ Exploratory QA of web apps: find bugs, evidence, reports. | | | |---|---| | Source | Bundled (installed by default) | -| Path | `skills/software-development/dogfood` | +| Path | `skills/software-development\dogfood` | | Version | `1.0.0` | | Author | Teknium (teknium1), Hermes Agent | | License | MIT | diff --git a/website/docs/user-guide/skills/bundled/software-development/software-development-github.md b/website/docs/user-guide/skills/bundled/software-development/software-development-github.md new file mode 100644 index 0000000000..6a70dc807c --- /dev/null +++ b/website/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. diff --git a/website/docs/user-guide/skills/bundled/software-development/software-development-hermes-agent-skill-authoring.md b/website/docs/user-guide/skills/bundled/software-development/software-development-hermes-agent-skill-authoring.md index 8a3eceb19d..c1d6299dfa 100644 --- a/website/docs/user-guide/skills/bundled/software-development/software-development-hermes-agent-skill-authoring.md +++ b/website/docs/user-guide/skills/bundled/software-development/software-development-hermes-agent-skill-authoring.md @@ -15,13 +15,13 @@ Author in-repo SKILL.md files: frontmatter and structure. | | | |---|---| | Source | Bundled (installed by default) | -| Path | `skills/software-development/hermes-agent-skill-authoring` | +| 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 | `plan` (now the built-in `/plan` command), [`requesting-code-review`](/docs/user-guide/skills/bundled/software-development/software-development-requesting-code-review) | +| Related skills | [`requesting-code-review`](/docs/user-guide/skills/bundled/software-development/software-development-requesting-code-review) | ## Reference: full SKILL.md @@ -166,7 +166,7 @@ A skill exists to make the agent's process more predictable — the agent reliab ## 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 `python3 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). +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 diff --git a/website/docs/user-guide/skills/bundled/software-development/software-development-inspecting-hermes-desktop-dom.md b/website/docs/user-guide/skills/bundled/software-development/software-development-inspecting-hermes-desktop-dom.md index 7779328dbe..d3f5e423cd 100644 --- a/website/docs/user-guide/skills/bundled/software-development/software-development-inspecting-hermes-desktop-dom.md +++ b/website/docs/user-guide/skills/bundled/software-development/software-development-inspecting-hermes-desktop-dom.md @@ -15,7 +15,7 @@ Read the live Hermes desktop DOM/CSS over CDP. | | | |---|---| | Source | Bundled (installed by default) | -| Path | `skills/software-development/inspecting-hermes-desktop-dom` | +| Path | `skills/software-development\inspecting-hermes-desktop-dom` | | Version | `1.0.0` | | Author | Hermes Agent | | License | MIT | diff --git a/website/docs/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger.md b/website/docs/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger.md index 57f26162d8..18580751bc 100644 --- a/website/docs/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger.md +++ b/website/docs/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger.md @@ -15,7 +15,7 @@ Debug Node.js via --inspect + Chrome DevTools Protocol CLI. | | | |---|---| | Source | Bundled (installed by default) | -| Path | `skills/software-development/node-inspect-debugger` | +| Path | `skills/software-development\node-inspect-debugger` | | Version | `1.0.0` | | Author | Hermes Agent | | License | MIT | diff --git a/website/docs/user-guide/skills/bundled/software-development/software-development-python-debugpy.md b/website/docs/user-guide/skills/bundled/software-development/software-development-python-debugpy.md index 4f7c4c37e3..e6f1120e08 100644 --- a/website/docs/user-guide/skills/bundled/software-development/software-development-python-debugpy.md +++ b/website/docs/user-guide/skills/bundled/software-development/software-development-python-debugpy.md @@ -15,7 +15,7 @@ Debug Python: pdb REPL + debugpy remote (DAP). | | | |---|---| | Source | Bundled (installed by default) | -| Path | `skills/software-development/python-debugpy` | +| Path | `skills/software-development\python-debugpy` | | Version | `1.0.0` | | Author | Hermes Agent | | License | MIT | diff --git a/website/docs/user-guide/skills/bundled/software-development/software-development-requesting-code-review.md b/website/docs/user-guide/skills/bundled/software-development/software-development-requesting-code-review.md index bf6f13b70d..dfdfb42622 100644 --- a/website/docs/user-guide/skills/bundled/software-development/software-development-requesting-code-review.md +++ b/website/docs/user-guide/skills/bundled/software-development/software-development-requesting-code-review.md @@ -15,13 +15,13 @@ Pre-commit review: security scan, quality gates, auto-fix. | | | |---|---| | Source | Bundled (installed by default) | -| Path | `skills/software-development/requesting-code-review` | +| Path | `skills/software-development\requesting-code-review` | | Version | `2.0.0` | | Author | Hermes Agent (adapted from obra/superpowers + MorAlekss) | | License | MIT | | Platforms | linux, macos, windows | | Tags | `code-review`, `security`, `verification`, `quality`, `pre-commit`, `auto-fix` | -| Related skills | [`subagent-driven-development`](/docs/user-guide/skills/optional/software-development/software-development-subagent-driven-development), `plan` (now the built-in `/plan` command), [`test-driven-development`](/docs/user-guide/skills/bundled/software-development/software-development-test-driven-development), [`github-code-review`](/docs/user-guide/skills/bundled/github/github-github-code-review) | +| Related skills | [`subagent-driven-development`](/docs/user-guide/skills/optional/software-development/software-development-subagent-driven-development), [`test-driven-development`](/docs/user-guide/skills/bundled/software-development/software-development-test-driven-development), [`github`](/docs/user-guide/skills/bundled/software-development/software-development-github) | ## Reference: full SKILL.md @@ -45,8 +45,8 @@ quality gates, an independent reviewer subagent, and an auto-fix loop. **Skip for:** documentation-only changes, pure config tweaks, or when user says "skip verification". -**This skill vs github-code-review:** This skill verifies YOUR changes before committing. -`github-code-review` reviews OTHER people's PRs on GitHub with inline comments. +**This skill vs github:** This skill verifies YOUR changes before committing. +`github` reviews OTHER people's PRs on GitHub with inline comments. ## Step 1 — Get the diff diff --git a/website/docs/user-guide/skills/bundled/software-development/software-development-simplify-code.md b/website/docs/user-guide/skills/bundled/software-development/software-development-simplify-code.md index 57a1534692..59e22aa1f6 100644 --- a/website/docs/user-guide/skills/bundled/software-development/software-development-simplify-code.md +++ b/website/docs/user-guide/skills/bundled/software-development/software-development-simplify-code.md @@ -15,13 +15,13 @@ Parallel 4-agent cleanup of recent code changes. | | | |---|---| | Source | Bundled (installed by default) | -| Path | `skills/software-development/simplify-code` | +| Path | `skills/software-development\simplify-code` | | Version | `1.1.0` | | Author | Hermes Agent (inspired by Claude Code /simplify) | | License | MIT | | Platforms | linux, macos, windows | | Tags | `code-review`, `cleanup`, `refactor`, `delegation`, `subagent`, `parallel`, `simplify` | -| Related skills | [`requesting-code-review`](/docs/user-guide/skills/bundled/software-development/software-development-requesting-code-review), [`test-driven-development`](/docs/user-guide/skills/bundled/software-development/software-development-test-driven-development), `plan` (now the built-in `/plan` command) | +| Related skills | [`requesting-code-review`](/docs/user-guide/skills/bundled/software-development/software-development-requesting-code-review), [`test-driven-development`](/docs/user-guide/skills/bundled/software-development/software-development-test-driven-development) | ## Reference: full SKILL.md diff --git a/website/docs/user-guide/skills/bundled/software-development/software-development-spike.md b/website/docs/user-guide/skills/bundled/software-development/software-development-spike.md index 470e984504..b2d6342723 100644 --- a/website/docs/user-guide/skills/bundled/software-development/software-development-spike.md +++ b/website/docs/user-guide/skills/bundled/software-development/software-development-spike.md @@ -15,13 +15,13 @@ Throwaway experiments to validate an idea before build. | | | |---|---| | Source | Bundled (installed by default) | -| Path | `skills/software-development/spike` | +| Path | `skills/software-development\spike` | | Version | `1.0.0` | | Author | Hermes Agent (adapted from gsd-build/get-shit-done) | | License | MIT | | Platforms | linux, macos, windows | | Tags | `spike`, `prototype`, `experiment`, `feasibility`, `throwaway`, `exploration`, `research`, `planning`, `mvp`, `proof-of-concept` | -| Related skills | [`sketch`](/docs/user-guide/skills/bundled/creative/creative-sketch), [`subagent-driven-development`](/docs/user-guide/skills/optional/software-development/software-development-subagent-driven-development), `plan` (now the built-in `/plan` command) | +| Related skills | [`sketch`](/docs/user-guide/skills/optional/creative/creative-sketch), [`subagent-driven-development`](/docs/user-guide/skills/optional/software-development/software-development-subagent-driven-development) | ## Reference: full SKILL.md @@ -138,7 +138,7 @@ spikes/ terminal("mkdir -p spikes/001-websocket-streaming") write_file("spikes/001-websocket-streaming/README.md", "# 001: websocket-streaming\n\n...") write_file("spikes/001-websocket-streaming/main.py", "...") -terminal("cd spikes/001-websocket-streaming && python3 main.py") +terminal("cd spikes/001-websocket-streaming && python main.py") # Observe output, iterate. ``` diff --git a/website/docs/user-guide/skills/bundled/software-development/software-development-systematic-debugging.md b/website/docs/user-guide/skills/bundled/software-development/software-development-systematic-debugging.md index a3f9f288aa..684cbdb5bf 100644 --- a/website/docs/user-guide/skills/bundled/software-development/software-development-systematic-debugging.md +++ b/website/docs/user-guide/skills/bundled/software-development/software-development-systematic-debugging.md @@ -15,13 +15,13 @@ description: "4-phase root cause debugging: understand bugs before fixing" | | | |---|---| | Source | Bundled (installed by default) | -| Path | `skills/software-development/systematic-debugging` | +| Path | `skills/software-development\systematic-debugging` | | Version | `1.1.0` | | Author | Hermes Agent (adapted from obra/superpowers) | | License | MIT | | Platforms | linux, macos, windows | | Tags | `debugging`, `troubleshooting`, `problem-solving`, `root-cause`, `investigation` | -| Related skills | [`test-driven-development`](/docs/user-guide/skills/bundled/software-development/software-development-test-driven-development), `plan` (now the built-in `/plan` command), [`subagent-driven-development`](/docs/user-guide/skills/optional/software-development/software-development-subagent-driven-development) | +| Related skills | [`test-driven-development`](/docs/user-guide/skills/bundled/software-development/software-development-test-driven-development), [`subagent-driven-development`](/docs/user-guide/skills/optional/software-development/software-development-subagent-driven-development) | ## Reference: full SKILL.md diff --git a/website/docs/user-guide/skills/bundled/software-development/software-development-test-driven-development.md b/website/docs/user-guide/skills/bundled/software-development/software-development-test-driven-development.md index 4ef912ec90..805782c463 100644 --- a/website/docs/user-guide/skills/bundled/software-development/software-development-test-driven-development.md +++ b/website/docs/user-guide/skills/bundled/software-development/software-development-test-driven-development.md @@ -15,13 +15,13 @@ TDD: enforce RED-GREEN-REFACTOR, tests before code. | | | |---|---| | Source | Bundled (installed by default) | -| Path | `skills/software-development/test-driven-development` | +| Path | `skills/software-development\test-driven-development` | | Version | `1.1.0` | | Author | Hermes Agent (adapted from obra/superpowers) | | License | MIT | | Platforms | linux, macos, windows | | Tags | `testing`, `tdd`, `development`, `quality`, `red-green-refactor` | -| Related skills | [`systematic-debugging`](/docs/user-guide/skills/bundled/software-development/software-development-systematic-debugging), `plan` (now the built-in `/plan` command), [`subagent-driven-development`](/docs/user-guide/skills/optional/software-development/software-development-subagent-driven-development) | +| Related skills | [`systematic-debugging`](/docs/user-guide/skills/bundled/software-development/software-development-systematic-debugging), [`subagent-driven-development`](/docs/user-guide/skills/optional/software-development/software-development-subagent-driven-development) | ## Reference: full SKILL.md diff --git a/website/docs/user-guide/skills/bundled/web/web-blocked-page-recovery.md b/website/docs/user-guide/skills/bundled/web/web-blocked-page-recovery.md new file mode 100644 index 0000000000..a32d215044 --- /dev/null +++ b/website/docs/user-guide/skills/bundled/web/web-blocked-page-recovery.md @@ -0,0 +1,155 @@ +--- +title: "Blocked Page Recovery — Use when a fetch fails: 403/429, paywall, WAF, bot wall" +sidebar_label: "Blocked Page Recovery" +description: "Use when a fetch fails: 403/429, paywall, WAF, bot wall" +--- + +{/* 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. */} + +# Blocked Page Recovery + +Use when a fetch fails: 403/429, paywall, WAF, bot wall. + +## Skill metadata + +| | | +|---|---| +| Source | Bundled (installed by default) | +| Path | `skills/web\blocked-page-recovery` | +| Version | `1.0.0` | +| Author | Hermes Agent | +| License | MIT | +| Platforms | linux, macos, windows | +| Tags | `Research`, `Archives`, `Wayback`, `Paywall`, `WAF`, `Fallback` | +| Related skills | [`grounded-citations`](/docs/user-guide/skills/bundled/research/research-grounded-citations) | + +## 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. +::: + +# Blocked-Page Recovery + +When a page won't fetch — 403/429, Cloudflare "Just a moment...", a paywall, +or a bot-detection interstitial — don't give up and don't loop on the same +URL. Third-party services often hold a **copy** of the page. Work down this +ladder, cheapest first. + +## The ladder + +``` +1. Wayback Machine — archive.org "available" API (snapshot + timestamp) +2. archive.today — domain rotation: archive.ph → .md → .li → .is +3. Jina Reader — only if JINA_API_KEY is set (live server-side render) +4. API-first pivot — look for /api/, /graphql, .json, or RSS on the same host +5. Real browser — browser tool as the last, most expensive resort +``` + +Run it in one shot with the bundled script: + +```bash +python3 scripts/recover_page.py "https://example.com/blocked-article" --json +``` + +The script tries each route in order, validates every body (see "Fake +successes" below), and prints the first genuine hit with its provenance. + +## Provenance discipline (non-negotiable) + +Every recovered copy carries a provenance you MUST preserve when citing: + +| Route | Provenance | How to cite | +|-------|-----------|-------------| +| Wayback / archive.today | `snapshot` | Cite WITH the snapshot date: "as archived 2026-08-06". Never present a snapshot as the live page — it may be stale. | +| Jina Reader | `live` | Server-side re-render of the live page; cite normally. | +| Live fetch / browser | `live` | Cite normally. | + +If the user needs *current* data (prices, availability, breaking news), a +snapshot is context, not an answer — say so explicitly and note its age. + +## Manual routes + +### 1. Wayback Machine (best provenance, try first) + +```bash +# Discovery: returns closest snapshot URL + timestamp as JSON +curl -sL "https://archive.org/wayback/available?url={URL}" +# Then fetch archived_snapshots.closest.url +``` + +For enumerating many snapshots (or recovering deleted pages), the CDX index: + +```bash +curl -sL "https://web.archive.org/cdx/search/cdx?url={URL}&output=json&limit=10" +``` + +CDX intermittently returns 503 under load — if it does, fall back to the +`available` API; don't retry-hammer it. + +Works for: any publicly crawled URL. Fails for: robots-blocked sites, +never-crawled URLs, JS-only SPAs (snapshots don't render). + +### 2. archive.today (paywalls, deleted content) + +User-submitted archives — often has paywalled news articles Wayback lacks. +Rate-limits aggressively (429) and rotates domains, so iterate: + +```bash +for d in archive.ph archive.md archive.li archive.is; do + curl -sL --max-time 20 "https://$d/newest/{URL}" -o /tmp/page.html \ + -w "%{http_code}" && break +done +``` + +**Validate the body, not the status code** — a 429 still ships several KB of +rate-limit HTML that looks like a success to a size check alone. + +### 3. Jina Reader (requires JINA_API_KEY) + +`r.jina.ai` re-renders the live page in a real browser server-side and +returns markdown. Anonymous access is dead (401 → Turnstile); a key is +required: + +```bash +curl -s -H "Authorization: Bearer $JINA_API_KEY" "https://r.jina.ai/{URL}" +``` + +Handles JS SPAs that archives can't. Skip this route entirely when the env +var is unset. + +### 4. API-first pivot + +WAFs protect the HTML surface far more aggressively than the data endpoints +behind it. After 2-3 blocked attempts on a site, stop fighting the HTML and +look for: + +- `/api/...`, `/graphql`, or `.json` variants of the page URL +- An RSS/Atom feed (`/feed`, `/rss`, `<link rel="alternate">` in any copy + you did recover) +- A sitemap (`/sitemap.xml`) revealing canonical URLs that may not be gated + +## Fake successes — routes that LIE + +These return HTTP 200 with a plausible body that is NOT the page. The script +rejects them automatically; reject them manually too: + +- **Google Cache is dead** (since mid-2024). `webcache.googleusercontent.com` + returns 200 + tens of KB, but it's a Google Search interstitial with a JS + redirect, not a cache. Never use it. +- **AMP caches** (`*.cdn.ampproject.org`) mostly return a ~300-byte + `<title>Redirecting` meta-refresh stub pointing back at the + original (blocked) URL. Treating that as success creates a fetch loop. +- **Rate-limit bodies**: archive.today 429 pages are multi-KB HTML. Check for + the target's actual content (title words, expected strings), not just size. + +Detection heuristics the script applies: body under a per-route byte floor; +meta-refresh/JS-redirect stubs whose target is the original host; interstitial +titles ("Just a moment", "Redirecting", "Google Search", "Attention Required"). + +## Proxy relays: don't + +Generic "web proxy" relays are man-in-the-middle by construction. Never send +cookies or Authorization headers through one, and don't use them for anything +the user will rely on — provenance is unverifiable. Prefer archives, which at +least timestamp their copies. diff --git a/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-antigravity-cli.md b/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-antigravity-cli.md index bb6e19904f..d4e2f48b97 100644 --- a/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-antigravity-cli.md +++ b/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-antigravity-cli.md @@ -15,7 +15,7 @@ Operate the Antigravity CLI (agy): plugins, auth, sandbox. | | | |---|---| | Source | Optional — install with `hermes skills install official/autonomous-ai-agents/antigravity-cli` | -| Path | `optional-skills/autonomous-ai-agents/antigravity-cli` | +| Path | `optional-skills/autonomous-ai-agents\antigravity-cli` | | Version | `0.2.0` | | Author | Tony Simons (asimons81), Hermes Agent | | License | MIT | diff --git a/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-blackbox.md b/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-blackbox.md index 822bb73de6..a56d767bd6 100644 --- a/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-blackbox.md +++ b/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-blackbox.md @@ -15,7 +15,7 @@ Delegate coding tasks to the Blackbox AI multi-model CLI. | | | |---|---| | Source | Optional — install with `hermes skills install official/autonomous-ai-agents/blackbox` | -| Path | `optional-skills/autonomous-ai-agents/blackbox` | +| Path | `optional-skills/autonomous-ai-agents\blackbox` | | Version | `1.0.1` | | Author | Hermes Agent (Nous Research) | | License | MIT | diff --git a/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-grok.md b/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-grok.md index a51590f761..e57f08318b 100644 --- a/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-grok.md +++ b/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-grok.md @@ -15,7 +15,7 @@ Delegate coding to xAI Grok Build CLI (features, PRs). | | | |---|---| | Source | Optional — install with `hermes skills install official/autonomous-ai-agents/grok` | -| Path | `optional-skills/autonomous-ai-agents/grok` | +| Path | `optional-skills/autonomous-ai-agents\grok` | | Version | `0.1.1` | | Author | Matt Maximo (MattMaximo), Hermes Agent | | License | MIT | diff --git a/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-honcho.md b/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-honcho.md index 4d3c1c1a45..2bffbcdb4c 100644 --- a/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-honcho.md +++ b/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-honcho.md @@ -15,7 +15,7 @@ Configure and troubleshoot Honcho memory for Hermes. | | | |---|---| | Source | Optional — install with `hermes skills install official/autonomous-ai-agents/honcho` | -| Path | `optional-skills/autonomous-ai-agents/honcho` | +| Path | `optional-skills/autonomous-ai-agents\honcho` | | Version | `2.0.0` | | Author | Hermes Agent | | License | MIT | diff --git a/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-openhands.md b/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-openhands.md index 9774fe25b0..b222bdecf7 100644 --- a/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-openhands.md +++ b/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-openhands.md @@ -15,7 +15,7 @@ Delegate coding to OpenHands CLI (model-agnostic, LiteLLM). | | | |---|---| | Source | Optional — install with `hermes skills install official/autonomous-ai-agents/openhands` | -| Path | `optional-skills/autonomous-ai-agents/openhands` | +| Path | `optional-skills/autonomous-ai-agents\openhands` | | Version | `0.1.0` | | Author | Tim Koepsel (xzessmedia), Hermes Agent | | License | MIT | diff --git a/website/docs/user-guide/skills/optional/blockchain/blockchain-evm.md b/website/docs/user-guide/skills/optional/blockchain/blockchain-evm.md index 01006870ee..a065f01a8b 100644 --- a/website/docs/user-guide/skills/optional/blockchain/blockchain-evm.md +++ b/website/docs/user-guide/skills/optional/blockchain/blockchain-evm.md @@ -15,7 +15,7 @@ Read-only EVM client: wallets, tokens, gas across 8 chains. | | | |---|---| | Source | Optional — install with `hermes skills install official/blockchain/evm` | -| Path | `optional-skills/blockchain/evm` | +| Path | `optional-skills/blockchain\evm` | | Version | `1.0.0` | | Author | Mibayy (@Mibayy), youssefea (@youssefea), ethernet8023 (@ethernet8023), Hermes Agent | | License | MIT | @@ -82,40 +82,40 @@ Helper script path: `~/.hermes/skills/blockchain/evm/scripts/evm_client.py` SCRIPT=~/.hermes/skills/blockchain/evm/scripts/evm_client.py # Network & prices -python3 $SCRIPT stats # Ethereum stats -python3 $SCRIPT stats --chain arbitrum # Arbitrum stats -python3 $SCRIPT compare # Gas + prices ALL 8 chains +python $SCRIPT stats # Ethereum stats +python $SCRIPT stats --chain arbitrum # Arbitrum stats +python $SCRIPT compare # Gas + prices ALL 8 chains # Wallet -python3 $SCRIPT wallet 0xd8dA...96045 # Portfolio (ETH + ERC-20) -python3 $SCRIPT wallet 0xd8dA...96045 --chain bsc -python3 $SCRIPT multichain 0xd8dA...96045 # Same wallet on ALL chains +python $SCRIPT wallet 0xd8dA...96045 # Portfolio (ETH + ERC-20) +python $SCRIPT wallet 0xd8dA...96045 --chain bsc +python $SCRIPT multichain 0xd8dA...96045 # Same wallet on ALL chains # Tokens & prices -python3 $SCRIPT price ETH -python3 $SCRIPT price 0xdAC1...1ec7 # By contract address -python3 $SCRIPT token 0xdAC1...1ec7 # ERC-20 metadata + market cap +python $SCRIPT price ETH +python $SCRIPT price 0xdAC1...1ec7 # By contract address +python $SCRIPT token 0xdAC1...1ec7 # ERC-20 metadata + market cap # Transactions -python3 $SCRIPT tx 0x5c50...f060 # Transaction details -python3 $SCRIPT decode 0x5c50...f060 # Decode input data (4byte.directory) -python3 $SCRIPT activity 0xd8dA...96045 # Recent transactions +python $SCRIPT tx 0x5c50...f060 # Transaction details +python $SCRIPT decode 0x5c50...f060 # Decode input data (4byte.directory) +python $SCRIPT activity 0xd8dA...96045 # Recent transactions # Gas -python3 $SCRIPT gas # Gas prices + cost estimates -python3 $SCRIPT gas --chain optimism +python $SCRIPT gas # Gas prices + cost estimates +python $SCRIPT gas --chain optimism # Security -python3 $SCRIPT allowance 0xd8dA...96045 # Dangerous ERC-20 approvals -python3 $SCRIPT contract 0xdAC1...1ec7 # Contract inspection (proxy? standards?) +python $SCRIPT allowance 0xd8dA...96045 # Dangerous ERC-20 approvals +python $SCRIPT contract 0xdAC1...1ec7 # Contract inspection (proxy? standards?) # ENS -python3 $SCRIPT ens vitalik.eth # Name -> address + profile -python3 $SCRIPT ens 0xd8dA...96045 # Address -> ENS name +python $SCRIPT ens vitalik.eth # Name -> address + profile +python $SCRIPT ens 0xd8dA...96045 # Address -> ENS name # Whale detection -python3 $SCRIPT whale # Large transfers (last 20 blocks, >$10k) -python3 $SCRIPT whale --blocks 50 --min-usd 100000 --chain arbitrum +python $SCRIPT whale # Large transfers (last 20 blocks, >$10k) +python $SCRIPT whale --blocks 50 --min-usd 100000 --chain arbitrum ``` --- @@ -124,67 +124,67 @@ python3 $SCRIPT whale --blocks 50 --min-usd 100000 --chain arbitrum ### 0. Setup Check ```bash -python3 --version # 3.8+ required -python3 ~/.hermes/skills/blockchain/evm/scripts/evm_client.py stats +python --version # 3.8+ required +python ~/.hermes/skills/blockchain/evm/scripts/evm_client.py stats ``` ### 1. Wallet Portfolio Native balance + known ERC-20 tokens, sorted by USD value. ```bash -python3 $SCRIPT wallet 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 -python3 $SCRIPT wallet 0xd8dA... --chain bsc --no-prices # faster +python $SCRIPT wallet 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 +python $SCRIPT wallet 0xd8dA... --chain bsc --no-prices # faster ``` ### 2. Multi-Chain Scan Scans all 8 chains simultaneously for the same address using threads. ```bash -python3 $SCRIPT multichain 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 +python $SCRIPT multichain 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 ``` Output: per-chain native balance + token holdings + grand total USD. ### 3. Compare (Gas + Prices) All 8 chains queried in parallel. Shows cheapest/most expensive chain. ```bash -python3 $SCRIPT compare +python $SCRIPT compare ``` ### 4. Transaction Details & Decode ```bash -python3 $SCRIPT tx 0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060 -python3 $SCRIPT decode 0x5c504ed... # Shows human-readable function signature +python $SCRIPT tx 0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060 +python $SCRIPT decode 0x5c504ed... # Shows human-readable function signature ``` Decode uses 4byte.directory to translate 0xa9059cbb -> transfer(address,uint256). ### 5. ENS Resolution ```bash -python3 $SCRIPT ens vitalik.eth # -> 0xd8dA... + avatar + social links -python3 $SCRIPT ens 0xd8dA...96045 # -> vitalik.eth +python $SCRIPT ens vitalik.eth # -> 0xd8dA... + avatar + social links +python $SCRIPT ens 0xd8dA...96045 # -> vitalik.eth ``` ### 6. Allowance Checker (Security) Checks ERC-20 approvals granted to known DEX/bridge contracts. ```bash -python3 $SCRIPT allowance 0xYourWallet +python $SCRIPT allowance 0xYourWallet ``` Flags UNLIMITED approvals as HIGH risk. ### 7. Contract Inspector ```bash -python3 $SCRIPT contract 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 # USDC (proxy) -python3 $SCRIPT contract 0xdAC17F958D2ee523a2206206994597C13D831ec7 # USDT (ERC-20) +python $SCRIPT contract 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 # USDC (proxy) +python $SCRIPT contract 0xdAC17F958D2ee523a2206206994597C13D831ec7 # USDT (ERC-20) ``` Detects: proxy (EIP-1967/EIP-1167), ERC-20, ERC-721, ERC-165. Shows bytecode size and implementation address for proxies. ### 8. Whale Detection ```bash -python3 $SCRIPT whale # ETH, last 20 blocks, >$10k -python3 $SCRIPT whale --blocks 50 --min-usd 50000 --chain bsc +python $SCRIPT whale # ETH, last 20 blocks, >$10k +python $SCRIPT whale --blocks 50 --min-usd 50000 --chain bsc ``` ### 9. Gas Tracker ```bash -python3 $SCRIPT gas -python3 $SCRIPT gas --chain polygon +python $SCRIPT gas +python $SCRIPT gas --chain polygon ``` Shows gwei price + USD cost for: transfer, ERC-20 transfer, approve, swap, NFT mint, NFT transfer. @@ -220,8 +220,8 @@ Shows gwei price + USD cost for: transfer, ERC-20 transfer, approve, swap, NFT m ## Verification ```bash # Should print current block, gas price, ETH price -python3 ~/.hermes/skills/blockchain/evm/scripts/evm_client.py stats +python ~/.hermes/skills/blockchain/evm/scripts/evm_client.py stats # Should resolve vitalik.eth to 0xd8dA... -python3 ~/.hermes/skills/blockchain/evm/scripts/evm_client.py ens vitalik.eth +python ~/.hermes/skills/blockchain/evm/scripts/evm_client.py ens vitalik.eth ``` diff --git a/website/docs/user-guide/skills/optional/blockchain/blockchain-hyperliquid.md b/website/docs/user-guide/skills/optional/blockchain/blockchain-hyperliquid.md index 177dfe36a1..2dba79dc9a 100644 --- a/website/docs/user-guide/skills/optional/blockchain/blockchain-hyperliquid.md +++ b/website/docs/user-guide/skills/optional/blockchain/blockchain-hyperliquid.md @@ -15,7 +15,7 @@ Hyperliquid market data, account history, trade review. | | | |---|---| | Source | Optional — install with `hermes skills install official/blockchain/hyperliquid` | -| Path | `optional-skills/blockchain/hyperliquid` | +| Path | `optional-skills/blockchain\hyperliquid` | | Version | `0.1.0` | | Author | Hugo Sequier (Hugo-SEQUIER), Hermes Agent | | License | MIT | @@ -72,7 +72,7 @@ Helper script: `~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_clie Invoke through the `terminal` tool: ```bash -python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py [args] +python ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py [args] ``` Add `--json` to any command for machine-readable output. @@ -106,12 +106,12 @@ optional when `HYPERLIQUID_USER_ADDRESS` is set in `${HERMES_HOME:-~/.hermes}/.e ### 1. Discover DEXs and Markets ```bash -python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py dexs +python ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py dexs -python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \ +python ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \ markets --limit 15 --sort volume -python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \ +python ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \ spots --limit 15 ``` @@ -122,10 +122,10 @@ python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \ ### 2. Pull Historical Market Data ```bash -python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \ +python ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \ candles BTC --interval 1h --hours 72 --limit 48 -python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \ +python ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \ funding BTC --hours 168 --limit 30 ``` @@ -135,7 +135,7 @@ Time-range endpoints paginate. For larger windows, repeat with a later ### 3. Inspect Live Order Book ```bash -python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \ +python ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \ l2 BTC --levels 10 ``` @@ -145,10 +145,10 @@ impact of a large order. ### 4. Review an Account ```bash -python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \ +python ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \ state 0xabc... -python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \ +python ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \ spot-balances ``` @@ -159,20 +159,20 @@ withdrawable?". ### 5. Review Fills and Orders ```bash -python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \ +python ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \ fills 0xabc... --hours 72 --limit 25 -python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \ +python ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \ orders --limit 25 ``` ### 6. Generate a Trade Review ```bash -python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \ +python ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \ review 0xabc... --hours 72 --fills 50 -python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \ +python ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \ review --coin BTC --hours 168 ``` @@ -188,10 +188,10 @@ from outcome quality. ### 7. Export a Reusable Dataset ```bash -python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \ +python ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \ export BTC --interval 1h --hours 168 --output ./btc-1h-7d.json -python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \ +python ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \ export BTC --interval 15m --hours 72 --end-time-ms 1760000000000 ``` @@ -221,7 +221,7 @@ normalized candle rows, normalized funding rows, summary stats. Use ## Verification ```bash -python3 ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \ +python ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \ markets --limit 5 ``` diff --git a/website/docs/user-guide/skills/optional/blockchain/blockchain-solana.md b/website/docs/user-guide/skills/optional/blockchain/blockchain-solana.md index f2c293ef7c..a9b4c55b7e 100644 --- a/website/docs/user-guide/skills/optional/blockchain/blockchain-solana.md +++ b/website/docs/user-guide/skills/optional/blockchain/blockchain-solana.md @@ -15,7 +15,7 @@ Query Solana wallets, tokens, txs, and NFTs in USD. | | | |---|---| | Source | Optional — install with `hermes skills install official/blockchain/solana` | -| Path | `optional-skills/blockchain/solana` | +| Path | `optional-skills/blockchain\solana` | | Version | `0.2.0` | | Author | Deniz Alagoz (gizdusum), enhanced by Hermes Agent | | License | MIT | @@ -69,14 +69,14 @@ Override: export SOLANA_RPC_URL=https://your-private-rpc.com Helper script path: ~/.hermes/skills/blockchain/solana/scripts/solana_client.py ``` -python3 solana_client.py wallet
[--limit N] [--all] [--no-prices] -python3 solana_client.py tx -python3 solana_client.py token -python3 solana_client.py activity
[--limit N] -python3 solana_client.py nft
-python3 solana_client.py whales [--min-sol N] -python3 solana_client.py stats -python3 solana_client.py price +python solana_client.py wallet
[--limit N] [--all] [--no-prices] +python solana_client.py tx +python solana_client.py token +python solana_client.py activity
[--limit N] +python solana_client.py nft
+python solana_client.py whales [--min-sol N] +python solana_client.py stats +python solana_client.py price ``` --- @@ -86,13 +86,13 @@ python3 solana_client.py price ### 0. Setup Check ```bash -python3 --version +python --version # Optional: set a private RPC for better rate limits export SOLANA_RPC_URL="https://api.mainnet-beta.solana.com" # Confirm connectivity -python3 ~/.hermes/skills/blockchain/solana/scripts/solana_client.py stats +python ~/.hermes/skills/blockchain/solana/scripts/solana_client.py stats ``` ### 1. Wallet Portfolio @@ -102,7 +102,7 @@ portfolio total. Tokens sorted by value, dust filtered, known tokens labeled by name (BONK, JUP, USDC, etc.). ```bash -python3 ~/.hermes/skills/blockchain/solana/scripts/solana_client.py \ +python ~/.hermes/skills/blockchain/solana/scripts/solana_client.py \ wallet 9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM ``` @@ -120,7 +120,7 @@ Inspect a full transaction by its base58 signature. Shows balance changes in both SOL and USD. ```bash -python3 ~/.hermes/skills/blockchain/solana/scripts/solana_client.py \ +python ~/.hermes/skills/blockchain/solana/scripts/solana_client.py \ tx 5j7s8K...your_signature_here ``` @@ -133,7 +133,7 @@ Get SPL token metadata, current price, market cap, supply, decimals, mint/freeze authorities, and top 5 holders. ```bash -python3 ~/.hermes/skills/blockchain/solana/scripts/solana_client.py \ +python ~/.hermes/skills/blockchain/solana/scripts/solana_client.py \ token DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263 ``` @@ -145,7 +145,7 @@ holders with percentages. List recent transactions for an address (default: last 10, max: 25). ```bash -python3 ~/.hermes/skills/blockchain/solana/scripts/solana_client.py \ +python ~/.hermes/skills/blockchain/solana/scripts/solana_client.py \ activity 9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM --limit 25 ``` @@ -154,7 +154,7 @@ python3 ~/.hermes/skills/blockchain/solana/scripts/solana_client.py \ List NFTs owned by a wallet (heuristic: SPL tokens with amount=1, decimals=0). ```bash -python3 ~/.hermes/skills/blockchain/solana/scripts/solana_client.py \ +python ~/.hermes/skills/blockchain/solana/scripts/solana_client.py \ nft 9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM ``` @@ -165,7 +165,7 @@ Note: Compressed NFTs (cNFTs) are not detected by this heuristic. Scan the most recent block for large SOL transfers with USD values. ```bash -python3 ~/.hermes/skills/blockchain/solana/scripts/solana_client.py \ +python ~/.hermes/skills/blockchain/solana/scripts/solana_client.py \ whales --min-sol 500 ``` @@ -177,7 +177,7 @@ Live Solana network health: current slot, epoch, TPS, supply, validator version, SOL price, and market cap. ```bash -python3 ~/.hermes/skills/blockchain/solana/scripts/solana_client.py stats +python ~/.hermes/skills/blockchain/solana/scripts/solana_client.py stats ``` ### 8. Price Lookup @@ -185,10 +185,10 @@ python3 ~/.hermes/skills/blockchain/solana/scripts/solana_client.py stats Quick price check for any token by mint address or known symbol. ```bash -python3 ~/.hermes/skills/blockchain/solana/scripts/solana_client.py price BONK -python3 ~/.hermes/skills/blockchain/solana/scripts/solana_client.py price JUP -python3 ~/.hermes/skills/blockchain/solana/scripts/solana_client.py price SOL -python3 ~/.hermes/skills/blockchain/solana/scripts/solana_client.py price DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263 +python ~/.hermes/skills/blockchain/solana/scripts/solana_client.py price BONK +python ~/.hermes/skills/blockchain/solana/scripts/solana_client.py price JUP +python ~/.hermes/skills/blockchain/solana/scripts/solana_client.py price SOL +python ~/.hermes/skills/blockchain/solana/scripts/solana_client.py price DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263 ``` Known symbols: SOL, USDC, USDT, BONK, JUP, WETH, JTO, mSOL, stSOL, @@ -221,5 +221,5 @@ PYTH, HNT, RNDR, WEN, W, TNSR, DRIFT, bSOL, JLP, WIF, MEW, BOME, PENGU. ```bash # Should print current Solana slot, TPS, and SOL price -python3 ~/.hermes/skills/blockchain/solana/scripts/solana_client.py stats +python ~/.hermes/skills/blockchain/solana/scripts/solana_client.py stats ``` diff --git a/website/docs/user-guide/skills/optional/communication/communication-one-three-one-rule.md b/website/docs/user-guide/skills/optional/communication/communication-one-three-one-rule.md index c0471b16ee..ff2a994e86 100644 --- a/website/docs/user-guide/skills/optional/communication/communication-one-three-one-rule.md +++ b/website/docs/user-guide/skills/optional/communication/communication-one-three-one-rule.md @@ -15,7 +15,7 @@ description: "1-3-1 decision briefs: problem, three options, one pick" | | | |---|---| | Source | Optional — install with `hermes skills install official/communication/one-three-one-rule` | -| Path | `optional-skills/communication/one-three-one-rule` | +| Path | `optional-skills/communication\one-three-one-rule` | | Version | `1.0.0` | | Author | Willard Moore | | License | MIT | diff --git a/website/docs/user-guide/skills/optional/creative/creative-ascii-art.md b/website/docs/user-guide/skills/optional/creative/creative-ascii-art.md new file mode 100644 index 0000000000..7a04bb125d --- /dev/null +++ b/website/docs/user-guide/skills/optional/creative/creative-ascii-art.md @@ -0,0 +1,338 @@ +--- +title: "Ascii Art — ASCII art: pyfiglet, cowsay, boxes, image-to-ascii" +sidebar_label: "Ascii Art" +description: "ASCII art: pyfiglet, cowsay, boxes, image-to-ascii" +--- + +{/* 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. */} + +# Ascii Art + +ASCII art: pyfiglet, cowsay, boxes, image-to-ascii. + +## Skill metadata + +| | | +|---|---| +| Source | Optional — install with `hermes skills install official/creative/ascii-art` | +| Path | `optional-skills/creative\ascii-art` | +| Version | `4.0.0` | +| Author | 0xbyt4, Hermes Agent | +| License | MIT | +| Platforms | linux, macos, windows | +| Tags | `ASCII`, `Art`, `Banners`, `Creative`, `Unicode`, `Text-Art`, `pyfiglet`, `figlet`, `cowsay`, `boxes` | +| Related skills | [`excalidraw`](/docs/user-guide/skills/optional/creative/creative-excalidraw) | + +## 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. +::: + +# ASCII Art Skill + +Multiple tools for different ASCII art needs. All tools are local CLI programs or free REST APIs — no API keys required. + +## Tool 1: Text Banners (pyfiglet — local) + +Render text as large ASCII art banners. 571 built-in fonts. + +### Setup + +```bash +pip install pyfiglet --break-system-packages -q +``` + +### Usage + +```bash +python -m pyfiglet "YOUR TEXT" -f slant +python -m pyfiglet "TEXT" -f doom -w 80 # Set width +python -m pyfiglet --list_fonts # List all 571 fonts +``` + +### Recommended fonts + +| Style | Font | Best for | +|-------|------|----------| +| Clean & modern | `slant` | Project names, headers | +| Bold & blocky | `doom` | Titles, logos | +| Big & readable | `big` | Banners | +| Classic banner | `banner3` | Wide displays | +| Compact | `small` | Subtitles | +| Cyberpunk | `cyberlarge` | Tech themes | +| 3D effect | `3-d` | Splash screens | +| Gothic | `gothic` | Dramatic text | + +### Tips + +- Preview 2-3 fonts and let the user pick their favorite +- Short text (1-8 chars) works best with detailed fonts like `doom` or `block` +- Long text works better with compact fonts like `small` or `mini` + +## Tool 2: Text Banners (asciified API — remote, no install) + +Free REST API that converts text to ASCII art. 250+ FIGlet fonts. Returns plain text directly — no parsing needed. Use this when pyfiglet is not installed or as a quick alternative. + +### Usage (via terminal curl) + +```bash +# Basic text banner (default font) +curl -s "https://asciified.thelicato.io/api/v2/ascii?text=Hello+World" + +# With a specific font +curl -s "https://asciified.thelicato.io/api/v2/ascii?text=Hello&font=Slant" +curl -s "https://asciified.thelicato.io/api/v2/ascii?text=Hello&font=Doom" +curl -s "https://asciified.thelicato.io/api/v2/ascii?text=Hello&font=Star+Wars" +curl -s "https://asciified.thelicato.io/api/v2/ascii?text=Hello&font=3-D" +curl -s "https://asciified.thelicato.io/api/v2/ascii?text=Hello&font=Banner3" + +# List all available fonts (returns JSON array) +curl -s "https://asciified.thelicato.io/api/v2/fonts" +``` + +### Tips + +- URL-encode spaces as `+` in the text parameter +- The response is plain text ASCII art — no JSON wrapping, ready to display +- Font names are case-sensitive; use the fonts endpoint to get exact names +- Works from any terminal with curl — no Python or pip needed + +## Tool 3: Cowsay (Message Art) + +Classic tool that wraps text in a speech bubble with an ASCII character. + +### Setup + +```bash +sudo apt install cowsay -y # Debian/Ubuntu +# brew install cowsay # macOS +``` + +### Usage + +```bash +cowsay "Hello World" +cowsay -f tux "Linux rules" # Tux the penguin +cowsay -f dragon "Rawr!" # Dragon +cowsay -f stegosaurus "Roar!" # Stegosaurus +cowthink "Hmm..." # Thought bubble +cowsay -l # List all characters +``` + +### Available characters (50+) + +`beavis.zen`, `bong`, `bunny`, `cheese`, `daemon`, `default`, `dragon`, +`dragon-and-cow`, `elephant`, `eyes`, `flaming-skull`, `ghostbusters`, +`hellokitty`, `kiss`, `kitty`, `koala`, `luke-koala`, `mech-and-cow`, +`meow`, `moofasa`, `moose`, `ren`, `sheep`, `skeleton`, `small`, +`stegosaurus`, `stimpy`, `supermilker`, `surgery`, `three-eyes`, +`turkey`, `turtle`, `tux`, `udder`, `vader`, `vader-koala`, `www` + +### Eye/tongue modifiers + +```bash +cowsay -b "Borg" # =_= eyes +cowsay -d "Dead" # x_x eyes +cowsay -g "Greedy" # $_$ eyes +cowsay -p "Paranoid" # @_@ eyes +cowsay -s "Stoned" # *_* eyes +cowsay -w "Wired" # O_O eyes +cowsay -e "OO" "Msg" # Custom eyes +cowsay -T "U " "Msg" # Custom tongue +``` + +## Tool 4: Boxes (Decorative Borders) + +Draw decorative ASCII art borders/frames around any text. 70+ built-in designs. + +### Setup + +```bash +sudo apt install boxes -y # Debian/Ubuntu +# brew install boxes # macOS +``` + +### Usage + +```bash +echo "Hello World" | boxes # Default box +echo "Hello World" | boxes -d stone # Stone border +echo "Hello World" | boxes -d parchment # Parchment scroll +echo "Hello World" | boxes -d cat # Cat border +echo "Hello World" | boxes -d dog # Dog border +echo "Hello World" | boxes -d unicornsay # Unicorn +echo "Hello World" | boxes -d diamonds # Diamond pattern +echo "Hello World" | boxes -d c-cmt # C-style comment +echo "Hello World" | boxes -d html-cmt # HTML comment +echo "Hello World" | boxes -a c # Center text +boxes -l # List all 70+ designs +``` + +### Combine with pyfiglet or asciified + +```bash +python -m pyfiglet "HERMES" -f slant | boxes -d stone +# Or without pyfiglet installed: +curl -s "https://asciified.thelicato.io/api/v2/ascii?text=HERMES&font=Slant" | boxes -d stone +``` + +## Tool 5: TOIlet (Colored Text Art) + +Like pyfiglet but with ANSI color effects and visual filters. Great for terminal eye candy. + +### Setup + +```bash +sudo apt install toilet toilet-fonts -y # Debian/Ubuntu +# brew install toilet # macOS +``` + +### Usage + +```bash +toilet "Hello World" # Basic text art +toilet -f bigmono12 "Hello" # Specific font +toilet --gay "Rainbow!" # Rainbow coloring +toilet --metal "Metal!" # Metallic effect +toilet -F border "Bordered" # Add border +toilet -F border --gay "Fancy!" # Combined effects +toilet -f pagga "Block" # Block-style font (unique to toilet) +toilet -F list # List available filters +``` + +### Filters + +`crop`, `gay` (rainbow), `metal`, `flip`, `flop`, `180`, `left`, `right`, `border` + +**Note**: toilet outputs ANSI escape codes for colors — works in terminals but may not render in all contexts (e.g., plain text files, some chat platforms). + +## Tool 6: Image to ASCII Art + +Convert images (PNG, JPEG, GIF, WEBP) to ASCII art. + +### Option A: ascii-image-converter (recommended, modern) + +```bash +# Install +sudo snap install ascii-image-converter +# OR: go install github.com/TheZoraiz/ascii-image-converter@latest +``` + +```bash +ascii-image-converter image.png # Basic +ascii-image-converter image.png -C # Color output +ascii-image-converter image.png -d 60,30 # Set dimensions +ascii-image-converter image.png -b # Braille characters +ascii-image-converter image.png -n # Negative/inverted +ascii-image-converter https://url/image.jpg # Direct URL +ascii-image-converter image.png --save-txt out # Save as text +``` + +### Option B: jp2a (lightweight, JPEG only) + +```bash +sudo apt install jp2a -y +jp2a --width=80 image.jpg +jp2a --colors image.jpg # Colorized +``` + +## Tool 7: Search Pre-Made ASCII Art + +Search curated ASCII art from the web. Use `terminal` with `curl`. + +### Source A: ascii.co.uk (recommended for pre-made art) + +Large collection of classic ASCII art organized by subject. Art is inside HTML `
` tags. Fetch the page with curl, then extract art with a small Python snippet.
+
+**URL pattern:** `https://ascii.co.uk/art/{subject}`
+
+**Step 1 — Fetch the page:**
+
+```bash
+curl -s 'https://ascii.co.uk/art/cat' -o /tmp/ascii_art.html
+```
+
+**Step 2 — Extract art from pre tags:**
+
+```python
+import re, html
+with open('/tmp/ascii_art.html') as f:
+    text = f.read()
+arts = re.findall(r']*>(.*?)
', text, re.DOTALL) +for art in arts: + clean = re.sub(r'<[^>]+>', '', art) + clean = html.unescape(clean).strip() + if len(clean) > 30: + print(clean) + print('\n---\n') +``` + +**Available subjects** (use as URL path): +- Animals: `cat`, `dog`, `horse`, `bird`, `fish`, `dragon`, `snake`, `rabbit`, `elephant`, `dolphin`, `butterfly`, `owl`, `wolf`, `bear`, `penguin`, `turtle` +- Objects: `car`, `ship`, `airplane`, `rocket`, `guitar`, `computer`, `coffee`, `beer`, `cake`, `house`, `castle`, `sword`, `crown`, `key` +- Nature: `tree`, `flower`, `sun`, `moon`, `star`, `mountain`, `ocean`, `rainbow` +- Characters: `skull`, `robot`, `angel`, `wizard`, `pirate`, `ninja`, `alien` +- Holidays: `christmas`, `halloween`, `valentine` + +**Tips:** +- Preserve artist signatures/initials — important etiquette +- Multiple art pieces per page — pick the best one for the user +- Works reliably via curl, no JavaScript needed + +### Source B: GitHub Octocat API (fun easter egg) + +Returns a random GitHub Octocat with a wise quote. No auth needed. + +```bash +curl -s https://api.github.com/octocat +``` + +## Tool 8: Fun ASCII Utilities (via curl) + +These free services return ASCII art directly — great for fun extras. + +### QR Codes as ASCII Art + +```bash +curl -s "qrenco.de/Hello+World" +curl -s "qrenco.de/https://example.com" +``` + +### Weather as ASCII Art + +```bash +curl -s "wttr.in/London" # Full weather report with ASCII graphics +curl -s "wttr.in/Moon" # Moon phase in ASCII art +curl -s "v2.wttr.in/London" # Detailed version +``` + +## Tool 9: LLM-Generated Custom Art (Fallback) + +When tools above don't have what's needed, generate ASCII art directly using these Unicode characters: + +### Character Palette + +**Box Drawing:** `╔ ╗ ╚ ╝ ║ ═ ╠ ╣ ╦ ╩ ╬ ┌ ┐ └ ┘ │ ─ ├ ┤ ┬ ┴ ┼ ╭ ╮ ╰ ╯` + +**Block Elements:** `░ ▒ ▓ █ ▄ ▀ ▌ ▐ ▖ ▗ ▘ ▝ ▚ ▞` + +**Geometric & Symbols:** `◆ ◇ ◈ ● ○ ◉ ■ □ ▲ △ ▼ ▽ ★ ☆ ✦ ✧ ◀ ▶ ◁ ▷ ⬡ ⬢ ⌂` + +### Rules + +- Max width: 60 characters per line (terminal-safe) +- Max height: 15 lines for banners, 25 for scenes +- Monospace only: output must render correctly in fixed-width fonts + +## Decision Flow + +1. **Text as a banner** → pyfiglet if installed, otherwise asciified API via curl +2. **Wrap a message in fun character art** → cowsay +3. **Add decorative border/frame** → boxes (can combine with pyfiglet/asciified) +4. **Art of a specific thing** (cat, rocket, dragon) → ascii.co.uk via curl + parsing +5. **Convert an image to ASCII** → ascii-image-converter or jp2a +6. **QR code** → qrenco.de via curl +7. **Weather/moon art** → wttr.in via curl +8. **Something custom/creative** → LLM generation with Unicode palette +9. **Any tool not installed** → install it, or fall back to next option diff --git a/website/docs/user-guide/skills/optional/creative/creative-audiocraft-audio-generation.md b/website/docs/user-guide/skills/optional/creative/creative-audiocraft-audio-generation.md index 418ab5e652..3a8c99319f 100644 --- a/website/docs/user-guide/skills/optional/creative/creative-audiocraft-audio-generation.md +++ b/website/docs/user-guide/skills/optional/creative/creative-audiocraft-audio-generation.md @@ -15,7 +15,7 @@ AudioCraft: MusicGen text-to-music, AudioGen text-to-sound. | | | |---|---| | Source | Optional — install with `hermes skills install official/creative/audiocraft-audio-generation` | -| Path | `optional-skills/creative/audiocraft-audio-generation` | +| Path | `optional-skills/creative\audiocraft-audio-generation` | | Version | `1.0.0` | | Author | Orchestra Research | | License | MIT | @@ -576,8 +576,8 @@ for desc in descriptions: ## References -- **[Advanced Usage](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative/audiocraft-audio-generation/references/advanced-usage.md)** - Training, fine-tuning, deployment -- **[Troubleshooting](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative/audiocraft-audio-generation/references/troubleshooting.md)** - Common issues and solutions +- **[Advanced Usage](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative\audiocraft-audio-generation/references/advanced-usage.md)** - Training, fine-tuning, deployment +- **[Troubleshooting](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative\audiocraft-audio-generation/references/troubleshooting.md)** - Common issues and solutions ## Resources diff --git a/website/docs/user-guide/skills/optional/creative/creative-baoyu-article-illustrator.md b/website/docs/user-guide/skills/optional/creative/creative-baoyu-article-illustrator.md index 2fbe498b78..f6a7395b28 100644 --- a/website/docs/user-guide/skills/optional/creative/creative-baoyu-article-illustrator.md +++ b/website/docs/user-guide/skills/optional/creative/creative-baoyu-article-illustrator.md @@ -15,7 +15,7 @@ Article illustrations: type × style × palette consistency. | | | |---|---| | Source | Optional — install with `hermes skills install official/creative/baoyu-article-illustrator` | -| Path | `optional-skills/creative/baoyu-article-illustrator` | +| Path | `optional-skills/creative\baoyu-article-illustrator` | | Version | `1.57.0` | | Author | 宝玉 (JimLiu) | | License | MIT | @@ -48,7 +48,7 @@ Trigger this skill when the user asks to illustrate an article, add images to an Combine freely: `type=infographic, style=vector-illustration, palette=macaron`. -Or use presets: `edu-visual` → type + style + palette in one shot. See [style-presets.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative/baoyu-article-illustrator/references/style-presets.md). +Or use presets: `edu-visual` → type + style + palette in one shot. See [style-presets.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative\baoyu-article-illustrator/references/style-presets.md). ## Types @@ -63,7 +63,7 @@ Or use presets: `edu-visual` → type + style + palette in one shot. See [style- ## Styles -See [references/styles.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative/baoyu-article-illustrator/references/styles.md) for Core Styles, the full gallery, and Type × Style compatibility. +See [references/styles.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative\baoyu-article-illustrator/references/styles.md) for Core Styles, the full gallery, and Type × Style compatibility. ## Output Structure @@ -116,7 +116,7 @@ If the user supplies reference images (paths pasted inline, attachments, or a UR 2. **Do not** try to copy the binary via `write_file` / `read_file` — those are text-only. If you want a local copy for the record, use `terminal` (`cp "$src" "{output-dir}/references/NN-ref-{slug}.{ext}"`). The skill itself never needs to read the binary; it works off the vision description. 3. Since `image_generate` doesn't take image inputs, the vision description is what gets embedded in prompts during Step 5. -Full procedures: [references/workflow.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative/baoyu-article-illustrator/references/workflow.md#step-1-detect-reference-images). +Full procedures: [references/workflow.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative\baoyu-article-illustrator/references/workflow.md#step-1-detect-reference-images). ### Step 2: Analyze @@ -129,7 +129,7 @@ Full procedures: [references/workflow.md](https://github.com/NousResearch/hermes Read source (file path → `read_file`, or pasted text) and write the analysis to `{output-dir}/analysis.md` using `write_file`. -Full procedures: [references/workflow.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative/baoyu-article-illustrator/references/workflow.md#step-2-analyze). +Full procedures: [references/workflow.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative\baoyu-article-illustrator/references/workflow.md#step-2-analyze). ### Step 3: Confirm Settings @@ -145,7 +145,7 @@ Use the `clarify` tool. Since `clarify` handles one question at a time, ask the Don't ask more than 2-3 `clarify` questions in a row. If the user already specified these in their request, skip entirely. -Full procedures: [references/workflow.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative/baoyu-article-illustrator/references/workflow.md#step-3-confirm-settings). +Full procedures: [references/workflow.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative\baoyu-article-illustrator/references/workflow.md#step-3-confirm-settings). ### Step 4: Generate Outline → `outline.md` @@ -159,7 +159,7 @@ Save `{output-dir}/outline.md` using `write_file` with frontmatter (type, densit **Filename**: 01-infographic-concept-name.png ``` -Full template: [references/workflow.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative/baoyu-article-illustrator/references/workflow.md#step-4-generate-outline). +Full template: [references/workflow.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative\baoyu-article-illustrator/references/workflow.md#step-4-generate-outline). ### Step 5: Generate Prompts @@ -167,7 +167,7 @@ Full template: [references/workflow.md](https://github.com/NousResearch/hermes-a For each illustration: -1. Create a prompt file per [references/prompt-construction.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative/baoyu-article-illustrator/references/prompt-construction.md). +1. Create a prompt file per [references/prompt-construction.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative\baoyu-article-illustrator/references/prompt-construction.md). 2. Save to `{output-dir}/prompts/NN-{type}-{slug}.md` using `write_file` with YAML frontmatter. 3. Prompts MUST use type-specific templates with structured sections (ZONES / LABELS / COLORS / STYLE / ASPECT). 4. LABELS MUST include article-specific data: actual numbers, terms, metrics, quotes. @@ -186,7 +186,7 @@ Note: the underlying image-generation backend is user-configured (default: FAL F ### Step 7: Finalize -Insert `![description](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative/baoyu-article-illustrator/{relative-path}/NN-{type}-{slug}.png)` after the corresponding paragraph. Alt text: concise description in the article's language. +Insert `![description](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative\baoyu-article-illustrator/{relative-path}/NN-{type}-{slug}.png)` after the corresponding paragraph. Alt text: concise description in the article's language. Report: @@ -208,11 +208,11 @@ Images: X/N generated | File | Content | |------|---------| -| [references/workflow.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative/baoyu-article-illustrator/references/workflow.md) | Detailed procedures | -| [references/usage.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative/baoyu-article-illustrator/references/usage.md) | Invocation examples | -| [references/styles.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative/baoyu-article-illustrator/references/styles.md) | Style gallery + Palette gallery | -| [references/style-presets.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative/baoyu-article-illustrator/references/style-presets.md) | Preset shortcuts (type + style + palette) | -| [references/prompt-construction.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative/baoyu-article-illustrator/references/prompt-construction.md) | Prompt templates | +| [references/workflow.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative\baoyu-article-illustrator/references/workflow.md) | Detailed procedures | +| [references/usage.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative\baoyu-article-illustrator/references/usage.md) | Invocation examples | +| [references/styles.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative\baoyu-article-illustrator/references/styles.md) | Style gallery + Palette gallery | +| [references/style-presets.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative\baoyu-article-illustrator/references/style-presets.md) | Preset shortcuts (type + style + palette) | +| [references/prompt-construction.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative\baoyu-article-illustrator/references/prompt-construction.md) | Prompt templates | ## Pitfalls diff --git a/website/docs/user-guide/skills/optional/creative/creative-baoyu-comic.md b/website/docs/user-guide/skills/optional/creative/creative-baoyu-comic.md index 88fdc93af6..6a41cf8589 100644 --- a/website/docs/user-guide/skills/optional/creative/creative-baoyu-comic.md +++ b/website/docs/user-guide/skills/optional/creative/creative-baoyu-comic.md @@ -15,7 +15,7 @@ Knowledge comics (知识漫画): educational, biography, tutorial. | | | |---|---| | Source | Optional — install with `hermes skills install official/creative/baoyu-comic` | -| Path | `optional-skills/creative/baoyu-comic` | +| Path | `optional-skills/creative\baoyu-comic` | | Version | `1.56.1` | | Author | 宝玉 (JimLiu) | | License | MIT | @@ -89,7 +89,7 @@ Character consistency is driven by **text descriptions** in `characters/characte | Images only | Generate images from existing prompts directory | | Regenerate N | Regenerate specific page(s) only (e.g., `3` or `2,5,8`) | -Details: [references/partial-workflows.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative/baoyu-comic/references/partial-workflows.md) +Details: [references/partial-workflows.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative\baoyu-comic/references/partial-workflows.md) ### Art, Tone & Preset Catalogue @@ -107,7 +107,7 @@ Details: [references/partial-workflows.md](https://github.com/NousResearch/herme Full rules at `references/presets/.md` — load the file when a preset is picked. -- **Compatibility matrix** and **content-signal → preset** table live in [references/auto-selection.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative/baoyu-comic/references/auto-selection.md). Read it before recommending combinations in Step 2. +- **Compatibility matrix** and **content-signal → preset** table live in [references/auto-selection.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative\baoyu-comic/references/auto-selection.md). Read it before recommending combinations in Step 2. ## File Structure @@ -185,7 +185,7 @@ Input → Analyze → [Check Existing?] → [Confirm: Style + Reviews] → Story ### User Questions -Use the `clarify` tool to confirm options. Since `clarify` handles one question at a time, ask the most important question first and proceed sequentially. See [references/workflow.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative/baoyu-comic/references/workflow.md) for the full Step 2 question set. +Use the `clarify` tool to confirm options. Since `clarify` handles one question at a time, ask the most important question first and proceed sequentially. See [references/workflow.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative\baoyu-comic/references/workflow.md) for the full Step 2 question set. **Timeout handling (CRITICAL)**: `clarify` can return `"The user did not provide a response within the time limit. Use your best judgement to make the choice and proceed."` — this is NOT user consent to default everything. @@ -221,15 +221,15 @@ Use Hermes' built-in `image_generate` tool for all image rendering. Its schema a **Backup rule**: existing `prompts/…md` and `…png` files → rename with `-backup-YYYYMMDD-HHMMSS` suffix before regenerating. -Full step-by-step workflow (analysis, storyboard, review gates, regeneration variants): [references/workflow.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative/baoyu-comic/references/workflow.md). +Full step-by-step workflow (analysis, storyboard, review gates, regeneration variants): [references/workflow.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative\baoyu-comic/references/workflow.md). ## References **Core Templates**: -- [analysis-framework.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative/baoyu-comic/references/analysis-framework.md) - Deep content analysis -- [character-template.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative/baoyu-comic/references/character-template.md) - Character definition format -- [storyboard-template.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative/baoyu-comic/references/storyboard-template.md) - Storyboard structure -- [ohmsha-guide.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative/baoyu-comic/references/ohmsha-guide.md) - Ohmsha manga specifics +- [analysis-framework.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative\baoyu-comic/references/analysis-framework.md) - Deep content analysis +- [character-template.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative\baoyu-comic/references/character-template.md) - Character definition format +- [storyboard-template.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative\baoyu-comic/references/storyboard-template.md) - Storyboard structure +- [ohmsha-guide.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative\baoyu-comic/references/ohmsha-guide.md) - Ohmsha manga specifics **Style Definitions**: - `references/art-styles/` - Art styles (ligne-claire, manga, realistic, ink-brush, chalk, minimalist) @@ -238,9 +238,9 @@ Full step-by-step workflow (analysis, storyboard, review gates, regeneration var - `references/layouts/` - Layouts (standard, cinematic, dense, splash, mixed, webtoon, four-panel) **Workflow**: -- [workflow.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative/baoyu-comic/references/workflow.md) - Full workflow details -- [auto-selection.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative/baoyu-comic/references/auto-selection.md) - Content signal analysis -- [partial-workflows.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative/baoyu-comic/references/partial-workflows.md) - Partial workflow options +- [workflow.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative\baoyu-comic/references/workflow.md) - Full workflow details +- [auto-selection.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative\baoyu-comic/references/auto-selection.md) - Content signal analysis +- [partial-workflows.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative\baoyu-comic/references/partial-workflows.md) - Partial workflow options ## Page Modification diff --git a/website/docs/user-guide/skills/optional/creative/creative-comfyui.md b/website/docs/user-guide/skills/optional/creative/creative-comfyui.md new file mode 100644 index 0000000000..418bf365c5 --- /dev/null +++ b/website/docs/user-guide/skills/optional/creative/creative-comfyui.md @@ -0,0 +1,616 @@ +--- +title: "Comfyui — Generate images, video, and audio via diffusion workflows" +sidebar_label: "Comfyui" +description: "Generate images, video, and audio via diffusion workflows" +--- + +{/* 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. */} + +# Comfyui + +Generate images, video, and audio via diffusion workflows. + +## Skill metadata + +| | | +|---|---| +| Source | Optional — install with `hermes skills install official/creative/comfyui` | +| Path | `optional-skills/creative\comfyui` | +| Version | `5.1.0` | +| Author | ['kshitijk4poor', 'alt-glitch', 'purzbeats'] | +| License | MIT | +| Platforms | macos, linux, windows | +| Tags | `comfyui`, `image-generation`, `stable-diffusion`, `flux`, `sd3`, `wan-video`, `hunyuan-video`, `creative`, `generative-ai`, `video-generation` | +| Related skills | [`stable-diffusion`](/docs/user-guide/skills/optional/mlops/mlops-stable-diffusion) | + +## 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. +::: + +# ComfyUI + +Generate images, video, audio, and 3D content through ComfyUI using the +official `comfy-cli` for setup/lifecycle and direct REST/WebSocket API +for workflow execution. + +## What's in this skill + +**Reference docs (`references/`):** + +- `official-cli.md` — every `comfy ...` command, with flags +- `rest-api.md` — REST + WebSocket endpoints (local + cloud), payload schemas +- `workflow-format.md` — API-format JSON, common node types, param mapping +- `template-integrity.md` — converting `comfyui-workflow-templates` from + editor format to API format: Reroute bypass, dotted dynamic-input keys + (`values.a`, `resize_type.width`), Cloud quirks (302 redirect, 1 concurrent + free-tier job, 1080p VRAM ceiling), Discord-compatible ffmpeg stitch. + Authored by [@purzbeats](https://github.com/purzbeats). Load this whenever + you're starting from an official template. + +**Scripts (`scripts/`):** + +| Script | Purpose | +|--------|---------| +| `_common.py` | Shared HTTP, cloud routing, node catalogs (don't run directly) | +| `hardware_check.py` | Probe GPU/VRAM/disk → recommend local vs Comfy Cloud | +| `comfyui_setup.sh` | Hardware check + comfy-cli + ComfyUI install + launch + verify | +| `extract_schema.py` | Read a workflow → list controllable params + model deps | +| `check_deps.py` | Check workflow against running server → list missing nodes/models | +| `auto_fix_deps.py` | Run check_deps then `comfy node install` / `comfy model download` | +| `run_workflow.py` | Inject params, submit, monitor, download outputs (HTTP or WS) | +| `run_batch.py` | Submit a workflow N times with sweeps, parallel up to your tier | +| `ws_monitor.py` | Real-time WebSocket viewer for executing jobs (live progress) | +| `health_check.py` | Verification checklist runner — comfy-cli + server + models + smoke test | +| `fetch_logs.py` | Pull traceback / status messages for a given prompt_id | + +**Example workflows (`workflows/`):** SD 1.5, SDXL, Flux Dev, SDXL img2img, +SDXL inpaint, ESRGAN upscale, AnimateDiff video, Wan T2V. See +`workflows/README.md`. + +## When to Use + +- User asks to generate images with Stable Diffusion, SDXL, Flux, SD3, etc. +- User wants to run a specific ComfyUI workflow file +- User wants to chain generative steps (txt2img → upscale → face restore) +- User needs ControlNet, inpainting, img2img, or other advanced pipelines +- User asks to manage ComfyUI queue, check models, or install custom nodes +- User wants video/audio/3D generation via AnimateDiff, Hunyuan, Wan, AudioCraft, etc. + +## Architecture: Two Layers + + +``` +┌─────────────────────────────────────────────────────┐ +│ Layer 1: comfy-cli (official lifecycle tool) │ +│ Setup, server lifecycle, custom nodes, models │ +│ → comfy install / launch / stop / node / model │ +└─────────────────────────┬───────────────────────────┘ + │ +┌─────────────────────────▼───────────────────────────┐ +│ Layer 2: REST/WebSocket API + skill scripts │ +│ Workflow execution, param injection, monitoring │ +│ POST /api/prompt, GET /api/view, WS /ws │ +│ → run_workflow.py, run_batch.py, ws_monitor.py │ +└─────────────────────────────────────────────────────┘ +``` + + +**Why two layers?** The official CLI is excellent for installation and server +management but has minimal workflow execution support. The REST/WS API fills +that gap — the scripts handle param injection, execution monitoring, and +output download that the CLI doesn't do. + +## Quick Start + +### Detect environment + +```bash +# What's available? +command -v comfy >/dev/null 2>&1 && echo "comfy-cli: installed" +curl -s http://127.0.0.1:8188/system_stats 2>/dev/null && echo "server: running" + +# Can this machine run ComfyUI locally? (GPU/VRAM/disk check) +python scripts/hardware_check.py +``` + +If nothing is installed, see **Setup & Onboarding** below — but always run the +hardware check first. + +### One-line health check + +```bash +python scripts/health_check.py +# → JSON: comfy_cli on PATH? server reachable? at least one checkpoint? smoke-test passes? +``` + +## Core Workflow + +### Step 1: Get a workflow JSON in API format + +Workflows must be in API format (each node has `class_type`). They come from: + +- ComfyUI web UI → **Workflow → Export (API)** (newer UI) or + the legacy "Save (API Format)" button (older UI) +- This skill's `workflows/` directory (ready-to-run examples) +- Community downloads (civitai, Reddit, Discord) — usually editor format, + must be loaded into ComfyUI then re-exported + +Editor format (top-level `nodes` and `links` arrays) is **not directly +executable**. The scripts detect this and tell you to re-export. + +### Step 2: See what's controllable + +```bash +python scripts/extract_schema.py workflow_api.json --summary-only +# → {"parameter_count": 12, "has_negative_prompt": true, "has_seed": true, ...} + +python scripts/extract_schema.py workflow_api.json +# → full schema with parameters, model deps, embedding refs +``` + +### Step 3: Run with parameters + +```bash +# Local (defaults to http://127.0.0.1:8188) +python scripts/run_workflow.py \ + --workflow workflow_api.json \ + --args '{"prompt": "a beautiful sunset over mountains", "seed": -1, "steps": 30}' \ + --output-dir ./outputs + +# Cloud (export API key once; uses correct /api routing automatically) +export COMFY_CLOUD_API_KEY="comfyui-..." +python scripts/run_workflow.py \ + --workflow workflow_api.json \ + --args '{"prompt": "..."}' \ + --host https://cloud.comfy.org \ + --output-dir ./outputs + +# Real-time progress via WebSocket (requires `pip install websocket-client`) +python scripts/run_workflow.py \ + --workflow flux_dev.json \ + --args '{"prompt": "..."}' \ + --ws + +# img2img / inpaint: pass --input-image to upload + reference automatically +python scripts/run_workflow.py \ + --workflow sdxl_img2img.json \ + --input-image image=./photo.png \ + --args '{"prompt": "make it watercolor", "denoise": 0.6}' + +# Batch / sweep: 8 random seeds, parallel up to cloud tier limit +python scripts/run_batch.py \ + --workflow sdxl.json \ + --args '{"prompt": "abstract"}' \ + --count 8 --randomize-seed --parallel 3 \ + --output-dir ./outputs/batch +``` + +`-1` for `seed` (or omitting it with `--randomize-seed`) generates a fresh +random seed per run. + +### Step 4: Present results + +The scripts emit JSON to stdout describing every output file: + +```json +{ + "status": "success", + "prompt_id": "abc-123", + "outputs": [ + {"file": "./outputs/sdxl_00001_.png", "node_id": "9", + "type": "image", "filename": "sdxl_00001_.png"} + ] +} +``` + +## Decision Tree + +| User says | Tool | Command | +|-----------|------|---------| +| **Lifecycle (use comfy-cli)** | | | +| "install ComfyUI" | comfy-cli | `bash scripts/comfyui_setup.sh` | +| "start ComfyUI" | comfy-cli | `comfy launch --background` | +| "stop ComfyUI" | comfy-cli | `comfy stop` | +| "install X node" | comfy-cli | `comfy node install ` | +| "download X model" | comfy-cli | `comfy model download --url --relative-path models/checkpoints` | +| "list installed models" | comfy-cli | `comfy model list` | +| "list installed nodes" | comfy-cli | `comfy node show installed` | +| **Execution (use scripts)** | | | +| "is everything ready?" | script | `health_check.py` (optionally with `--workflow X --smoke-test`) | +| "what can I change in this workflow?" | script | `extract_schema.py W.json` | +| "check if W's deps are met" | script | `check_deps.py W.json` | +| "fix missing deps" | script | `auto_fix_deps.py W.json` | +| "generate an image" | script | `run_workflow.py --workflow W --args '{...}'` | +| "use this image" (img2img) | script | `run_workflow.py --input-image image=./x.png ...` | +| "8 variations with random seeds" | script | `run_batch.py --count 8 --randomize-seed ...` | +| "show me live progress" | script | `ws_monitor.py --prompt-id ` | +| "fetch the error from job X" | script | `fetch_logs.py ` | +| **Direct REST** | | | +| "what's in the queue?" | REST | `curl http://HOST:8188/queue` (local) or `--host https://cloud.comfy.org` | +| "cancel that" | REST | `curl -X POST http://HOST:8188/interrupt` | +| "free GPU memory" | REST | `curl -X POST http://HOST:8188/free` | + +## Setup & Onboarding + +When a user asks to set up ComfyUI, **the FIRST thing to do is ask whether +they want Comfy Cloud (hosted, zero install, API key) or Local (install +ComfyUI on their machine)**. Don't start running install commands or hardware +checks until they've answered. + +**Official docs:** https://docs.comfy.org/installation +**CLI docs:** https://docs.comfy.org/comfy-cli/getting-started +**Cloud docs:** https://docs.comfy.org/get_started/cloud +**Cloud API:** https://docs.comfy.org/development/cloud/overview + +### Step 0: Ask Local vs Cloud (ALWAYS FIRST) + +Suggested script: + +> "Do you want to run ComfyUI locally on your machine, or use Comfy Cloud? +> +> - **Comfy Cloud** — hosted on RTX 6000 Pro GPUs, all common models pre-installed, +> zero setup. Requires an API key (paid subscription required to actually run +> workflows; free tier is read-only). Best if you don't have a capable GPU. +> - **Local** — free, but your machine MUST meet the hardware requirements: +> - NVIDIA GPU with **≥6 GB VRAM** (≥8 GB for SDXL, ≥12 GB for Flux/video), OR +> - AMD GPU with ROCm support (Linux), OR +> - Apple Silicon Mac (M1+) with **≥16 GB unified memory** (≥32 GB recommended). +> - Intel Macs and machines with no GPU will NOT work — use Cloud instead. +> +> Which would you like?" + +Routing: + +- **Cloud** → skip to **Path A**. +- **Local** → run hardware check first, then pick a path from Paths B–E based on the verdict. +- **Unsure** → run the hardware check and let the verdict decide. + +### Step 1: Verify Hardware (ONLY if user chose local) + +```bash +python scripts/hardware_check.py --json +# Optional: also probe `torch` for actual CUDA/MPS: +python scripts/hardware_check.py --json --check-pytorch +``` + +| Verdict | Meaning | Action | +|------------|---------------------------------------------------------------|--------| +| `ok` | ≥8 GB VRAM (discrete) OR ≥32 GB unified (Apple Silicon) | Local install — use `comfy_cli_flag` from report | +| `marginal` | SD1.5 works; SDXL tight; Flux/video unlikely | Local OK for light workflows, else **Path A (Cloud)** | +| `cloud` | No usable GPU, <6 GB VRAM, <16 GB Apple unified, Intel Mac, Rosetta Python | **Switch to Cloud** unless user explicitly forces local | + +The script also surfaces `wsl: true` (WSL2 with NVIDIA passthrough) and +`rosetta: true` (x86_64 Python on Apple Silicon — must reinstall as ARM64). + +If verdict is `cloud` but the user wants local, do not proceed silently. +Show the `notes` array verbatim and ask whether they want to (a) switch to +Cloud or (b) force a local install (will OOM or be unusably slow on modern models). + +### Choosing an Installation Path + +Use the hardware check first. The table below is the fallback for when the +user has already told you their hardware: + +| Situation | Recommended Path | +|-----------|------------------| +| `verdict: cloud` from hardware check | **Path A: Comfy Cloud** | +| No GPU / want to try without commitment | **Path A: Comfy Cloud** | +| Windows + NVIDIA + non-technical | **Path B: ComfyUI Desktop** | +| Windows + NVIDIA + technical | **Path C: Portable** or **Path D: comfy-cli** | +| Linux + any GPU | **Path D: comfy-cli** (easiest) | +| macOS + Apple Silicon | **Path B: Desktop** or **Path D: comfy-cli** | +| Headless / server / CI / agents | **Path D: comfy-cli** | + +For the fully automated path (hardware check → install → launch → verify): + +```bash +bash scripts/comfyui_setup.sh +# Or with overrides: +bash scripts/comfyui_setup.sh --m-series --port=8190 --workspace=/data/comfy +``` + +It runs `hardware_check.py` internally, refuses to install locally when the +verdict is `cloud` (unless `--force-cloud-override`), picks the right +`comfy-cli` flag, and prefers `pipx`/`uvx` over global `pip` to avoid polluting +system Python. + +--- + +### Path A: Comfy Cloud (No Local Install) + +For users without a capable GPU or who want zero setup. Hosted on RTX 6000 Pro. + +**Docs:** https://docs.comfy.org/get_started/cloud + +1. Sign up at https://comfy.org/cloud +2. Generate an API key at https://platform.comfy.org/login +3. Set the key: + ```bash + export COMFY_CLOUD_API_KEY="your-comfyui-key" + ``` +4. Run workflows: + ```bash + python scripts/run_workflow.py \ + --workflow workflows/flux_dev_txt2img.json \ + --args '{"prompt": "..."}' \ + --host https://cloud.comfy.org \ + --output-dir ./outputs + ``` + +**Pricing:** https://www.comfy.org/cloud/pricing +**Concurrent jobs:** Free/Standard 1, Creator 3, Pro 5. Free tier +**cannot run workflows via API** — only browse models. Paid subscription +required for `/api/prompt`, `/api/upload/*`, `/api/view`, etc. + +--- + +### Path B: ComfyUI Desktop (Windows / macOS) + +One-click installer for non-technical users. Currently Beta. + +**Docs:** https://docs.comfy.org/installation/desktop +- **Windows (NVIDIA):** https://download.comfy.org/windows/nsis/x64 +- **macOS (Apple Silicon):** https://comfy.org + +Linux is **not supported** for Desktop — use Path D. + +--- + +### Path C: ComfyUI Portable (Windows Only) + +**Docs:** https://docs.comfy.org/installation/comfyui_portable_windows + +Download from https://github.com/comfyanonymous/ComfyUI/releases, extract, +run `run_nvidia_gpu.bat`. Update via `update/update_comfyui_stable.bat`. + +--- + +### Path D: comfy-cli (All Platforms — Recommended for Agents) + +The official CLI is the best path for headless/automated setups. + +**Docs:** https://docs.comfy.org/comfy-cli/getting-started + +#### Install comfy-cli + +```bash +# Recommended: +pipx install comfy-cli +# Or use uvx without installing: +uvx --from comfy-cli comfy --help +# Or (if pipx/uvx unavailable): +pip install --user comfy-cli +``` + +Disable analytics non-interactively: +```bash +comfy --skip-prompt tracking disable +``` + +#### Install ComfyUI + +```bash +comfy --skip-prompt install --nvidia # NVIDIA (CUDA) +comfy --skip-prompt install --amd # AMD (ROCm, Linux) +comfy --skip-prompt install --m-series # Apple Silicon (MPS) +comfy --skip-prompt install --cpu # CPU only (slow) +comfy --skip-prompt install --nvidia --fast-deps # uv-based dep resolution +``` + +Default location: `~/comfy/ComfyUI` (Linux), `~/Documents/comfy/ComfyUI` +(macOS/Win). Override with `comfy --workspace /custom/path install`. + +#### Launch / verify + +```bash +comfy launch --background # background daemon on :8188 +comfy launch -- --listen 0.0.0.0 --port 8190 # LAN-accessible custom port +curl -s http://127.0.0.1:8188/system_stats # health check +``` + +--- + +### Path E: Manual Install (Advanced / Unsupported Hardware) + +For Ascend NPU, Cambricon MLU, Intel Arc, or other unsupported hardware. + +**Docs:** https://docs.comfy.org/installation/manual_install + +```bash +git clone https://github.com/comfyanonymous/ComfyUI.git +cd ComfyUI +pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu130 +pip install -r requirements.txt +python main.py +``` + +--- + +### Post-Install: Download Models + +```bash +# SDXL (general purpose, ~6.5 GB) +comfy model download \ + --url "https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0/resolve/main/sd_xl_base_1.0.safetensors" \ + --relative-path models/checkpoints + +# SD 1.5 (lighter, ~4 GB, good for 6 GB cards) +comfy model download \ + --url "https://huggingface.co/stable-diffusion-v1-5/stable-diffusion-v1-5/resolve/main/v1-5-pruned-emaonly.safetensors" \ + --relative-path models/checkpoints + +# Flux Dev fp8 (smaller variant, ~12 GB) +comfy model download \ + --url "https://huggingface.co/Comfy-Org/flux1-dev/resolve/main/flux1-dev-fp8.safetensors" \ + --relative-path models/checkpoints + +# CivitAI (set token first): +comfy model download \ + --url "https://civitai.com/api/download/models/128713" \ + --relative-path models/checkpoints \ + --set-civitai-api-token "YOUR_TOKEN" +``` + +List installed: `comfy model list`. + +### Post-Install: Install Custom Nodes + +```bash +comfy node install comfyui-impact-pack # popular utility pack +comfy node install comfyui-animatediff-evolved # video generation +comfy node install comfyui-controlnet-aux # ControlNet preprocessors +comfy node install comfyui-essentials # common helpers +comfy node update all +comfy node install-deps --workflow=workflow.json # install everything a workflow needs +``` + +### Post-Install: Verify + +```bash +python scripts/health_check.py +# → comfy_cli on PATH? server reachable? checkpoints? smoke test? + +python scripts/check_deps.py my_workflow.json +# → are this workflow's nodes/models/embeddings installed? + +python scripts/run_workflow.py \ + --workflow workflows/sd15_txt2img.json \ + --args '{"prompt": "test", "steps": 4}' \ + --output-dir ./test-outputs +``` + +## Image Upload (img2img / Inpainting) + +The simplest way is to use `--input-image` with `run_workflow.py`: + +```bash +python scripts/run_workflow.py \ + --workflow workflows/sdxl_img2img.json \ + --input-image image=./photo.png \ + --args '{"prompt": "make it cyberpunk", "denoise": 0.6}' +``` + +The flag uploads `photo.png`, then injects its server-side filename into +whatever schema parameter is named `image`. For inpainting, pass both: + +```bash +python scripts/run_workflow.py \ + --workflow workflows/sdxl_inpaint.json \ + --input-image image=./photo.png \ + --input-image mask_image=./mask.png \ + --args '{"prompt": "fill with flowers"}' +``` + +Manual upload via REST: +```bash +curl -X POST "http://127.0.0.1:8188/upload/image" \ + -F "image=@photo.png" -F "type=input" -F "overwrite=true" +# Returns: {"name": "photo.png", "subfolder": "", "type": "input"} + +# Cloud equivalent: +curl -X POST "https://cloud.comfy.org/api/upload/image" \ + -H "X-API-Key: $COMFY_CLOUD_API_KEY" \ + -F "image=@photo.png" -F "type=input" -F "overwrite=true" +``` + +## Cloud Specifics + +- **Base URL:** `https://cloud.comfy.org` +- **Auth:** `X-API-Key` header (or `?token=KEY` for WebSocket) +- **API key:** set `$COMFY_CLOUD_API_KEY` once and the scripts pick it up automatically +- **Output download:** `/api/view` returns a 302 to a signed URL; the scripts + follow it and strip `X-API-Key` before fetching from the storage backend + (don't leak the API key to S3/CloudFront). +- **Endpoint differences from local ComfyUI:** + - `/api/object_info`, `/api/queue`, `/api/userdata` — **403 on free tier**; + paid only. + - `/history` is renamed to `/history_v2` on cloud (the scripts route + automatically). + - `/models/` is renamed to `/experiment/models/` on cloud + (the scripts route automatically). + - `clientId` in WebSocket is currently ignored — all connections for a + user receive the same broadcast. Filter by `prompt_id` client-side. + - `subfolder` is accepted on uploads but ignored — cloud has a flat namespace. +- **Concurrent jobs:** Free/Standard: 1, Creator: 3, Pro: 5. Extras queue + automatically. Use `run_batch.py --parallel N` to saturate your tier. + +## Queue & System Management + +```bash +# Local +curl -s http://127.0.0.1:8188/queue | python -m json.tool +curl -X POST http://127.0.0.1:8188/queue -d '{"clear": true}' # cancel pending +curl -X POST http://127.0.0.1:8188/interrupt # cancel running +curl -X POST http://127.0.0.1:8188/free \ + -H "Content-Type: application/json" \ + -d '{"unload_models": true, "free_memory": true}' + +# Cloud — same paths under /api/, plus: +python scripts/fetch_logs.py --tail-queue --host https://cloud.comfy.org +``` + +## Pitfalls + +1. **API format required** — every script and the `/api/prompt` endpoint expect + API-format workflow JSON. The scripts detect editor format (top-level + `nodes` and `links` arrays) and tell you to re-export via + "Workflow → Export (API)" (newer UI) or "Save (API Format)" (older UI). + +2. **Server must be running** — all execution requires a live server. + `comfy launch --background` starts one. Verify with + `curl http://127.0.0.1:8188/system_stats`. + +3. **Model names are exact** — case-sensitive, includes file extension. + `check_deps.py` does fuzzy matching (with/without extension and folder + prefix), but the workflow itself must use the canonical name. Use + `comfy model list` to discover what's installed. + +4. **Missing custom nodes** — "class_type not found" means a required node + isn't installed. `check_deps.py` reports which package to install; + `auto_fix_deps.py` runs the install for you. + +5. **Working directory** — `comfy-cli` auto-detects the ComfyUI workspace. + If commands fail with "no workspace found", use + `comfy --workspace /path/to/ComfyUI ` or + `comfy set-default /path/to/ComfyUI`. + +6. **Cloud free-tier API limits** — `/api/prompt`, `/api/view`, `/api/upload/*`, + `/api/object_info` all return 403 on free accounts. `health_check.py` and + `check_deps.py` handle this gracefully and surface a clear message. + +7. **Timeout for video/audio workflows** — auto-detected when an output node + is `VHS_VideoCombine`, `SaveVideo`, etc.; the default jumps from 300 s to + 900 s. Override explicitly with `--timeout 1800`. + +8. **Path traversal in output filenames** — server-supplied filenames are + passed through `safe_path_join` to refuse anything escaping `--output-dir`. + Keep this protection on — workflows with custom save nodes can produce + arbitrary paths. + +9. **Workflow JSON is arbitrary code** — custom nodes run Python, so + submitting an unknown workflow has the same trust profile as `eval`. + Inspect workflows from untrusted sources before running. + +10. **Auto-randomized seed** — pass `seed: -1` in `--args` (or use + `--randomize-seed` and omit the seed) to get a fresh seed per run. + The actual seed is logged to stderr. + +11. **`tracking` prompt** — first run of `comfy` may prompt for analytics. + Use `comfy --skip-prompt tracking disable` to skip non-interactively. + `comfyui_setup.sh` does this for you. + +## Verification Checklist + +Use `python scripts/health_check.py` to run the whole list at once. Manual: + +- [ ] `hardware_check.py` verdict is `ok` OR the user explicitly chose Comfy Cloud +- [ ] `comfy --version` works (or `uvx --from comfy-cli comfy --help`) +- [ ] `curl http://HOST:PORT/system_stats` returns JSON +- [ ] `comfy model list` shows at least one checkpoint (local) OR + `/api/experiment/models/checkpoints` returns models (cloud) +- [ ] Workflow JSON is in API format +- [ ] `check_deps.py` reports `is_ready: true` (or only `node_check_skipped` + on cloud free tier) +- [ ] Test run with a small workflow completes; outputs land in `--output-dir` diff --git a/website/docs/user-guide/skills/optional/creative/creative-concept-diagrams.md b/website/docs/user-guide/skills/optional/creative/creative-concept-diagrams.md index 09ac135f4a..cc0bc64a8b 100644 --- a/website/docs/user-guide/skills/optional/creative/creative-concept-diagrams.md +++ b/website/docs/user-guide/skills/optional/creative/creative-concept-diagrams.md @@ -15,13 +15,13 @@ Generate flat, minimal educational SVG visuals as HTML. | | | |---|---| | Source | Optional — install with `hermes skills install official/creative/concept-diagrams` | -| Path | `optional-skills/creative/concept-diagrams` | +| Path | `optional-skills/creative\concept-diagrams` | | Version | `0.1.0` | | Author | v1k22 (original PR), ported into hermes-agent | | License | MIT | | Platforms | linux, macos, windows | | Tags | `diagrams`, `svg`, `visualization`, `education`, `physics`, `chemistry`, `engineering` | -| Related skills | [`architecture-diagram`](/docs/user-guide/skills/bundled/creative/creative-architecture-diagram), [`excalidraw`](/docs/user-guide/skills/bundled/creative/creative-excalidraw) | +| Related skills | [`architecture-diagram`](/docs/user-guide/skills/bundled/creative/creative-architecture-diagram), [`excalidraw`](/docs/user-guide/skills/optional/creative/creative-excalidraw) | ## Reference: full SKILL.md @@ -317,7 +317,7 @@ mkdir -p .diagrams/sn2-mechanism # ...write .diagrams/sn2-mechanism/index.html... # Serve on loopback only, free port -cd .diagrams && python3 -c " +cd .diagrams && python -c " import http.server, socketserver with socketserver.TCPServer(('127.0.0.1', 0), http.server.SimpleHTTPRequestHandler) as s: print(f'Serving at http://127.0.0.1:{s.server_address[1]}/') diff --git a/website/docs/user-guide/skills/optional/creative/creative-creative-ideation.md b/website/docs/user-guide/skills/optional/creative/creative-creative-ideation.md index 698b105eaa..2c023074c2 100644 --- a/website/docs/user-guide/skills/optional/creative/creative-creative-ideation.md +++ b/website/docs/user-guide/skills/optional/creative/creative-creative-ideation.md @@ -15,7 +15,7 @@ Generate ideas via named methods from creative practice. | | | |---|---| | Source | Optional — install with `hermes skills install official/creative/creative-ideation` | -| Path | `optional-skills/creative/creative-ideation` | +| Path | `optional-skills/creative\creative-ideation` | | Version | `2.1.0` | | Author | SHL0MS | | License | MIT | diff --git a/website/docs/user-guide/skills/optional/creative/creative-draw-your-font.md b/website/docs/user-guide/skills/optional/creative/creative-draw-your-font.md index 23a0596bc8..e5fcdda279 100644 --- a/website/docs/user-guide/skills/optional/creative/creative-draw-your-font.md +++ b/website/docs/user-guide/skills/optional/creative/creative-draw-your-font.md @@ -1,21 +1,21 @@ --- -title: "Draw Your Font — Turn a photo of handwriting into an installable font (TTF/WOFF)" +title: "Draw Your Font — Turn a handwriting photo into an installable TTF font" sidebar_label: "Draw Your Font" -description: "Turn a photo of handwriting into an installable font (TTF/WOFF)" +description: "Turn a handwriting photo into an installable TTF font" --- {/* 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. */} # Draw Your Font -Turn a photo of handwriting into an installable font (TTF/WOFF). +Turn a handwriting photo into an installable TTF font. ## Skill metadata | | | |---|---| | Source | Optional — install with `hermes skills install official/creative/draw-your-font` | -| Path | `optional-skills/creative/draw-your-font` | +| Path | `optional-skills/creative\draw-your-font` | | Version | `0.1.0` | | Author | Danilo Znamerovszkij (https://github.com/danilo-znamerovszkij/draw-your-font), ported by Hermes Agent | | License | MIT | diff --git a/website/docs/user-guide/skills/optional/creative/creative-excalidraw.md b/website/docs/user-guide/skills/optional/creative/creative-excalidraw.md new file mode 100644 index 0000000000..15da2dbebc --- /dev/null +++ b/website/docs/user-guide/skills/optional/creative/creative-excalidraw.md @@ -0,0 +1,212 @@ +--- +title: "Excalidraw — Hand-drawn Excalidraw JSON diagrams (arch, flow, seq)" +sidebar_label: "Excalidraw" +description: "Hand-drawn Excalidraw JSON diagrams (arch, flow, seq)" +--- + +{/* 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. */} + +# Excalidraw + +Hand-drawn Excalidraw JSON diagrams (arch, flow, seq). + +## Skill metadata + +| | | +|---|---| +| Source | Optional — install with `hermes skills install official/creative/excalidraw` | +| Path | `optional-skills/creative\excalidraw` | +| Version | `1.0.1` | +| Author | Hermes Agent | +| License | MIT | +| Platforms | linux, macos, windows | +| Tags | `Excalidraw`, `Diagrams`, `Flowcharts`, `Architecture`, `Visualization`, `JSON` | + +## 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. +::: + +# Excalidraw Diagram Skill + +Create diagrams by writing standard Excalidraw element JSON and saving as `.excalidraw` files. These files can be drag-and-dropped onto [excalidraw.com](https://excalidraw.com) for viewing and editing. No accounts, no API keys, no rendering libraries -- just JSON. + +## When to use + +Generate `.excalidraw` files for architecture diagrams, flowcharts, sequence diagrams, concept maps, and more. Files can be opened at excalidraw.com or uploaded for shareable links. + +## Workflow + +1. **Load this skill** (you already did) +2. **Write the elements JSON** -- an array of Excalidraw element objects +3. **Save the file** using `write_file` to create a `.excalidraw` file +4. **Optionally upload** for a shareable link using `scripts/upload.py` via `terminal` + +### Saving a Diagram + +Wrap your elements array in the standard `.excalidraw` envelope and save with `write_file`: + +```json +{ + "type": "excalidraw", + "version": 2, + "source": "hermes-agent", + "elements": [ ...your elements array here... ], + "appState": { + "viewBackgroundColor": "#ffffff" + } +} +``` + +Save to any path, e.g. `~/diagrams/my_diagram.excalidraw`. + +### Uploading for a Shareable Link + +Run the upload script (located in this skill's `scripts/` directory) via terminal: + +```bash +python skills/creative/excalidraw/scripts/upload.py ~/diagrams/my_diagram.excalidraw +``` + +This uploads to excalidraw.com (no account needed) and prints a shareable URL. Requires the `cryptography` pip package (`pip install cryptography`). + +--- + +## Element Format Reference + +### Required Fields (all elements) +`type`, `id` (unique string), `x`, `y`, `width`, `height` + +### Defaults (skip these -- they're applied automatically) +- `strokeColor`: `"#1e1e1e"` +- `backgroundColor`: `"transparent"` +- `fillStyle`: `"solid"` +- `strokeWidth`: `2` +- `roughness`: `1` (hand-drawn look) +- `opacity`: `100` + +Canvas background is white. + +### Element Types + +**Rectangle**: +```json +{ "type": "rectangle", "id": "r1", "x": 100, "y": 100, "width": 200, "height": 100 } +``` +- `roundness: { "type": 3 }` for rounded corners +- `backgroundColor: "#a5d8ff"`, `fillStyle: "solid"` for filled + +**Ellipse**: +```json +{ "type": "ellipse", "id": "e1", "x": 100, "y": 100, "width": 150, "height": 150 } +``` + +**Diamond**: +```json +{ "type": "diamond", "id": "d1", "x": 100, "y": 100, "width": 150, "height": 150 } +``` + +**Labeled shape (container binding)** -- create a text element bound to the shape: + +> **WARNING:** Do NOT use `"label": { "text": "..." }` on shapes. This is NOT a valid +> Excalidraw property and will be silently ignored, producing blank shapes. You MUST +> use the container binding approach below. + +The shape needs `boundElements` listing the text, and the text needs `containerId` pointing back: +```json +{ "type": "rectangle", "id": "r1", "x": 100, "y": 100, "width": 200, "height": 80, + "roundness": { "type": 3 }, "backgroundColor": "#a5d8ff", "fillStyle": "solid", + "boundElements": [{ "id": "t_r1", "type": "text" }] }, +{ "type": "text", "id": "t_r1", "x": 105, "y": 110, "width": 190, "height": 25, + "text": "Hello", "fontSize": 20, "fontFamily": 1, "strokeColor": "#1e1e1e", + "textAlign": "center", "verticalAlign": "middle", + "containerId": "r1", "originalText": "Hello", "autoResize": true } +``` +- Works on rectangle, ellipse, diamond +- Text is auto-centered by Excalidraw when `containerId` is set +- The text `x`/`y`/`width`/`height` are approximate -- Excalidraw recalculates them on load +- `originalText` should match `text` +- Always include `fontFamily: 1` (Virgil/hand-drawn font) + +**Labeled arrow** -- same container binding approach: +```json +{ "type": "arrow", "id": "a1", "x": 300, "y": 150, "width": 200, "height": 0, + "points": [[0,0],[200,0]], "endArrowhead": "arrow", + "boundElements": [{ "id": "t_a1", "type": "text" }] }, +{ "type": "text", "id": "t_a1", "x": 370, "y": 130, "width": 60, "height": 20, + "text": "connects", "fontSize": 16, "fontFamily": 1, "strokeColor": "#1e1e1e", + "textAlign": "center", "verticalAlign": "middle", + "containerId": "a1", "originalText": "connects", "autoResize": true } +``` + +**Standalone text** (titles and annotations only -- no container): +```json +{ "type": "text", "id": "t1", "x": 150, "y": 138, "text": "Hello", "fontSize": 20, + "fontFamily": 1, "strokeColor": "#1e1e1e", "originalText": "Hello", "autoResize": true } +``` +- `x` is the LEFT edge. To center at position `cx`: `x = cx - (text.length * fontSize * 0.5) / 2` +- Do NOT rely on `textAlign` or `width` for positioning + +**Arrow**: +```json +{ "type": "arrow", "id": "a1", "x": 300, "y": 150, "width": 200, "height": 0, + "points": [[0,0],[200,0]], "endArrowhead": "arrow" } +``` +- `points`: `[dx, dy]` offsets from element `x`, `y` +- `endArrowhead`: `null` | `"arrow"` | `"bar"` | `"dot"` | `"triangle"` +- `strokeStyle`: `"solid"` (default) | `"dashed"` | `"dotted"` + +### Arrow Bindings (connect arrows to shapes) + +```json +{ + "type": "arrow", "id": "a1", "x": 300, "y": 150, "width": 150, "height": 0, + "points": [[0,0],[150,0]], "endArrowhead": "arrow", + "startBinding": { "elementId": "r1", "fixedPoint": [1, 0.5] }, + "endBinding": { "elementId": "r2", "fixedPoint": [0, 0.5] } +} +``` + +`fixedPoint` coordinates: `top=[0.5,0]`, `bottom=[0.5,1]`, `left=[0,0.5]`, `right=[1,0.5]` + +### Drawing Order (z-order) +- Array order = z-order (first = back, last = front) +- Emit progressively: background zones → shape → its bound text → its arrows → next shape +- BAD: all rectangles, then all texts, then all arrows +- GOOD: bg_zone → shape1 → text_for_shape1 → arrow1 → arrow_label_text → shape2 → text_for_shape2 → ... +- Always place the bound text element immediately after its container shape + +### Sizing Guidelines + +**Font sizes:** +- Minimum `fontSize`: **16** for body text, labels, descriptions +- Minimum `fontSize`: **20** for titles and headings +- Minimum `fontSize`: **14** for secondary annotations only (sparingly) +- NEVER use `fontSize` below 14 + +**Element sizes:** +- Minimum shape size: 120x60 for labeled rectangles/ellipses +- Leave 20-30px gaps between elements minimum +- Prefer fewer, larger elements over many tiny ones + +### Color Palette + +See `references/colors.md` for full color tables. Quick reference: + +| Use | Fill Color | Hex | +|-----|-----------|-----| +| Primary / Input | Light Blue | `#a5d8ff` | +| Success / Output | Light Green | `#b2f2bb` | +| Warning / External | Light Orange | `#ffd8a8` | +| Processing / Special | Light Purple | `#d0bfff` | +| Error / Critical | Light Red | `#ffc9c9` | +| Notes / Decisions | Light Yellow | `#fff3bf` | +| Storage / Data | Light Teal | `#c3fae8` | + +### Tips +- Use the color palette consistently across the diagram +- **Text contrast is CRITICAL** -- never use light gray on white backgrounds. Minimum text color on white: `#757575` +- Do NOT use emoji in text -- they don't render in Excalidraw's font +- For dark mode diagrams, see `references/dark-mode.md` +- For larger examples, see `references/examples.md` diff --git a/website/docs/user-guide/skills/optional/creative/creative-heartmula.md b/website/docs/user-guide/skills/optional/creative/creative-heartmula.md index 052970f3bb..ed21822770 100644 --- a/website/docs/user-guide/skills/optional/creative/creative-heartmula.md +++ b/website/docs/user-guide/skills/optional/creative/creative-heartmula.md @@ -15,7 +15,7 @@ HeartMuLa: Suno-like song generation from lyrics + tags. | | | |---|---| | Source | Optional — install with `hermes skills install official/creative/heartmula` | -| Path | `optional-skills/creative/heartmula` | +| Path | `optional-skills/creative\heartmula` | | Version | `1.0.0` | | Author | Teknium (teknium1), Hermes Agent | | License | MIT | diff --git a/website/docs/user-guide/skills/optional/creative/creative-hyperframes.md b/website/docs/user-guide/skills/optional/creative/creative-hyperframes.md index 3f453acd8d..1a8afaa9e1 100644 --- a/website/docs/user-guide/skills/optional/creative/creative-hyperframes.md +++ b/website/docs/user-guide/skills/optional/creative/creative-hyperframes.md @@ -15,7 +15,7 @@ Render MP4/WebM videos from HTML compositions. | | | |---|---| | Source | Optional — install with `hermes skills install official/creative/hyperframes` | -| Path | `optional-skills/creative/hyperframes` | +| Path | `optional-skills/creative\hyperframes` | | Version | `1.0.0` | | Author | heygen-com | | License | Apache-2.0 | @@ -57,14 +57,16 @@ Do **not** use this skill for: npx hyperframes init my-video # scaffold a project cd my-video npx hyperframes lint # validate before preview/render -npx hyperframes preview # live-reload browser preview (port 3002) +npx hyperframes preview # live-reload preview (long-lived server, port 3002) npx hyperframes render --output final.mp4 # render to MP4 npx hyperframes doctor # diagnose environment issues ``` +`preview` is a **long-lived** Next.js server that holds Chrome render workers open. Always stop it when done (see [Cleanup](#cleanup)) — a forgotten preview keeps idle `chrome-headless-shell` workers alive that, on GPU-less hosts (WSL, containers, CI), spin a CPU core each indefinitely via software WebGL (swiftshader). + Render flags: `--quality draft|standard|high` · `--fps 24|30|60` · `--format mp4|webm` · `--docker` (reproducible) · `--strict`. -Full CLI reference: [references/cli.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative/hyperframes/references/cli.md). +Full CLI reference: [references/cli.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative\hyperframes/references/cli.md). ## Setup (one-time) @@ -78,7 +80,7 @@ The script: 3. Pre-caches `chrome-headless-shell` via Puppeteer — **required** for best-quality rendering via Chrome's `HeadlessExperimental.beginFrame` capture path. 4. Runs `npx hyperframes doctor` and reports the result. -See [references/troubleshooting.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative/hyperframes/references/troubleshooting.md) if setup fails. +See [references/troubleshooting.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative\hyperframes/references/troubleshooting.md) if setup fails. ## Procedure @@ -115,7 +117,7 @@ Write the static HTML+CSS for the **hero frame first** — no GSAP yet. The `.sc Only after the hero frame looks right, add `gsap.from()` entrances (animate **to** the CSS position) and `gsap.to()` exits (animate **from** it). -See [references/composition.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative/hyperframes/references/composition.md) for the full data-attribute schema and composition rules. +See [references/composition.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative\hyperframes/references/composition.md) for the full data-attribute schema and composition rules. ### 4. Animate with GSAP @@ -126,7 +128,7 @@ Every composition must: - Be deterministic — no `Math.random()`, `Date.now()`, or wall-clock logic. Use a seeded PRNG if you need pseudo-randomness. - Build synchronously — no `async`/`await`, `setTimeout`, or Promises around timeline construction. -See [references/gsap.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative/hyperframes/references/gsap.md) for the core GSAP API (tweens, eases, stagger, timelines). +See [references/gsap.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative\hyperframes/references/gsap.md) for the core GSAP API (tweens, eases, stagger, timelines). ### 5. Transitions between scenes @@ -162,11 +164,26 @@ npx hyperframes render --quality high --output final.mp4 # final delivery ### 8. Website-to-video (if the user gives a URL) -Use the 7-step capture-to-video workflow in [references/website-to-video.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative/hyperframes/references/website-to-video.md): capture → DESIGN.md → SCRIPT.md → storyboard → composition → render → deliver. +Use the 7-step capture-to-video workflow in [references/website-to-video.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative\hyperframes/references/website-to-video.md): capture → DESIGN.md → SCRIPT.md → storyboard → composition → render → deliver. + +## Cleanup + +`render` is one-shot (workers exit when it finishes). `preview` is **not** — it runs a background Next.js server that keeps Chrome workers resident until you stop it. Never leave one running: on GPU-less hosts each idle worker's swiftshader process pegs a CPU core, and a preview left open for days stacks up multiple. + +Stop a preview when the user is done reviewing (or before starting a new one): + +```bash +pkill -f "hyperframes.*preview" # the Studio server (frees port 3002) +pkill -f chrome-headless-shell # its render workers; only safe if nothing else uses them +``` + +If unsure whether other tools use `chrome-headless-shell`, check first: `pgrep -af chrome-headless-shell`. Recover a wedged host (many idle workers spinning CPU) the same way — see [references/troubleshooting.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative\hyperframes/references/troubleshooting.md#runaway-cpu-from-leftover-preview-workers). ## Pitfalls -- **`HeadlessExperimental.beginFrame' wasn't found`** — Chromium 147+ removed this protocol. Ensure you're on `hyperframes@>=0.4.2` (auto-detects and falls back to screenshot mode). Escape hatch: `export PRODUCER_FORCE_SCREENSHOT=true`. See [hyperframes#294](https://github.com/heygen-com/hyperframes/issues/294) and [references/troubleshooting.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative/hyperframes/references/troubleshooting.md). +- **Leaving `preview` running** — it's a long-lived server holding Chrome workers; on WSL/containers/CI those idle workers spin a CPU core each (software WebGL). Stop it when done — see [Cleanup](#cleanup). + +- **`HeadlessExperimental.beginFrame' wasn't found`** — Chromium 147+ removed this protocol. Ensure you're on `hyperframes@>=0.4.2` (auto-detects and falls back to screenshot mode). Escape hatch: `export PRODUCER_FORCE_SCREENSHOT=true`. See [hyperframes#294](https://github.com/heygen-com/hyperframes/issues/294) and [references/troubleshooting.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative\hyperframes/references/troubleshooting.md). - **System Chrome (not `chrome-headless-shell`)** — renders hang for 120s then timeout. Run `npx puppeteer browsers install chrome-headless-shell` (setup.sh does this). `hyperframes doctor` reports which binary will be used. - **`repeat: -1` anywhere** — breaks the capture engine. Always compute a finite repeat count. - **`gsap.set()` on clip elements that enter later** — the element doesn't exist at page load. Use `tl.set(selector, vars, timePosition)` inside the timeline instead, at or after the clip's `data-start`. @@ -197,9 +214,9 @@ If `hyperframes render` fails, run `npx hyperframes doctor` and attach its outpu ## References -- [composition.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative/hyperframes/references/composition.md) — data attributes, timeline contract, non-negotiable rules, typography/asset rules -- [cli.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative/hyperframes/references/cli.md) — every CLI command (init, capture, lint, validate, inspect, preview, render, transcribe, tts, doctor, browser, info, upgrade, benchmark) -- [gsap.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative/hyperframes/references/gsap.md) — GSAP core API for HyperFrames (tweens, eases, stagger, timelines, matchMedia) -- [features.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative/hyperframes/references/features.md) — captions, TTS, audio-reactive, marker highlighting, transitions (load on demand) -- [website-to-video.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative/hyperframes/references/website-to-video.md) — 7-step capture-to-video workflow -- [troubleshooting.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative/hyperframes/references/troubleshooting.md) — OpenClaw fix, env vars, common render errors +- [composition.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative\hyperframes/references/composition.md) — data attributes, timeline contract, non-negotiable rules, typography/asset rules +- [cli.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative\hyperframes/references/cli.md) — every CLI command (init, capture, lint, validate, inspect, preview, render, transcribe, tts, doctor, browser, info, upgrade, benchmark) +- [gsap.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative\hyperframes/references/gsap.md) — GSAP core API for HyperFrames (tweens, eases, stagger, timelines, matchMedia) +- [features.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative\hyperframes/references/features.md) — captions, TTS, audio-reactive, marker highlighting, transitions (load on demand) +- [website-to-video.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative\hyperframes/references/website-to-video.md) — 7-step capture-to-video workflow +- [troubleshooting.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative\hyperframes/references/troubleshooting.md) — OpenClaw fix, env vars, common render errors diff --git a/website/docs/user-guide/skills/optional/creative/creative-impeccable.md b/website/docs/user-guide/skills/optional/creative/creative-impeccable.md index 55e475d1cd..a94647e8f7 100644 --- a/website/docs/user-guide/skills/optional/creative/creative-impeccable.md +++ b/website/docs/user-guide/skills/optional/creative/creative-impeccable.md @@ -15,7 +15,7 @@ Frontend design guidance, upstream-maintained (impeccable). | | | |---|---| | Source | Optional — install with `hermes skills install official/creative/impeccable` | -| Path | `optional-skills/creative/impeccable` | +| Path | `optional-skills/creative\impeccable` | | Version | `4.1.2` | | Author | Paul Bakaus (pbakaus) | | License | Apache-2.0 | diff --git a/website/docs/user-guide/skills/optional/creative/creative-kanban-video-orchestrator.md b/website/docs/user-guide/skills/optional/creative/creative-kanban-video-orchestrator.md index 6d3185eb80..ecb36c41a9 100644 --- a/website/docs/user-guide/skills/optional/creative/creative-kanban-video-orchestrator.md +++ b/website/docs/user-guide/skills/optional/creative/creative-kanban-video-orchestrator.md @@ -15,13 +15,13 @@ Plan and run multi-agent video production pipelines. | | | |---|---| | Source | Optional — install with `hermes skills install official/creative/kanban-video-orchestrator` | -| Path | `optional-skills/creative/kanban-video-orchestrator` | +| Path | `optional-skills/creative\kanban-video-orchestrator` | | Version | `1.0.0` | | Author | ['SHL0MS', 'alt-glitch'] | | License | MIT | | Platforms | linux, macos, windows | | Tags | `video`, `kanban`, `multi-agent`, `orchestration`, `production-pipeline` | -| Related skills | [`ascii-video`](/docs/user-guide/skills/bundled/creative/creative-ascii-video), [`manim-video`](/docs/user-guide/skills/bundled/creative/creative-manim-video), [`p5js`](/docs/user-guide/skills/bundled/creative/creative-p5js), [`comfyui`](/docs/user-guide/skills/bundled/creative/creative-comfyui), [`touchdesigner-mcp`](/docs/user-guide/skills/bundled/creative/creative-touchdesigner-mcp), [`pixel-art`](/docs/user-guide/skills/optional/creative/creative-pixel-art), [`ascii-art`](/docs/user-guide/skills/bundled/creative/creative-ascii-art), [`songwriting-and-ai-music`](/docs/user-guide/skills/bundled/creative/creative-songwriting-and-ai-music), [`heartmula`](/docs/user-guide/skills/optional/creative/creative-heartmula), [`songsee`](/docs/user-guide/skills/bundled/media/media-songsee), [`youtube-content`](/docs/user-guide/skills/bundled/media/media-youtube-content), [`claude-design`](/docs/user-guide/skills/bundled/creative/creative-claude-design), [`excalidraw`](/docs/user-guide/skills/bundled/creative/creative-excalidraw), [`architecture-diagram`](/docs/user-guide/skills/bundled/creative/creative-architecture-diagram), [`concept-diagrams`](/docs/user-guide/skills/optional/creative/creative-concept-diagrams), [`baoyu-comic`](/docs/user-guide/skills/optional/creative/creative-baoyu-comic), [`baoyu-infographic`](/docs/user-guide/skills/bundled/creative/creative-baoyu-infographic), [`humanizer`](/docs/user-guide/skills/bundled/creative/creative-humanizer), [`gif-search`](/docs/user-guide/skills/bundled/media/media-gif-search), [`meme-generation`](/docs/user-guide/skills/optional/creative/creative-meme-generation) | +| Related skills | [`ascii-video`](/docs/user-guide/skills/bundled/creative/creative-ascii-video), [`manim-video`](/docs/user-guide/skills/bundled/creative/creative-manim-video), [`p5js`](/docs/user-guide/skills/bundled/creative/creative-p5js), [`comfyui`](/docs/user-guide/skills/optional/creative/creative-comfyui), [`touchdesigner-mcp`](/docs/user-guide/skills/optional/creative/creative-touchdesigner-mcp), [`pixel-art`](/docs/user-guide/skills/optional/creative/creative-pixel-art), [`ascii-art`](/docs/user-guide/skills/optional/creative/creative-ascii-art), [`songwriting-and-ai-music`](/docs/user-guide/skills/bundled/creative/creative-songwriting-and-ai-music), [`heartmula`](/docs/user-guide/skills/optional/creative/creative-heartmula), [`songsee`](/docs/user-guide/skills/bundled/media/media-songsee), [`youtube-content`](/docs/user-guide/skills/bundled/media/media-youtube-content), [`claude-design`](/docs/user-guide/skills/bundled/creative/creative-claude-design), [`excalidraw`](/docs/user-guide/skills/optional/creative/creative-excalidraw), [`architecture-diagram`](/docs/user-guide/skills/bundled/creative/creative-architecture-diagram), [`concept-diagrams`](/docs/user-guide/skills/optional/creative/creative-concept-diagrams), [`baoyu-comic`](/docs/user-guide/skills/optional/creative/creative-baoyu-comic), [`baoyu-infographic`](/docs/user-guide/skills/bundled/creative/creative-baoyu-infographic), [`humanizer`](/docs/user-guide/skills/bundled/creative/creative-humanizer), [`gif-search`](/docs/user-guide/skills/bundled/media/media-gif-search), [`meme-generation`](/docs/user-guide/skills/optional/creative/creative-meme-generation) | ## Reference: full SKILL.md @@ -76,7 +76,7 @@ time, listen, then proceed. Make reasonable assumptions whenever the user implies an answer. For complete intake patterns and per-style question banks, see -**[references/intake.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative/kanban-video-orchestrator/references/intake.md)**. +**[references/intake.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative\kanban-video-orchestrator/references/intake.md)**. ### Step 2 — Brief @@ -100,10 +100,10 @@ clone.** Most videos need 4-7 profiles. The director is always present; the rest are picked by what the brief actually requires. For the role library and per-style team compositions, see -**[references/role-archetypes.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative/kanban-video-orchestrator/references/role-archetypes.md)**. +**[references/role-archetypes.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative\kanban-video-orchestrator/references/role-archetypes.md)**. For mapping role → which Hermes skills + toolsets it loads, see -**[references/tool-matrix.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative/kanban-video-orchestrator/references/tool-matrix.md)**. +**[references/tool-matrix.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative\kanban-video-orchestrator/references/tool-matrix.md)**. ### Step 4 — Setup @@ -118,7 +118,7 @@ Generate a setup script (`setup.sh`) and run it. The script: 7. Fires the initial `hermes kanban create` task assigned to the director Use `scripts/bootstrap_pipeline.py` to generate setup.sh from a brief + -team-design JSON. See **[references/kanban-setup.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative/kanban-video-orchestrator/references/kanban-setup.md)** +team-design JSON. See **[references/kanban-setup.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative\kanban-video-orchestrator/references/kanban-setup.md)** for the setup script structure, profile config patterns, and the critical "shared workspace" rule. @@ -149,14 +149,14 @@ heartbeats. When a worker's output fails review, the standard interventions are: 3. Adjust the brief's scope and let the director re-decompose For diagnostic patterns, intervention recipes, and the "task is stuck" -playbook, see **[references/monitoring.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative/kanban-video-orchestrator/references/monitoring.md)**. +playbook, see **[references/monitoring.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative\kanban-video-orchestrator/references/monitoring.md)**. ## Reference: worked examples Six concrete pipelines covering very different video styles — narrative film, product/marketing, music video, math/algorithm explainer, ASCII video, real-time installation — showing how the same workflow yields very different teams and -task graphs. See **[references/examples.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative/kanban-video-orchestrator/references/examples.md)**. +task graphs. See **[references/examples.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/creative\kanban-video-orchestrator/references/examples.md)**. ## Critical rules diff --git a/website/docs/user-guide/skills/optional/creative/creative-meme-generation.md b/website/docs/user-guide/skills/optional/creative/creative-meme-generation.md index 605fe7ddc0..f7b61f10f9 100644 --- a/website/docs/user-guide/skills/optional/creative/creative-meme-generation.md +++ b/website/docs/user-guide/skills/optional/creative/creative-meme-generation.md @@ -15,13 +15,13 @@ Create meme PNGs from templates with Pillow text overlay. | | | |---|---| | Source | Optional — install with `hermes skills install official/creative/meme-generation` | -| Path | `optional-skills/creative/meme-generation` | +| Path | `optional-skills/creative\meme-generation` | | Version | `2.0.0` | | Author | adanaleycio | | License | MIT | | Platforms | linux, macos, windows | | Tags | `creative`, `memes`, `humor`, `images` | -| Related skills | [`ascii-art`](/docs/user-guide/skills/bundled/creative/creative-ascii-art) | +| Related skills | [`ascii-art`](/docs/user-guide/skills/optional/creative/creative-ascii-art) | ## Reference: full SKILL.md diff --git a/website/docs/user-guide/skills/optional/creative/creative-pixel-art.md b/website/docs/user-guide/skills/optional/creative/creative-pixel-art.md index c2f3d20b24..065496394c 100644 --- a/website/docs/user-guide/skills/optional/creative/creative-pixel-art.md +++ b/website/docs/user-guide/skills/optional/creative/creative-pixel-art.md @@ -15,7 +15,7 @@ Pixel art w/ era palettes (NES, Game Boy, PICO-8). | | | |---|---| | Source | Optional — install with `hermes skills install official/creative/pixel-art` | -| Path | `optional-skills/creative/pixel-art` | +| Path | `optional-skills/creative\pixel-art` | | Version | `2.0.0` | | Author | dodo-reach | | License | MIT | @@ -151,7 +151,8 @@ pixel_art("in.png", "out.png", preset="snes", palette="PICO_8", block=6) ```python import sys -sys.path.insert(0, "/home/teknium/.hermes/skills/creative/pixel-art/scripts") +import os +sys.path.insert(0, os.path.expanduser("~/.hermes/skills/creative/pixel-art/scripts")) from pixel_art import pixel_art from pixel_art_video import pixel_art_video @@ -173,7 +174,7 @@ pixel_art_video( ### CLI ```bash -cd /home/teknium/.hermes/skills/creative/pixel-art/scripts +cd ~/.hermes/skills/creative/pixel-art/scripts python pixel_art.py in.jpg out.png --preset gameboy python pixel_art.py in.jpg out.png --preset snes --palette PICO_8 --block 6 diff --git a/website/docs/user-guide/skills/optional/creative/creative-pretext.md b/website/docs/user-guide/skills/optional/creative/creative-pretext.md new file mode 100644 index 0000000000..7688aadcbc --- /dev/null +++ b/website/docs/user-guide/skills/optional/creative/creative-pretext.md @@ -0,0 +1,238 @@ +--- +title: "Pretext — Build creative browser demos with DOM-free text layout" +sidebar_label: "Pretext" +description: "Build creative browser demos with DOM-free text layout" +--- + +{/* 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. */} + +# Pretext + +Build creative browser demos with DOM-free text layout. + +## Skill metadata + +| | | +|---|---| +| Source | Optional — install with `hermes skills install official/creative/pretext` | +| Path | `optional-skills/creative\pretext` | +| Version | `1.0.0` | +| Author | Hermes Agent | +| License | MIT | +| Platforms | linux, macos, windows | +| Tags | `creative-coding`, `typography`, `pretext`, `ascii-art`, `canvas`, `generative`, `text-layout`, `kinetic-typography` | +| Related skills | [`p5js`](/docs/user-guide/skills/bundled/creative/creative-p5js), [`claude-design`](/docs/user-guide/skills/bundled/creative/creative-claude-design), [`excalidraw`](/docs/user-guide/skills/optional/creative/creative-excalidraw), [`architecture-diagram`](/docs/user-guide/skills/bundled/creative/creative-architecture-diagram) | + +## 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. +::: + +# Pretext Creative Demos + +## Overview + +[`@chenglou/pretext`](https://github.com/chenglou/pretext) is a 15KB zero-dependency TypeScript library by Cheng Lou (React core, ReasonML, Midjourney) for **DOM-free multiline text measurement and layout**. It does one thing: given `(text, font, width)`, return the line breaks, per-line widths, per-grapheme positions, and total height — all via canvas measurement, no reflow. + +That sounds like plumbing. It is not. Because it is fast and geometric, it is a **creative primitive**: you can reflow paragraphs around a moving sprite at 60fps, build games whose level geometry is made of real words, drive ASCII logos through prose, shatter text into particles with exact per-grapheme starting positions, or pack shrink-wrapped multiline UI without any `getBoundingClientRect` thrash. + +This skill exists so Hermes can make **cool demos** with it — the kind people post to X. See `pretext.cool` and `chenglou.me/pretext` for the community demo corpus. + +## When to Use + +Use when the user asks for: +- A "pretext demo" / "cool pretext thing" / "text-as-X" +- Text flowing around a moving shape (hero sections, editorial layouts, animated long-form pages) +- ASCII-art effects using **real words or prose**, not monospace rasters +- Games where the playfield / obstacles / bricks are made of text (Tetris-from-letters, Breakout-of-prose) +- Kinetic typography with per-glyph physics (shatter, scatter, flock, flow) +- Typographic generative art, especially with non-Latin scripts or mixed scripts +- Multiline "shrink-wrap" UI (smallest container width that still fits the text) +- Anything that would require knowing line breaks *before* rendering + +Don't use for: +- Static SVG/HTML pages where CSS already solves layout — just use CSS +- Rich text editors, general inline formatting engines (pretext is intentionally narrow) +- Image → text (use `ascii-art` / `ascii-video` skills) +- Pure canvas generative art with no text role — use `p5js` + +## Creative Standard + +This is visual art rendered in a browser. Pretext returns numbers; **you** draw the thing. + +- **Don't ship a "hello world" demo.** The `hello-orb-flow.html` template is the *starting* point. Every delivered demo must add intentional color, motion, composition, and one visual detail the user didn't ask for but will appreciate. +- **Dark backgrounds, warm cores, considered palette.** Classic amber-on-black (CRT / terminal) works, but so do cold-white-on-charcoal (editorial) and desaturated pastels (risograph). Pick one and commit. +- **Proportional fonts are the point.** Pretext's whole vibe is "not monospaced" — lean into it. Use Iowan Old Style, Inter, JetBrains Mono, Helvetica Neue, or a variable font. Never default sans. +- **Real source/text, not lorem ipsum.** The corpus should mean something. Short manifestos, poetry, real source code, a found text, the library's own README — never `lorem ipsum`. +- **First-paint excellence.** No loading states, no blank frames. The demo must look shippable the instant it opens. + +## Stack + +Single self-contained HTML file per demo. No build step. + +| Layer | Tool | Purpose | +|-------|------|---------| +| Core | `@chenglou/pretext` via `esm.sh` CDN | Text measurement + line layout | +| Render | HTML5 Canvas 2D | Glyph rendering, per-frame composition | +| Segmentation | `Intl.Segmenter` (built-in) | Grapheme splitting for emoji / CJK / combining marks | +| Interaction | Raw DOM events | Mouse / touch / wheel — no framework | + +```html + +``` + +Pin the version. `@0.0.6` at time of writing — check [npm](https://www.npmjs.com/package/@chenglou/pretext) for the latest if demo behavior is off. + +## The Two Use Cases + +Almost everything reduces to one of these two shapes. Learn both. + +### Use-case 1 — measure, then render with CSS/DOM + +```js +const prepared = prepare(text, "16px Inter"); +const { height, lineCount } = layout(prepared, 320, 20); +``` + +You still let the browser draw the text. Pretext just tells you how tall the box will be at a given width, **without** a DOM read. Use for: +- Virtualized lists where rows contain wrapping text +- Masonry with precise card heights +- "Does this label fit?" dev-time checks +- Preventing layout shift when remote text loads + +**Keep `font` and `letterSpacing` exactly in sync with your CSS.** The canvas `ctx.font` format (e.g. `"16px Inter"`, `"500 17px 'JetBrains Mono'"`) must match the rendered CSS, or measurements drift. + +### Use-case 2 — measure *and* render yourself + +```js +const prepared = prepareWithSegments(text, FONT); +const { lines } = layoutWithLines(prepared, 320, 26); +for (let i = 0; i < lines.length; i++) { + ctx.fillText(lines[i].text, 0, i * 26); +} +``` + +This is where the creative work lives. You own the drawing, so you can: +- Render to canvas, SVG, WebGL, or any coordinate system +- Substitute per-glyph transforms (rotation, jitter, scale, opacity) +- Use line metadata (width, grapheme positions) as geometry + +For **variable-width-per-line** flow (text around a shape, text in a donut band, text in a non-rectangular column): + +```js +let cursor = { segmentIndex: 0, graphemeIndex: 0 }; +let y = 0; +while (true) { + const lineWidth = widthAtY(y); // your function: how wide is the corridor at this y? + const range = layoutNextLineRange(prepared, cursor, lineWidth); + if (!range) break; + const line = materializeLineRange(prepared, range); + ctx.fillText(line.text, leftEdgeAtY(y), y); + cursor = range.end; + y += lineHeight; +} +``` + +This is the most important pattern in the whole library. It's what unlocks "text flowing around a dragged sprite" — the demo that went viral on X. + +### Helpers worth knowing + +- `measureLineStats(prepared, maxWidth)` → `{ lineCount, maxLineWidth }` — the widest line, i.e. multiline shrink-wrap width. +- `walkLineRanges(prepared, maxWidth, callback)` — iterate lines without allocating strings. Use for stats/physics over graphemes when you don't need the characters. +- `@chenglou/pretext/rich-inline` — the same system but for paragraphs mixing fonts / chips / mentions. Import from the subpath. + +## Demo Recipe Patterns + +The community corpus (see `references/patterns.md`) clusters into a handful of strong patterns. Pick one and riff — don't invent a new category unless asked. + +| Pattern | Key API | Example idea | +|---|---|---| +| **Reflow around obstacle** | `layoutNextLineRange` + per-row width function | Editorial paragraph that parts around a dragged cursor sprite | +| **Text-as-geometry game** | `layoutWithLines` + per-line collision rects | Breakout where each brick is a measured word | +| **Shatter / particles** | `walkLineRanges` → per-grapheme (x,y) → physics | Sentence that explodes into letters on click | +| **ASCII obstacle typography** | `layoutNextLineRange` + measured per-row obstacle spans | Bitmap ASCII logo, shape morphs, and draggable wire objects that make text open around their actual geometry | +| **Editorial multi-column** | `layoutNextLineRange` per column + shared cursor | Animated magazine spread with pull quotes | +| **Kinetic type** | `layoutWithLines` + per-line transform over time | Star Wars crawl, wave, bounce, glitch | +| **Multiline shrink-wrap** | `measureLineStats` | Quote card that auto-sizes to its tightest container | + +See `templates/donut-orbit.html` and `templates/hello-orb-flow.html` for working single-file starters. + +## Workflow + +1. **Pick a pattern** from the table above based on the user's brief. +2. **Start from a template**: + - `templates/hello-orb-flow.html` — text reflowing around a moving orb (reflow-around-obstacle pattern) + - `templates/donut-orbit.html` — advanced example: measured ASCII logo obstacles, draggable wire sphere/cube, morphing shape fields, selectable DOM text, and dev-only controls + - `write_file` to a new `.html` in `/tmp/` or the user's workspace. +3. **Swap the corpus** for something intentional to the brief. Real prose, 10-100 sentences, no lorem. +4. **Tune the aesthetic** — font, palette, composition, interaction. This is the work; don't skip it. +5. **Verify locally**: + ```sh + cd && python -m http.server 8765 + # then open http://localhost:8765/.html + ``` +6. **Check the console** — pretext will throw if `prepareWithSegments` is called with a bad font string; `Intl.Segmenter` is available in every modern browser. +7. **Show the user the file path**, not just the code — they want to open it. + +## Performance Notes + +- `prepare()` / `prepareWithSegments()` is the expensive call. Do it **once** per text+font pair. Cache the handle. +- On resize, only rerun `layout()` / `layoutWithLines()` — never re-prepare. +- For per-frame animations where text doesn't change but geometry does, `layoutNextLineRange` in a tight loop is cheap enough to do every frame at 60fps for normal-length paragraphs. +- When rendering ASCII masks per frame, keep a cell buffer (`Uint8Array`/typed arrays), derive measured per-row obstacle spans from the cells or projected geometry, merge spans, then feed those spans into `layoutNextLineRange` before drawing text. +- Keep visual animation and layout animation coupled. If a sphere morphs into a cube, tween both the rendered cell buffer and the obstacle spans with the same value; otherwise the demo looks painted-on instead of physically reflowed. +- For fades, prefer layer opacity over changing glyph intensity or obstacle scale. Put transient ASCII sprites on their own canvas and fade the canvas with CSS/GSAP opacity so geometry does not appear to shrink. +- Canvas `ctx.font` setting is surprisingly slow; set it **once** per frame if font doesn't vary, not per `fillText` call. + +## Common Pitfalls + +1. **Drifting CSS/canvas font strings.** `ctx.font = "16px Inter"` measured, but CSS says `font-family: Inter, sans-serif; font-size: 16px`. Fine *if* Inter loads. If Inter 404s, CSS falls back to sans-serif and measurements drift by 5-20%. Always `preload` the font or use a web-safe family. + +2. **Re-preparing inside the animation loop.** Only `layout*` is cheap. Re-calling `prepare` every frame will tank perf. Keep the prepared handle in module scope. + +3. **Forgetting `Intl.Segmenter` for grapheme splits.** Emoji, combining marks, CJK — `"é".split("")` gives you two chars. Use `new Intl.Segmenter(undefined, { granularity: "grapheme" })` when sampling individual visible glyphs. + +4. **`break: 'never'` chips without `extraWidth`.** In `rich-inline`, if you use `break: 'never'` for an atomic chip/mention, you must also supply `extraWidth` for the pill padding — otherwise chip chrome overflows the container. + +5. **Using `@chenglou/pretext` from `unpkg` with TypeScript-only entry.** Use `esm.sh` — it compiles the TS exports to browser-ready ESM automatically. `unpkg` will 404 or serve raw TS. + +6. **Monospace fallbacks silently erasing the whole point.** Users seeing monospace-looking output often have a CSS `font-family` that fell through to `monospace`. Verify the actual rendered font via DevTools. + +7. **Skipping rows vs adjusting width** when flowing around a shape. If the corridor on this row is too narrow to fit a line, *skip the row* (`y += lineHeight; continue;`) rather than passing a tiny maxWidth to `layoutNextLineRange` — pretext will return one-grapheme lines that look broken. + +8. **Shipping a cold demo.** The default first-paint looks tutorial-grade. Add: vignette, subtle scanline, idle auto-motion, one carefully chosen interactive response (drag, hover, scroll, click). Without these, "cool pretext demo" lands as "intern repro of the README." + +## Verification Checklist + +- [ ] Demo is a single self-contained `.html` file — opens by double-click or `python -m http.server` +- [ ] `@chenglou/pretext` imported via `esm.sh` with pinned version +- [ ] Corpus is real prose, not lorem ipsum, and matches the demo's concept +- [ ] Font string passed to `prepare` matches the CSS font exactly +- [ ] `prepare()` / `prepareWithSegments()` called once, not per frame +- [ ] Dark background + considered palette — not the default white canvas +- [ ] At least one interactive response (drag / hover / scroll / click) or idle auto-motion +- [ ] Tested locally with `python -m http.server` and confirmed no console errors +- [ ] 60fps on a mid-tier laptop (or graceful degradation documented) +- [ ] One "extra mile" detail the user didn't ask for + +## Reference: Community Demos + +Clone these for inspiration / patterns (all MIT-ish, linked from [pretext.cool](https://www.pretext.cool/)): + +- **Pretext Breaker** — breakout with word-bricks — `github.com/rinesh/pretext-breaker` +- **Tetris × Pretext** — `github.com/shinichimochizuki/tetris-pretext` +- **Dragon animation** — `github.com/qtakmalay/PreTextExperiments` +- **Somnai editorial engine** — `github.com/somnai-dreams/pretext-demos` +- **Bad Apple!! ASCII** — `github.com/frmlinn/bad-apple-pretext` +- **Drag-sprite reflow** — `github.com/dokobot/pretext-demo` +- **Alarmy editorial clock** — `github.com/SmisLee/alarmy-pretext-demo` + +Official playground: [chenglou.me/pretext](https://chenglou.me/pretext/) — accordion, bubbles, dynamic-layout, editorial-engine, justification-comparison, masonry, markdown-chat, rich-note. diff --git a/website/docs/user-guide/skills/optional/creative/creative-simple-english.md b/website/docs/user-guide/skills/optional/creative/creative-simple-english.md index 9c35b2de88..a00e0623c8 100644 --- a/website/docs/user-guide/skills/optional/creative/creative-simple-english.md +++ b/website/docs/user-guide/skills/optional/creative/creative-simple-english.md @@ -1,21 +1,21 @@ --- -title: "Simple English — Rewrite technical text to ASD-STE100 Simplified Technical English" +title: "Simple English — Rewrite text to ASD-STE100 Simplified Technical English" sidebar_label: "Simple English" -description: "Rewrite technical text to ASD-STE100 Simplified Technical English" +description: "Rewrite text to ASD-STE100 Simplified Technical English" --- {/* 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. */} # Simple English -Rewrite technical text to ASD-STE100 Simplified Technical English. +Rewrite text to ASD-STE100 Simplified Technical English. ## Skill metadata | | | |---|---| | Source | Optional — install with `hermes skills install official/creative/simple-english` | -| Path | `optional-skills/creative/simple-english` | +| Path | `optional-skills/creative\simple-english` | | Version | `1.2.0` | | Author | AminBlg (https://github.com/AminBlg/SimpleEnglish), ported by Hermes Agent | | License | MIT | @@ -128,7 +128,7 @@ Break long noun chains with prepositions (of, on, in, for): | 3.6 | Active voice. In descriptive text, passive is legal only when the agent is unknown. | | 3.7 | Describe an action with a verb, not a noun ("compress the file", not "perform compression of the file"). | -**Approved modals: can, will, must. Banned: should, would, may, might, could.** +**Approved modals: can, will, must. Banned: should, would, may, might, could (Rule 3.2).** The standard rejects "could" even for possibility: write "an explosion can occur", never "could occur". For "should": a requirement becomes "must"; a suggestion is stated as fact or deleted. This matters double for agent instructions — models read "should" as optional. **Before:** The migration has completed and the table is being rebuilt. @@ -255,7 +255,7 @@ This table is ours, not the ASD dictionary. It maps the words AI-generated docs | leverage, utilize | use | | in order to | to | | prior to | before | -| ensure | make sure that | +| ensure | make sure that (strict mode; in pragmatic mode, ensure is an allowed pick if it is your one chosen check-verb) | | it is worth noting that | (delete) | | it's important to, crucially | (delete — state the fact) | | simply, just, easily, seamlessly, effortlessly | (delete) | diff --git a/website/docs/user-guide/skills/optional/creative/creative-sketch.md b/website/docs/user-guide/skills/optional/creative/creative-sketch.md new file mode 100644 index 0000000000..88f2fcfacd --- /dev/null +++ b/website/docs/user-guide/skills/optional/creative/creative-sketch.md @@ -0,0 +1,240 @@ +--- +title: "Sketch — Throwaway HTML mockups: 2-3 design variants to compare" +sidebar_label: "Sketch" +description: "Throwaway HTML mockups: 2-3 design variants to compare" +--- + +{/* 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. */} + +# Sketch + +Throwaway HTML mockups: 2-3 design variants to compare. + +## Skill metadata + +| | | +|---|---| +| Source | Optional — install with `hermes skills install official/creative/sketch` | +| Path | `optional-skills/creative\sketch` | +| Version | `1.0.1` | +| Author | Hermes Agent (adapted from gsd-build/get-shit-done) | +| License | MIT | +| Platforms | linux, macos, windows | +| Tags | `sketch`, `mockup`, `design`, `ui`, `prototype`, `html`, `variants`, `exploration`, `wireframe`, `comparison` | +| Related skills | [`spike`](/docs/user-guide/skills/bundled/software-development/software-development-spike), [`claude-design`](/docs/user-guide/skills/bundled/creative/creative-claude-design), [`popular-web-designs`](/docs/user-guide/skills/bundled/creative/creative-popular-web-designs), [`excalidraw`](/docs/user-guide/skills/optional/creative/creative-excalidraw) | + +## 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. +::: + +# Sketch + +Use this skill when the user wants to **see a design direction before committing** to one — exploring a UI/UX idea as disposable HTML mockups. The point is to generate 2-3 interactive variants so the user can compare visual directions side-by-side, not to produce shippable code. + +Load this when the user says things like "sketch this screen", "show me what X could look like", "compare layout A vs B", "give me 2-3 takes on this UI", "let me see some variants", "mockup this before I build". + +## When NOT to use this + +- User wants a production component — use `claude-design` or build it properly +- User wants a polished one-off HTML artifact (landing page, deck) — `claude-design` +- User wants a diagram — `excalidraw`, `architecture-diagram` +- The design is already locked — just build it + +## If the user has the full GSD system installed + +If `gsd-sketch` shows up as a sibling skill (installed via `npx get-shit-done-cc --hermes`), you can use **`gsd-sketch`** for the fuller workflow: persistent `.planning/sketches/` with MANIFEST, frontier mode analysis, consistency audits across past sketches, and integration with the rest of GSD. This skill is the lightweight standalone version — one-off sketching without the state machinery. + +> **Note:** The upstream GSD project ([gsd-build/get-shit-done](https://github.com/gsd-build/get-shit-done)) is **archived / no longer maintained** on GitHub. The npm package (`get-shit-done-cc`) still installs, but treat it as an archived community project — this standalone `sketch` skill is the maintained path and needs nothing extra. + +## Core method + +``` +intake → variants → head-to-head → pick winner (or iterate) +``` + +### 1. Intake (skip if the user already gave you enough) + +Before generating variants, get three things — one question at a time, not all at once: + +1. **Feel.** "What should this feel like? Adjectives, emotions, a vibe." — *"calm, editorial, like Linear"* tells you more than *"minimal"*. +2. **References.** "What apps, sites, or products capture the feel you're imagining?" — actual references beat abstract descriptions. +3. **Core action.** "What's the single most important thing a user does on this screen?" — the variants should all serve this well; if they don't, they're just decoration. + +Reflect each answer briefly before the next question. If the user already gave you all three upfront, skip straight to variants. + +### 2. Variants (2-3, never 1, rarely 4+) + +Produce **2-3 variants** in one go. Each variant is a complete, standalone HTML file. Don't describe variants — build them. The point is comparison. + +Each variant should take a **different design stance**, not different pixel values. Three good variant axes: + +- **Density:** compact / airy / ultra-dense (pick two contrasting poles) +- **Emphasis:** content-first / action-first / tool-first +- **Aesthetic:** editorial / utilitarian / playful +- **Layout:** single-column / sidebar / split-pane +- **Grounding:** card-based / bare-content / document-style + +Pick one axis and pull apart from it. Two variants that differ only in accent color are wasted effort — the user can't distinguish them. + +**Variant naming:** describe the stance, not the number. + + +``` +sketches/ +├── 001-calm-editorial/ +│ ├── index.html +│ └── README.md +├── 001-utilitarian-dense/ +│ ├── index.html +│ └── README.md +└── 001-playful-split/ + ├── index.html + └── README.md +``` + + +### 3. Make them real HTML + +Each variant is a **single self-contained HTML file**: + +- Inline ` +``` + +### 4. Variant README + +Each variant's `README.md` answers: + +```markdown +## Variant: {stance name} + +### Design stance +One sentence on the principle driving this variant. + +### Key choices +- Layout: ... +- Typography: ... +- Color: ... +- Interaction: ... + +### Trade-offs +- Strong at: ... +- Weak at: ... + +### Best for +- The kind of user or use case this variant actually serves +``` + +### 5. Head-to-head + +After all variants are built, present them as a comparison. Don't just list — **opinionate**: + +```markdown +## Three takes on the home screen + +| Dimension | Calm editorial | Utilitarian dense | Playful split | +|-----------|----------------|-------------------|---------------| +| Density | Low | High | Medium | +| Primary action visibility | Low | High | Medium | +| Scan-ability | High | Medium | Low | +| Feel | Calm, trusted | Sharp, tool-like | Inviting, energetic | + +**My take:** Utilitarian dense for power users, calm editorial for content-forward audiences. Playful split is weakest — tries to do both and commits to neither. +``` + +Let the user pick a winner, or combine two into a hybrid, or ask for another round. + +## Theming (when the project has a visual identity) + +If the user has an existing theme (colors, fonts, tokens), put shared tokens in `sketches/themes/tokens.css` and `@import` them in each variant. Keep tokens minimal: + +```css +/* sketches/themes/tokens.css */ +:root { + --color-bg: #fafafa; + --color-fg: #1a1a1a; + --color-accent: #0066ff; + --color-muted: #666; + --radius: 8px; + --font-display: "Inter", sans-serif; + --font-body: -apple-system, BlinkMacSystemFont, sans-serif; +} +``` + +Don't over-tokenize a throwaway sketch — three colors and one font is usually enough. + +## Interactivity bar + +A sketch is interactive enough when the user can: + +1. **Click a primary action** and something visible happens (state change, modal, toast, navigation feint) +2. **See one meaningful state transition** (filter a list, toggle a mode, open/close a panel) +3. **Hover recognizable affordances** (buttons, rows, tabs) + +More than that is over-engineering a throwaway. Less than that is a screenshot. + +## Frontier mode (picking what to sketch next) + +If sketches already exist and the user says "what should I sketch next?": + +- **Consistency gaps** — two winning variants from different sketches made independent choices that haven't been composed together yet +- **Unsketched screens** — referenced but never explored +- **State coverage** — happy path sketched, but not empty / loading / error / 1000-items +- **Responsive gaps** — validated at one viewport; does it hold at mobile / ultrawide? +- **Interaction patterns** — static layouts exist; transitions, drag, scroll behavior don't + +Propose 2-4 named candidates. Let the user pick. + +## Output + +- Create `sketches/` (or `.planning/sketches/` if the user is using GSD conventions) in the repo root +- One subdir per variant: `NNN-stance-name/index.html` + `README.md` +- Tell the user how to open them: `open sketches/001-calm-editorial/index.html` on macOS, `xdg-open` on Linux, `start` on Windows +- Keep variants disposable — a sketch that you felt the need to preserve should be promoted into real project code, not curated as an asset + +**Typical tool sequence for one variant:** + +``` +terminal("mkdir -p sketches/001-calm-editorial") +write_file("sketches/001-calm-editorial/index.html", "...") +write_file("sketches/001-calm-editorial/README.md", "## Variant: Calm editorial\n...") +browser_navigate(url="file://$(pwd)/sketches/001-calm-editorial/index.html") +browser_vision(question="How does this look? Any obvious layout issues?") +``` + +Repeat for each variant, then present the comparison table. + +## Attribution + +Adapted from the GSD (Get Shit Done) project's `/gsd-sketch` workflow — MIT © 2025 Lex Christopherson ([gsd-build/get-shit-done](https://github.com/gsd-build/get-shit-done)). The upstream GSD repo is now **archived/unmaintained** on GitHub; the `get-shit-done-cc` npm package still installs (`npx get-shit-done-cc --hermes --global`) and ships persistent sketch state, theme/variant pattern references, and consistency-audit workflows, but treat it as an archived community project. diff --git a/website/docs/user-guide/skills/optional/creative/creative-social-media-content-calendar.md b/website/docs/user-guide/skills/optional/creative/creative-social-media-content-calendar.md index fd57bca150..eaf72464eb 100644 --- a/website/docs/user-guide/skills/optional/creative/creative-social-media-content-calendar.md +++ b/website/docs/user-guide/skills/optional/creative/creative-social-media-content-calendar.md @@ -15,7 +15,7 @@ Plan multi-platform social campaigns: briefs to posting. | | | |---|---| | Source | Optional — install with `hermes skills install official/creative/social-media-content-calendar` | -| Path | `optional-skills/creative/social-media-content-calendar` | +| Path | `optional-skills/creative\social-media-content-calendar` | | Version | `0.1.0` | | Author | Ben Barclay (benbarclay), Hermes Agent | | License | MIT | diff --git a/website/docs/user-guide/skills/optional/creative/creative-tldraw-offline.md b/website/docs/user-guide/skills/optional/creative/creative-tldraw-offline.md index 59cc602b93..737d513912 100644 --- a/website/docs/user-guide/skills/optional/creative/creative-tldraw-offline.md +++ b/website/docs/user-guide/skills/optional/creative/creative-tldraw-offline.md @@ -15,7 +15,7 @@ Drive and script tldraw offline canvases with an agent. | | | |---|---| | Source | Optional — install with `hermes skills install official/creative/tldraw-offline` | -| Path | `optional-skills/creative/tldraw-offline` | +| Path | `optional-skills/creative\tldraw-offline` | | Version | `1.0.0` | | Author | Teknium + Hermes Agent | | License | MIT | @@ -80,11 +80,11 @@ is a live edit, not saved script: ```bash BASE=http://localhost:7236 -TOKEN=$(python3 -c "import json;print(json.load(open('$HOME/.config/tldraw/server.json'))['token'])") +TOKEN=$(python -c "import json;print(json.load(open('$HOME/.config/tldraw/server.json'))['token'])") # find the focused document id DOC=$(curl -s "$BASE/api/search" -X POST -H 'content-type: application/json' \ -H "Authorization: Bearer $TOKEN" \ - -d '{"code":"return (await api.getFocusedDoc()).id"}' | python3 -c "import sys,json;print(json.load(sys.stdin)['result'])") + -d '{"code":"return (await api.getFocusedDoc()).id"}' | python -c "import sys,json;print(json.load(sys.stdin)['result'])") # run code with the live `editor` + `helpers` in scope curl -s "$BASE/api/doc/$DOC/exec" -X POST -H 'content-type: application/json' \ -H "Authorization: Bearer $TOKEN" \ diff --git a/website/docs/user-guide/skills/optional/creative/creative-touchdesigner-mcp.md b/website/docs/user-guide/skills/optional/creative/creative-touchdesigner-mcp.md new file mode 100644 index 0000000000..befee1c288 --- /dev/null +++ b/website/docs/user-guide/skills/optional/creative/creative-touchdesigner-mcp.md @@ -0,0 +1,373 @@ +--- +title: "Touchdesigner Mcp — Control TouchDesigner via twozero MCP" +sidebar_label: "Touchdesigner Mcp" +description: "Control TouchDesigner via twozero MCP" +--- + +{/* 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. */} + +# Touchdesigner Mcp + +Control TouchDesigner via twozero MCP. + +## Skill metadata + +| | | +|---|---| +| Source | Optional — install with `hermes skills install official/creative/touchdesigner-mcp` | +| Path | `optional-skills/creative\touchdesigner-mcp` | +| Version | `1.1.0` | +| Author | kshitijk4poor | +| License | MIT | +| Platforms | linux, macos, windows | +| Tags | `TouchDesigner`, `MCP`, `twozero`, `creative-coding`, `real-time-visuals`, `generative-art`, `audio-reactive`, `VJ`, `installation`, `GLSL` | +| Related skills | [`ascii-video`](/docs/user-guide/skills/bundled/creative/creative-ascii-video), [`manim-video`](/docs/user-guide/skills/bundled/creative/creative-manim-video) | + +## 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. +::: + +# TouchDesigner Integration (twozero MCP) + +## CRITICAL RULES + +1. **NEVER guess parameter names.** Call `td_get_par_info` for the op type FIRST. Your training data is wrong for TD 2025.32. +2. **If `tdAttributeError` fires, STOP.** Call `td_get_operator_info` on the failing node before continuing. +3. **NEVER hardcode absolute paths** in script callbacks. Use `me.parent()` / `scriptOp.parent()`. +4. **Prefer native MCP tools over td_execute_python.** Use `td_create_operator`, `td_set_operator_pars`, `td_get_errors` etc. Only fall back to `td_execute_python` for complex multi-step logic. +5. **Call `td_get_hints` before building.** It returns patterns specific to the op type you're working with. + +## Architecture + +``` +Hermes Agent -> MCP (Streamable HTTP) -> twozero.tox (port 40404) -> TD Python +``` + +36 native tools. Free plugin (no payment/license — confirmed April 2026). +Context-aware (knows selected OP, current network). +Hub health check: `GET http://localhost:40404/mcp` returns JSON with instance PID, project name, TD version. + +## Setup (Automated) + +Run the setup script to handle everything: + +```bash +bash "${HERMES_HOME:-$HOME/.hermes}/skills/creative/touchdesigner-mcp/scripts/setup.sh" +``` + +The script will: +1. Check if TD is running +2. Download twozero.tox if not already cached +3. Add `twozero_td` MCP server to Hermes config (if missing) +4. Test the MCP connection on port 40404 +5. Report what manual steps remain (drag .tox into TD, enable MCP toggle) + +### Manual steps (one-time, cannot be automated) + +1. **Drag `~/Downloads/twozero.tox` into the TD network editor** → click Install +2. **Enable MCP:** click twozero icon → Settings → mcp → "auto start MCP" → Yes +3. **Restart Hermes session** to pick up the new MCP server + +After setup, verify: +```bash +nc -z 127.0.0.1 40404 && echo "twozero MCP: READY" +``` + +## Environment Notes + +- **Non-Commercial TD** caps resolution at 1280×1280. Use `outputresolution = 'custom'` and set width/height explicitly. +- **Codecs:** `prores` (preferred on macOS) or `mjpa` as fallback. H.264/H.265/AV1 require a Commercial license. +- Always call `td_get_par_info` before setting params — names vary by TD version (see CRITICAL RULES #1). + +## Workflow + +### Step 0: Discover (before building anything) + +``` +Call td_get_par_info with op_type for each type you plan to use. +Call td_get_hints with the topic you're building (e.g. "glsl", "audio reactive", "feedback"). +Call td_get_focus to see where the user is and what's selected. +Call td_get_network to see what already exists. +``` + +No temp nodes, no cleanup. This replaces the old discovery dance entirely. + +### Step 1: Clean + Build + +**IMPORTANT: Split cleanup and creation into SEPARATE MCP calls.** Destroying and recreating same-named nodes in one `td_execute_python` script causes "Invalid OP object" errors. See pitfalls #11b. + +Use `td_create_operator` for each node (handles viewport positioning automatically): + +``` +td_create_operator(type="noiseTOP", parent="/project1", name="bg", parameters={"resolutionw": 1280, "resolutionh": 720}) +td_create_operator(type="levelTOP", parent="/project1", name="brightness") +td_create_operator(type="nullTOP", parent="/project1", name="out") +``` + +For bulk creation or wiring, use `td_execute_python`: + +```python +# td_execute_python script: +root = op('/project1') +nodes = [] +for name, optype in [('bg', noiseTOP), ('fx', levelTOP), ('out', nullTOP)]: + n = root.create(optype, name) + nodes.append(n.path) +# Wire chain +for i in range(len(nodes)-1): + op(nodes[i]).outputConnectors[0].connect(op(nodes[i+1]).inputConnectors[0]) +result = {'created': nodes} +``` + +### Step 2: Set Parameters + +Prefer the native tool (validates params, won't crash): + +``` +td_set_operator_pars(path="/project1/bg", parameters={"roughness": 0.6, "monochrome": true}) +``` + +For expressions or modes, use `td_execute_python`: + +```python +op('/project1/time_driver').par.colorr.expr = "absTime.seconds % 1000.0" +``` + +### Step 3: Wire + +Use `td_execute_python` — no native wire tool exists: + +```python +op('/project1/bg').outputConnectors[0].connect(op('/project1/fx').inputConnectors[0]) +``` + +### Step 4: Verify + +``` +td_get_errors(path="/project1", recursive=true) +td_get_perf() +td_get_operator_info(path="/project1/out", detail="full") +``` + +### Step 5: Display / Capture + +``` +td_get_screenshot(path="/project1/out") +``` + +Or open a window via script: + +```python +win = op('/project1').create(windowCOMP, 'display') +win.par.winop = op('/project1/out').path +win.par.winw = 1280; win.par.winh = 720 +win.par.winopen.pulse() +``` + +## MCP Tool Quick Reference + +**Core (use these most):** +| Tool | What | +|------|------| +| `td_execute_python` | Run arbitrary Python in TD. Full API access. | +| `td_create_operator` | Create node with params + auto-positioning | +| `td_set_operator_pars` | Set params safely (validates, won't crash) | +| `td_get_operator_info` | Inspect one node: connections, params, errors | +| `td_get_operators_info` | Inspect multiple nodes in one call | +| `td_get_network` | See network structure at a path | +| `td_get_errors` | Find errors/warnings recursively | +| `td_get_par_info` | Get param names for an OP type (replaces discovery) | +| `td_get_hints` | Get patterns/tips before building | +| `td_get_focus` | What network is open, what's selected | + +**Read/Write:** +| Tool | What | +|------|------| +| `td_read_dat` | Read DAT text content | +| `td_write_dat` | Write/patch DAT content | +| `td_read_chop` | Read CHOP channel values | +| `td_read_textport` | Read TD console output | + +**Visual:** +| Tool | What | +|------|------| +| `td_get_screenshot` | Capture one OP viewer to file | +| `td_get_screenshots` | Capture multiple OPs at once | +| `td_get_screen_screenshot` | Capture actual screen via TD | +| `td_navigate_to` | Jump network editor to an OP | + +**Search:** +| Tool | What | +|------|------| +| `td_find_op` | Find ops by name/type across project | +| `td_search` | Search code, expressions, string params | + +**System:** +| Tool | What | +|------|------| +| `td_get_perf` | Performance profiling (FPS, slow ops) | +| `td_list_instances` | List all running TD instances | +| `td_get_docs` | In-depth docs on a TD topic | +| `td_agents_md` | Read/write per-COMP markdown docs | +| `td_reinit_extension` | Reload extension after code edit | +| `td_clear_textport` | Clear console before debug session | + +**Input Automation:** +| Tool | What | +|------|------| +| `td_input_execute` | Send mouse/keyboard to TD | +| `td_input_status` | Poll input queue status | +| `td_input_clear` | Stop input automation | +| `td_op_screen_rect` | Get screen coords of a node | +| `td_click_screen_point` | Click a point in a screenshot | +| `td_screen_point_to_global` | Convert screenshot pixel to absolute screen coords | + +The table above covers the 32 tools used in typical creative workflows. The remaining 4 tools (`td_project_quit`, `td_test_session`, `td_dev_log`, `td_clear_dev_log`) are admin/dev-mode utilities — see `references/mcp-tools.md` for the full 36-tool reference with complete parameter schemas. + +## Key Implementation Rules + +**GLSL time:** No `uTDCurrentTime` in GLSL TOP. Use the Values page: +```python +# Call td_get_par_info(op_type="glslTOP") first to confirm param names +td_set_operator_pars(path="/project1/shader", parameters={"value0name": "uTime"}) +# Then set expression via script: +# op('/project1/shader').par.value0.expr = "absTime.seconds" +# In GLSL: uniform float uTime; +``` + +Fallback: Constant TOP in `rgba32float` format (8-bit clamps to 0-1, freezing the shader). + +**Feedback TOP:** Use `top` parameter reference, not direct input wire. "Not enough sources" resolves after first cook. "Cook dependency loop" warning is expected. + +**Resolution:** Non-Commercial caps at 1280×1280. Use `outputresolution = 'custom'`. + +**Large shaders:** Write GLSL to `/tmp/file.glsl`, then use `td_write_dat` or `td_execute_python` to load. + +**Vertex/Point access (TD 2025.32):** `point.P[0]`, `point.P[1]`, `point.P[2]` — NOT `.x`, `.y`, `.z`. + +**Extensions:** `ext0object` format is `"op('./datName').module.ClassName(me)"` in CONSTANT mode. After editing extension code with `td_write_dat`, call `td_reinit_extension`. + +**Script callbacks:** ALWAYS use relative paths via `me.parent()` / `scriptOp.parent()`. + +**Cleaning nodes:** Always `list(root.children)` before iterating + `child.valid` check. + +## Recording / Exporting Video + +```python +# via td_execute_python: +root = op('/project1') +rec = root.create(moviefileoutTOP, 'recorder') +op('/project1/out').outputConnectors[0].connect(rec.inputConnectors[0]) +rec.par.type = 'movie' +rec.par.file = '/tmp/output.mov' +rec.par.videocodec = 'prores' # Apple ProRes — NOT license-restricted on macOS +rec.par.record = True # start +# rec.par.record = False # stop (call separately later) +``` + +H.264/H.265/AV1 need Commercial license. Use `prores` on macOS or `mjpa` as fallback. +Extract frames: `ffmpeg -i /tmp/output.mov -vframes 120 /tmp/frames/frame_%06d.png` + +**TOP.save() is useless for animation** — captures same GPU texture every time. Always use MovieFileOut. + +### Before Recording: Checklist + +1. **Verify FPS > 0** via `td_get_perf`. If FPS=0 the recording will be empty. See pitfalls #38-39. +2. **Verify shader output is not black** via `td_get_screenshot`. Black output = shader error or missing input. See pitfalls #8, #40. +3. **If recording with audio:** cue audio to start first, then delay recording by 3 frames. See pitfalls #19. +4. **Set output path before starting record** — setting both in the same script can race. + +## Audio-Reactive GLSL (Proven Recipe) + +### Correct signal chain (tested April 2026) + +``` +AudioFileIn CHOP (playmode=sequential) + → AudioSpectrum CHOP (FFT=512, outputmenu=setmanually, outlength=256, timeslice=ON) + → Math CHOP (gain=10) + → CHOP to TOP (dataformat=r, layout=rowscropped) + → GLSL TOP input 1 (spectrum texture, 256x2) + +Constant TOP (rgba32float, time) → GLSL TOP input 0 +GLSL TOP → Null TOP → MovieFileOut +``` + +### Critical audio-reactive rules (empirically verified) + +1. **TimeSlice must stay ON** for AudioSpectrum. OFF = processes entire audio file → 24000+ samples → CHOP to TOP overflow. +2. **Set Output Length manually** to 256 via `outputmenu='setmanually'` and `outlength=256`. Default outputs 22050 samples. +3. **DO NOT use Lag CHOP for spectrum smoothing.** Lag CHOP operates in timeslice mode and expands 256 samples to 2400+, averaging all values to near-zero (~1e-06). The shader receives no usable data. This was the #1 audio sync failure in testing. +4. **DO NOT use Filter CHOP either** — same timeslice expansion problem with spectrum data. +5. **Smoothing belongs in the GLSL shader** if needed, via temporal lerp with a feedback texture: `mix(prevValue, newValue, 0.3)`. This gives frame-perfect sync with zero pipeline latency. +6. **CHOP to TOP dataformat = 'r'**, layout = 'rowscropped'. Spectrum output is 256x2 (stereo). Sample at y=0.25 for first channel. +7. **Math gain = 10** (not 5). Raw spectrum values are ~0.19 in bass range. Gain of 10 gives usable ~5.0 for the shader. +8. **No Resample CHOP needed.** Control output size via AudioSpectrum's `outlength` param directly. + +### GLSL spectrum sampling + +```glsl +// Input 0 = time (1x1 rgba32float), Input 1 = spectrum (256x2) +float iTime = texture(sTD2DInputs[0], vec2(0.5)).r; + +// Sample multiple points per band and average for stability: +// NOTE: y=0.25 for first channel (stereo texture is 256x2, first row center is 0.25) +float bass = (texture(sTD2DInputs[1], vec2(0.02, 0.25)).r + + texture(sTD2DInputs[1], vec2(0.05, 0.25)).r) / 2.0; +float mid = (texture(sTD2DInputs[1], vec2(0.2, 0.25)).r + + texture(sTD2DInputs[1], vec2(0.35, 0.25)).r) / 2.0; +float hi = (texture(sTD2DInputs[1], vec2(0.6, 0.25)).r + + texture(sTD2DInputs[1], vec2(0.8, 0.25)).r) / 2.0; +``` + +See `references/network-patterns.md` for complete build scripts + shader code. + +## Operator Quick Reference + +| Family | Color | Python class / MCP type | Suffix | +|--------|-------|-------------|--------| +| TOP | Purple | noiseTOP, glslTOP, compositeTOP, levelTop, blurTOP, textTOP, nullTOP | TOP | +| CHOP | Green | audiofileinCHOP, audiospectrumCHOP, mathCHOP, lfoCHOP, constantCHOP | CHOP | +| SOP | Blue | gridSOP, sphereSOP, transformSOP, noiseSOP | SOP | +| DAT | White | textDAT, tableDAT, scriptDAT, webserverDAT | DAT | +| MAT | Yellow | phongMAT, pbrMAT, glslMAT, constMAT | MAT | +| COMP | Gray | geometryCOMP, containerCOMP, cameraCOMP, lightCOMP, windowCOMP | COMP | + +## Security Notes + +- MCP runs on localhost only (port 40404). No authentication — any local process can send commands. +- `td_execute_python` has unrestricted access to the TD Python environment and filesystem as the TD process user. +- `setup.sh` downloads twozero.tox from the official 404zero.com URL. Verify the download if concerned. +- The skill never sends data outside localhost. All MCP communication is local. + +## References + +| File | What | +|------|------| +| `references/pitfalls.md` | Hard-won lessons from real sessions | +| `references/operators.md` | All operator families with params and use cases | +| `references/network-patterns.md` | Recipes: audio-reactive, generative, GLSL, instancing | +| `references/mcp-tools.md` | Full twozero MCP tool parameter schemas | +| `references/python-api.md` | TD Python: op(), scripting, extensions | +| `references/troubleshooting.md` | Connection diagnostics, debugging | +| `references/glsl.md` | GLSL uniforms, built-in functions, shader templates | +| `references/postfx.md` | Post-FX: bloom, CRT, chromatic aberration, feedback glow | +| `references/layout-compositor.md` | HUD layout patterns, panel grids, BSP-style layouts | +| `references/operator-tips.md` | Wireframe rendering, feedback TOP setup | +| `references/geometry-comp.md` | Geometry COMP: instancing, POP vs SOP, morphing | +| `references/audio-reactive.md` | Audio band extraction, beat detection, envelope following | +| `references/animation.md` | LFOs, timers, keyframes, easing, expression-driven motion | +| `references/midi-osc.md` | MIDI/OSC controllers, TouchOSC, multi-machine sync | +| `references/particles.md` | POPs and legacy particleSOP — emission, forces, collisions | +| `references/projection-mapping.md` | Multi-window output, corner pin, mesh warp, edge blending | +| `references/external-data.md` | HTTP, WebSocket, MQTT, Serial, TCP, webserverDAT | +| `references/panel-ui.md` | Custom params, panel COMPs, button/slider/field, panelExecuteDAT | +| `references/replicator.md` | replicatorCOMP — data-driven cloning, layouts, callbacks | +| `references/dat-scripting.md` | Execute DAT family — chop/dat/parameter/panel/op/executeDAT | +| `references/3d-scene.md` | Lighting rigs, shadows, IBL/cubemaps, multi-camera, PBR | +| `scripts/setup.sh` | Automated setup script | + +--- + +> You're not writing code. You're conducting light. diff --git a/website/docs/user-guide/skills/optional/creative/creative-unreal-mcp.md b/website/docs/user-guide/skills/optional/creative/creative-unreal-mcp.md index 65aa94e9e1..6e8ccc000e 100644 --- a/website/docs/user-guide/skills/optional/creative/creative-unreal-mcp.md +++ b/website/docs/user-guide/skills/optional/creative/creative-unreal-mcp.md @@ -15,7 +15,7 @@ Automate Unreal Engine editor scenes, actors, and renders. | | | |---|---| | Source | Optional — install with `hermes skills install official/creative/unreal-mcp` | -| Path | `optional-skills/creative/unreal-mcp` | +| Path | `optional-skills/creative\unreal-mcp` | | Version | `1.0.0` | | Author | Hermes Agent | | License | MIT | diff --git a/website/docs/user-guide/skills/optional/data-science/data-science-jupyter-notebook.md b/website/docs/user-guide/skills/optional/data-science/data-science-jupyter-notebook.md index a869a968d2..3d5f5780ff 100644 --- a/website/docs/user-guide/skills/optional/data-science/data-science-jupyter-notebook.md +++ b/website/docs/user-guide/skills/optional/data-science/data-science-jupyter-notebook.md @@ -15,7 +15,7 @@ Iterative Python via live Jupyter kernel (hamelnb). | | | |---|---| | Source | Optional — install with `hermes skills install official/data-science/jupyter-notebook` | -| Path | `optional-skills/data-science/jupyter-notebook` | +| Path | `optional-skills/data-science\jupyter-notebook` | | Version | `1.0.0` | | Author | Hermes Agent | | License | MIT | @@ -89,7 +89,7 @@ session via the Jupyter REST API: ``` curl -s -X POST http://127.0.0.1:8888/api/sessions \ -H "Content-Type: application/json" \ - -d '{"path":"scratch.ipynb","type":"notebook","name":"scratch.ipynb","kernel":{"name":"python3"}}' + -d '{"path":"scratch.ipynb","type":"notebook","name":"scratch.ipynb","kernel":{"name":"python"}}' ``` ## Core Workflow diff --git a/website/docs/user-guide/skills/optional/devops/devops-actual-setup.md b/website/docs/user-guide/skills/optional/devops/devops-actual-setup.md index d7fa4bd756..450eb93bc9 100644 --- a/website/docs/user-guide/skills/optional/devops/devops-actual-setup.md +++ b/website/docs/user-guide/skills/optional/devops/devops-actual-setup.md @@ -15,7 +15,7 @@ Set up Actual Computer (actual.inc) inference in Hermes. | | | |---|---| | Source | Optional — install with `hermes skills install official/devops/actual-setup` | -| Path | `optional-skills/devops/actual-setup` | +| Path | `optional-skills/devops\actual-setup` | | Version | `2.0.0` | | Author | shl0ms + Hermes Agent | | License | MIT | diff --git a/website/docs/user-guide/skills/optional/devops/devops-docker-management.md b/website/docs/user-guide/skills/optional/devops/devops-docker-management.md index bc9c60c9c6..d2cff31536 100644 --- a/website/docs/user-guide/skills/optional/devops/devops-docker-management.md +++ b/website/docs/user-guide/skills/optional/devops/devops-docker-management.md @@ -15,7 +15,7 @@ Manage Docker containers, images, volumes, and Compose. | | | |---|---| | Source | Optional — install with `hermes skills install official/devops/docker-management` | -| Path | `optional-skills/devops/docker-management` | +| Path | `optional-skills/devops\docker-management` | | Version | `1.0.0` | | Author | sprmn24 | | License | MIT | @@ -194,7 +194,8 @@ services: ports: - "3000:3000" environment: - - DATABASE_URL=postgres://user:pass@db:5432/mydb + # Password comes from the POSTGRES_PASSWORD secret, not the URL + - DATABASE_URL=postgres://mydb_user@db:5432/mydb depends_on: db: condition: service_healthy diff --git a/website/docs/user-guide/skills/optional/devops/devops-hermes-s6-container-supervision.md b/website/docs/user-guide/skills/optional/devops/devops-hermes-s6-container-supervision.md index 6bcadfa0ac..76b34e9c3e 100644 --- a/website/docs/user-guide/skills/optional/devops/devops-hermes-s6-container-supervision.md +++ b/website/docs/user-guide/skills/optional/devops/devops-hermes-s6-container-supervision.md @@ -15,7 +15,7 @@ Modify or debug s6 services in the Hermes Docker image. | | | |---|---| | Source | Optional — install with `hermes skills install official/devops/hermes-s6-container-supervision` | -| Path | `optional-skills/devops/hermes-s6-container-supervision` | +| Path | `optional-skills/devops\hermes-s6-container-supervision` | | Version | `1.0.0` | | Author | Hermes Agent | | License | MIT | @@ -82,7 +82,8 @@ If you're just running the Hermes Agent and want to use Docker, see `website/doc | Path | Role | |---|---| -| `Dockerfile` | s6-overlay install + cont-init.d wiring + `ENTRYPOINT ["/init", "/opt/hermes/docker/main-wrapper.sh"]` | +| `Dockerfile` | s6-overlay install + cont-init.d wiring + `ENTRYPOINT ["/opt/hermes/docker/entrypoint-dispatch.sh"]` | +| `docker/entrypoint-dispatch.sh` | PID-1 dispatcher: exec's `/init` + main-wrapper when the image owns PID 1; on wrapped runtimes (Fly Machines, `docker run --init`) falls back to stage2-hook + main-wrapper directly, restoring the s6 helper PATH first (#38349). | | `docker/stage2-hook.sh` | The "old entrypoint logic" — UID remap, chown, seed, skills sync. Runs as cont-init.d/01-hermes-setup. | | `docker/cont-init.d/02-reconcile-profiles` | Calls `hermes_cli.container_boot` on every boot to restore profile gateway slots from the persistent volume. | | `docker/main-wrapper.sh` | The container's CMD. Routes user args, drops to hermes via `s6-setuidgid`, exec's the chosen program. | @@ -100,7 +101,7 @@ The original plan (v1–v3) called for main hermes to run as a supervised s6-rc 1. **cont-init.d scripts receive no CMD args** — so the stage2 hook can't parse `docker run chat -q "hi"` to set `HERMES_ARGS` for a service `run` script to consume. 2. **`/run/s6/basedir/bin/halt` does NOT propagate the exit code** written to `/run/s6-linux-init-container-results/exitcode`. Containers always exit 143 (SIGTERM) regardless. Confirmed by skarnet (s6 author) in [issue #477](https://github.com/just-containers/s6-overlay/issues/477): _"if you want a container shutdown, you need to either have your CMD exit, or, if you have no CMD, write the container exit code you want then call halt"_. -So we use the s6-overlay-native CMD pattern: `ENTRYPOINT ["/init", "/opt/hermes/docker/main-wrapper.sh"]`. /init prepends the wrapper to user args automatically — so `docker run --version` becomes `/init main-wrapper.sh --version`, and `--version` doesn't get intercepted by /init's POSIX shell. The wrapper drops to hermes via `s6-setuidgid`, then exec's the chosen program. The program's exit code becomes the container exit code, exactly matching the pre-s6 tini contract. +So we use the s6-overlay-native CMD pattern via the dispatcher: `ENTRYPOINT ["/opt/hermes/docker/entrypoint-dispatch.sh"]`, which under PID 1 exec's `/init /opt/hermes/docker/main-wrapper.sh "$@"`. The wrapper is prepended to user args automatically — so `docker run --version` becomes `/init main-wrapper.sh --version`, and `--version` doesn't get intercepted by /init's POSIX shell. The wrapper drops to hermes via `s6-setuidgid`, then exec's the chosen program. The program's exit code becomes the container exit code, exactly matching the pre-s6 tini contract. When the entrypoint is NOT PID 1 (Fly Machines, `docker run --init`), the dispatcher skips `/init` entirely (it would abort with `can only run as pid 1`), restores the s6 helper PATH, runs stage2-hook.sh, and exec's main-wrapper.sh directly — no supervised services on that path (#38349). Trade-off: main hermes is unsupervised under s6. That exactly matches its behavior under tini (the pre-s6 image). Dashboard supervision is the only **new** guarantee — and per-profile gateways under `/run/service/` get full supervision. diff --git a/website/docs/user-guide/skills/optional/devops/devops-inference-sh-cli.md b/website/docs/user-guide/skills/optional/devops/devops-inference-sh-cli.md index 0fe5f1dfa7..295c14b0cc 100644 --- a/website/docs/user-guide/skills/optional/devops/devops-inference-sh-cli.md +++ b/website/docs/user-guide/skills/optional/devops/devops-inference-sh-cli.md @@ -15,7 +15,7 @@ Run 150+ AI apps (image, video, LLM) via inference.sh CLI. | | | |---|---| | Source | Optional — install with `hermes skills install official/devops/inference-sh-cli` | -| Path | `optional-skills/devops/inference-sh-cli` | +| Path | `optional-skills/devops\inference-sh-cli` | | Version | `1.0.0` | | Author | okaris | | License | MIT | diff --git a/website/docs/user-guide/skills/optional/devops/devops-pinggy-tunnel.md b/website/docs/user-guide/skills/optional/devops/devops-pinggy-tunnel.md index ff7ec24d22..de59598e06 100644 --- a/website/docs/user-guide/skills/optional/devops/devops-pinggy-tunnel.md +++ b/website/docs/user-guide/skills/optional/devops/devops-pinggy-tunnel.md @@ -15,7 +15,7 @@ Zero-install localhost tunnels over SSH via Pinggy. | | | |---|---| | Source | Optional — install with `hermes skills install official/devops/pinggy-tunnel` | -| Path | `optional-skills/devops/pinggy-tunnel` | +| Path | `optional-skills/devops\pinggy-tunnel` | | Version | `0.1.0` | | Author | Teknium (teknium1), Hermes Agent | | License | MIT | @@ -96,7 +96,7 @@ curl -sI http://127.0.0.1:8000/ | head -1 # expect HTTP/1.x 200 (or any non-connection-refused response) ``` -If nothing is listening yet, start it first (e.g. `python3 -m http.server 8000 --bind 127.0.0.1`). Pinggy will happily return a URL pointed at nothing — the user will see 502 until the origin comes up. +If nothing is listening yet, start it first (e.g. `python -m http.server 8000 --bind 127.0.0.1`). Pinggy will happily return a URL pointed at nothing — the user will see 502 until the origin comes up. ### 2. Launch the tunnel as a background process @@ -220,7 +220,7 @@ class H(http.server.BaseHTTPRequestHandler): def log_message(self,*a,**k): pass http.server.HTTPServer(("127.0.0.1", 18080), H).serve_forever() PY -nohup python3 /tmp/webhook-server.py >/tmp/webhook-server.log 2>&1 & +nohup python /tmp/webhook-server.py >/tmp/webhook-server.log 2>&1 & echo $! >/tmp/webhook-server.pid # 2. Tunnel — bearer-token-gate so randos can't pollute the capture log @@ -245,7 +245,7 @@ Use when a remote MCP client (Claude Desktop on another machine, a teammate's ed ```bash # 1. Start the MCP server in HTTP mode (example: a FastMCP server on port 8765) -nohup python3 my_mcp_server.py --transport http --port 8765 \ +nohup python my_mcp_server.py --transport http --port 8765 \ >/tmp/mcp-server.log 2>&1 & echo $! >/tmp/mcp-server.pid @@ -306,7 +306,7 @@ ssh -p 443 -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \ ```bash # End-to-end: spin up a trivial origin, tunnel it, hit it, tear down -python3 -m http.server 18000 --bind 127.0.0.1 >/tmp/origin.log 2>&1 & +python -m http.server 18000 --bind 127.0.0.1 >/tmp/origin.log 2>&1 & ORIGIN_PID=$! nohup ssh -p 443 \ diff --git a/website/docs/user-guide/skills/optional/devops/devops-setup-wizard-generator.md b/website/docs/user-guide/skills/optional/devops/devops-setup-wizard-generator.md index ec89593a37..077235163e 100644 --- a/website/docs/user-guide/skills/optional/devops/devops-setup-wizard-generator.md +++ b/website/docs/user-guide/skills/optional/devops/devops-setup-wizard-generator.md @@ -15,7 +15,7 @@ Generate a bash wizard guiding a human through manual setup. | | | |---|---| | Source | Optional — install with `hermes skills install official/devops/setup-wizard-generator` | -| Path | `optional-skills/devops/setup-wizard-generator` | +| Path | `optional-skills/devops\setup-wizard-generator` | | Version | `1.0.0` | | Author | Matt Pocock (mattpocock/skills, wizard) + Hermes Agent | | License | MIT | diff --git a/website/docs/user-guide/skills/optional/devops/devops-watchers.md b/website/docs/user-guide/skills/optional/devops/devops-watchers.md index 9d2fc7f752..b1860772f7 100644 --- a/website/docs/user-guide/skills/optional/devops/devops-watchers.md +++ b/website/docs/user-guide/skills/optional/devops/devops-watchers.md @@ -15,7 +15,7 @@ Poll RSS, JSON APIs, and GitHub with watermark dedup. | | | |---|---| | Source | Optional — install with `hermes skills install official/devops/watchers` | -| Path | `optional-skills/devops/watchers` | +| Path | `optional-skills/devops\watchers` | | Version | `1.0.0` | | Author | Hermes Agent | | License | MIT | diff --git a/website/docs/user-guide/skills/optional/dogfood/dogfood-adversarial-ux-test.md b/website/docs/user-guide/skills/optional/dogfood/dogfood-adversarial-ux-test.md index 2a552a5846..4bef37dab1 100644 --- a/website/docs/user-guide/skills/optional/dogfood/dogfood-adversarial-ux-test.md +++ b/website/docs/user-guide/skills/optional/dogfood/dogfood-adversarial-ux-test.md @@ -15,7 +15,7 @@ Roleplay a hostile user to find and triage UX pain points. | | | |---|---| | Source | Optional — install with `hermes skills install official/dogfood/adversarial-ux-test` | -| Path | `optional-skills/dogfood/adversarial-ux-test` | +| Path | `optional-skills/dogfood\adversarial-ux-test` | | Version | `1.0.0` | | Author | Omni @ Comelse | | License | MIT | diff --git a/website/docs/user-guide/skills/optional/email/email-agentmail.md b/website/docs/user-guide/skills/optional/email/email-agentmail.md index 5fb31dba0f..26c682c381 100644 --- a/website/docs/user-guide/skills/optional/email/email-agentmail.md +++ b/website/docs/user-guide/skills/optional/email/email-agentmail.md @@ -15,7 +15,7 @@ Use when an agent needs AgentMail CLI email inboxes. | | | |---|---| | Source | Optional — install with `hermes skills install official/email/agentmail` | -| Path | `optional-skills/email/agentmail` | +| Path | `optional-skills/email\agentmail` | | Version | `1.0.0` | | Author | Haakam Aujla (Haakam21), AgentMail | | License | MIT | @@ -58,7 +58,7 @@ npm install -g agentmail-cli@latest export AGENTMAIL_API_KEY="am_..." ``` -No API key yet? Use [signup.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/email/agentmail/references/signup.md). +No API key yet? Use [signup.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/email\agentmail/references/signup.md). ## How to Run @@ -74,20 +74,20 @@ agentmail inboxes list --format json - [AgentMail](https://agentmail.to): product landing page. - [Console](https://console.agentmail.to): API keys and account management. - [Docs](https://docs.agentmail.to): full product documentation. -- [signup.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/email/agentmail/references/signup.md): self-signup and OTP verification. -- [core.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/email/agentmail/references/core.md): inboxes, messages, threads, labels, attachments. -- [webhooks.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/email/agentmail/references/webhooks.md): events to a public HTTPS server. -- [websockets.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/email/agentmail/references/websockets.md): events to a local agent process. -- [mcp.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/email/agentmail/references/mcp.md): MCP integration. +- [signup.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/email\agentmail/references/signup.md): self-signup and OTP verification. +- [core.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/email\agentmail/references/core.md): inboxes, messages, threads, labels, attachments. +- [webhooks.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/email\agentmail/references/webhooks.md): events to a public HTTPS server. +- [websockets.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/email\agentmail/references/websockets.md): events to a local agent process. +- [mcp.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/email\agentmail/references/mcp.md): MCP integration. ## Procedure 1. Install `agentmail-cli@latest` and verify `agentmail inboxes list --format json`. -2. If no API key is available, complete [signup.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/email/agentmail/references/signup.md). -3. Use [core.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/email/agentmail/references/core.md) for inbox, send, read, reply, forward, +2. If no API key is available, complete [signup.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/email\agentmail/references/signup.md). +3. Use [core.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/email\agentmail/references/core.md) for inbox, send, read, reply, forward, label, thread, and attachment flows. -4. Add [webhooks.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/email/agentmail/references/webhooks.md) or - [websockets.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/email/agentmail/references/websockets.md) only when polling is not enough. +4. Add [webhooks.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/email\agentmail/references/webhooks.md) or + [websockets.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/email\agentmail/references/websockets.md) only when polling is not enough. ## Pitfalls diff --git a/website/docs/user-guide/skills/optional/finance/finance-3-statement-model.md b/website/docs/user-guide/skills/optional/finance/finance-3-statement-model.md index d945e58e49..250d7fadf4 100644 --- a/website/docs/user-guide/skills/optional/finance/finance-3-statement-model.md +++ b/website/docs/user-guide/skills/optional/finance/finance-3-statement-model.md @@ -15,7 +15,7 @@ Build integrated IS/BS/CF financial workbooks in Excel. | | | |---|---| | Source | Optional — install with `hermes skills install official/finance/3-statement-model` | -| Path | `optional-skills/finance/3-statement-model` | +| Path | `optional-skills/finance\3-statement-model` | | Version | `1.0.0` | | Author | Anthropic (adapted by Nous Research) | | License | Apache-2.0 | @@ -194,7 +194,7 @@ Use a scenario toggle (dropdown) in the Assumptions tab with CHOOSE or INDEX/MAT ## SEC Filings Data Extraction -If the template specifically requires pulling data from SEC filings (10-K, 10-Q), see [references/sec-filings.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/finance/3-statement-model/references/sec-filings.md) for detailed extraction guidance. This reference is only needed when populating templates with public company data from regulatory filings. +If the template specifically requires pulling data from SEC filings (10-K, 10-Q), see [references/sec-filings.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/finance\3-statement-model/references/sec-filings.md) for detailed extraction guidance. This reference is only needed when populating templates with public company data from regulatory filings. ## Completing Model Templates @@ -327,7 +327,7 @@ This section consolidates all validation checks and audit procedures for complet ### Core Linkages (Must Always Hold) -See [references/formulas.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/finance/3-statement-model/references/formulas.md) for all formula details. +See [references/formulas.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/finance\3-statement-model/references/formulas.md) for all formula details. | Check | Formula | Expected Result | |-------|---------|-----------------| diff --git a/website/docs/user-guide/skills/optional/finance/finance-comps-analysis.md b/website/docs/user-guide/skills/optional/finance/finance-comps-analysis.md index 192f0f98e5..de8d1aa2e4 100644 --- a/website/docs/user-guide/skills/optional/finance/finance-comps-analysis.md +++ b/website/docs/user-guide/skills/optional/finance/finance-comps-analysis.md @@ -15,7 +15,7 @@ Build comparable-company valuation workbooks in Excel. | | | |---|---| | Source | Optional — install with `hermes skills install official/finance/comps-analysis` | -| Path | `optional-skills/finance/comps-analysis` | +| Path | `optional-skills/finance\comps-analysis` | | Version | `1.0.0` | | Author | Anthropic (adapted by Nous Research) | | License | Apache-2.0 | diff --git a/website/docs/user-guide/skills/optional/finance/finance-dcf-model.md b/website/docs/user-guide/skills/optional/finance/finance-dcf-model.md index 34a847d2db..689df50dd3 100644 --- a/website/docs/user-guide/skills/optional/finance/finance-dcf-model.md +++ b/website/docs/user-guide/skills/optional/finance/finance-dcf-model.md @@ -15,7 +15,7 @@ Build discounted cash flow valuation workbooks in Excel. | | | |---|---| | Source | Optional — install with `hermes skills install official/finance/dcf-model` | -| Path | `optional-skills/finance/dcf-model` | +| Path | `optional-skills/finance\dcf-model` | | Version | `1.0.0` | | Author | Anthropic (adapted by Nous Research) | | License | Apache-2.0 | @@ -1196,7 +1196,7 @@ This approach centralizes scenario logic, making the model easier to audit and m ## Troubleshooting -**If you encounter errors or unreasonable results, read [TROUBLESHOOTING.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/finance/dcf-model/TROUBLESHOOTING.md) for detailed debugging guidance.** +**If you encounter errors or unreasonable results, read [TROUBLESHOOTING.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/finance\dcf-model/TROUBLESHOOTING.md) for detailed debugging guidance.** ## Workflow Integration @@ -1234,7 +1234,7 @@ This approach centralizes scenario logic, making the model easier to audit and m 3. **Check output**: - If `status` is `"success"` → Continue to step 4 - - If `status` is `"errors_found"` → Check `error_summary` and read [TROUBLESHOOTING.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/finance/dcf-model/TROUBLESHOOTING.md) for debugging guidance + - If `status` is `"errors_found"` → Check `error_summary` and read [TROUBLESHOOTING.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/finance\dcf-model/TROUBLESHOOTING.md) for debugging guidance 4. **Fix errors and re-run recalc.py** until status is "success" diff --git a/website/docs/user-guide/skills/optional/finance/finance-excel-author.md b/website/docs/user-guide/skills/optional/finance/finance-excel-author.md index 732080ee06..50e1e36f80 100644 --- a/website/docs/user-guide/skills/optional/finance/finance-excel-author.md +++ b/website/docs/user-guide/skills/optional/finance/finance-excel-author.md @@ -15,7 +15,7 @@ Build auditable financial workbooks headless via openpyxl. | | | |---|---| | Source | Optional — install with `hermes skills install official/finance/excel-author` | -| Path | `optional-skills/finance/excel-author` | +| Path | `optional-skills/finance\excel-author` | | Version | `1.0.0` | | Author | Anthropic (adapted by Nous Research) | | License | Apache-2.0 | diff --git a/website/docs/user-guide/skills/optional/finance/finance-lbo-model.md b/website/docs/user-guide/skills/optional/finance/finance-lbo-model.md index 052cf58809..2746010729 100644 --- a/website/docs/user-guide/skills/optional/finance/finance-lbo-model.md +++ b/website/docs/user-guide/skills/optional/finance/finance-lbo-model.md @@ -15,7 +15,7 @@ Build leveraged buyout workbooks with IRR/MOIC in Excel. | | | |---|---| | Source | Optional — install with `hermes skills install official/finance/lbo-model` | -| Path | `optional-skills/finance/lbo-model` | +| Path | `optional-skills/finance\lbo-model` | | Version | `1.0.0` | | Author | Anthropic (adapted by Nous Research) | | License | Apache-2.0 | diff --git a/website/docs/user-guide/skills/optional/finance/finance-merger-model.md b/website/docs/user-guide/skills/optional/finance/finance-merger-model.md index c7876caac8..89c34a2cf1 100644 --- a/website/docs/user-guide/skills/optional/finance/finance-merger-model.md +++ b/website/docs/user-guide/skills/optional/finance/finance-merger-model.md @@ -15,7 +15,7 @@ Build M&A accretion/dilution workbooks in Excel. | | | |---|---| | Source | Optional — install with `hermes skills install official/finance/merger-model` | -| Path | `optional-skills/finance/merger-model` | +| Path | `optional-skills/finance\merger-model` | | Version | `1.0.0` | | Author | Anthropic (adapted by Nous Research) | | License | Apache-2.0 | diff --git a/website/docs/user-guide/skills/optional/finance/finance-polymarket.md b/website/docs/user-guide/skills/optional/finance/finance-polymarket.md index 78f370685a..f320f55dfa 100644 --- a/website/docs/user-guide/skills/optional/finance/finance-polymarket.md +++ b/website/docs/user-guide/skills/optional/finance/finance-polymarket.md @@ -15,7 +15,7 @@ Query Polymarket: markets, prices, orderbooks, history. | | | |---|---| | Source | Optional — install with `hermes skills install official/finance/polymarket` | -| Path | `optional-skills/finance/polymarket` | +| Path | `optional-skills/finance\polymarket` | | Version | `1.0.0` | | Author | Hermes Agent + Teknium | | License | MIT | diff --git a/website/docs/user-guide/skills/optional/finance/finance-pptx-author.md b/website/docs/user-guide/skills/optional/finance/finance-pptx-author.md index ae7d711c39..4f5b5f28c3 100644 --- a/website/docs/user-guide/skills/optional/finance/finance-pptx-author.md +++ b/website/docs/user-guide/skills/optional/finance/finance-pptx-author.md @@ -15,7 +15,7 @@ Build PowerPoint decks headless with python-pptx. | | | |---|---| | Source | Optional — install with `hermes skills install official/finance/pptx-author` | -| Path | `optional-skills/finance/pptx-author` | +| Path | `optional-skills/finance\pptx-author` | | Version | `1.0.0` | | Author | Anthropic (adapted by Nous Research) | | License | Apache-2.0 | diff --git a/website/docs/user-guide/skills/optional/finance/finance-stocks.md b/website/docs/user-guide/skills/optional/finance/finance-stocks.md index 7c43dea306..b855ca4ac3 100644 --- a/website/docs/user-guide/skills/optional/finance/finance-stocks.md +++ b/website/docs/user-guide/skills/optional/finance/finance-stocks.md @@ -15,7 +15,7 @@ Stock quotes, history, search, compare, crypto via Yahoo. | | | |---|---| | Source | Optional — install with `hermes skills install official/finance/stocks` | -| Path | `optional-skills/finance/stocks` | +| Path | `optional-skills/finance\stocks` | | Version | `0.1.0` | | Author | Mibay (Mibayy), Hermes Agent | | License | MIT | @@ -55,7 +55,7 @@ Invoke through the `terminal` tool. Once installed: ``` SCRIPT=~/.hermes/skills/finance/stocks/scripts/stocks_client.py -python3 $SCRIPT quote AAPL +python $SCRIPT quote AAPL ``` All output is JSON on stdout — pipe through `jq` if you want to slice it. @@ -63,12 +63,12 @@ All output is JSON on stdout — pipe through `jq` if you want to slice it. ## Quick Reference ``` -python3 $SCRIPT quote AAPL -python3 $SCRIPT quote AAPL MSFT GOOGL TSLA -python3 $SCRIPT search "Tesla" -python3 $SCRIPT history NVDA --range 6mo -python3 $SCRIPT compare AAPL MSFT GOOGL -python3 $SCRIPT crypto BTC ETH SOL +python $SCRIPT quote AAPL +python $SCRIPT quote AAPL MSFT GOOGL TSLA +python $SCRIPT search "Tesla" +python $SCRIPT history NVDA --range 6mo +python $SCRIPT compare AAPL MSFT GOOGL +python $SCRIPT crypto BTC ETH SOL ``` ## Commands @@ -106,7 +106,7 @@ Crypto prices. Pass `BTC` (the script appends `-USD` automatically). ## Verification ``` -python3 ~/.hermes/skills/finance/stocks/scripts/stocks_client.py quote AAPL +python ~/.hermes/skills/finance/stocks/scripts/stocks_client.py quote AAPL ``` Returns a JSON object with `symbol: "AAPL"` and a numeric `price` field. diff --git a/website/docs/user-guide/skills/optional/gaming/gaming-minecraft-modpack-server.md b/website/docs/user-guide/skills/optional/gaming/gaming-minecraft-modpack-server.md index 4b8f0ec356..2f0e925f23 100644 --- a/website/docs/user-guide/skills/optional/gaming/gaming-minecraft-modpack-server.md +++ b/website/docs/user-guide/skills/optional/gaming/gaming-minecraft-modpack-server.md @@ -15,7 +15,7 @@ Host modded Minecraft servers (CurseForge, Modrinth). | | | |---|---| | Source | Optional — install with `hermes skills install official/gaming/minecraft-modpack-server` | -| Path | `optional-skills/gaming/minecraft-modpack-server` | +| Path | `optional-skills/gaming\minecraft-modpack-server` | | Version | `1.0.0` | | Author | Teknium (teknium1), Hermes Agent | | License | MIT | diff --git a/website/docs/user-guide/skills/optional/gaming/gaming-pokemon-player.md b/website/docs/user-guide/skills/optional/gaming/gaming-pokemon-player.md index 3a98d97a75..c7cde4080a 100644 --- a/website/docs/user-guide/skills/optional/gaming/gaming-pokemon-player.md +++ b/website/docs/user-guide/skills/optional/gaming/gaming-pokemon-player.md @@ -15,7 +15,7 @@ Play Pokemon via headless emulator + RAM reads. | | | |---|---| | Source | Optional — install with `hermes skills install official/gaming/pokemon-player` | -| Path | `optional-skills/gaming/pokemon-player` | +| Path | `optional-skills/gaming\pokemon-player` | | Version | `1.0.0` | | Author | Teknium (teknium1), Hermes Agent | | License | MIT | @@ -43,7 +43,7 @@ Play Pokemon games via headless emulation using the `pokemon-agent` package. The repo is NousResearch/pokemon-agent on GitHub. Clone it, then set up a Python 3.10+ virtual environment. Use uv (preferred for speed) to create the venv and install the package in editable mode with the -pyboy extra. If uv is not available, fall back to python3 -m venv + pip. +pyboy extra. If uv is not available, fall back to python -m venv + pip. If a checkout already exists (e.g. ~/pokemon-agent with a venv ready), just cd there and source .venv/bin/activate instead of recloning. diff --git a/website/docs/user-guide/skills/optional/health/health-fitness-nutrition.md b/website/docs/user-guide/skills/optional/health/health-fitness-nutrition.md index feb2a45049..1ff5827959 100644 --- a/website/docs/user-guide/skills/optional/health/health-fitness-nutrition.md +++ b/website/docs/user-guide/skills/optional/health/health-fitness-nutrition.md @@ -15,7 +15,7 @@ Workout planning, macros, and body metrics via wger/USDA. | | | |---|---| | Source | Optional — install with `hermes skills install official/health/fitness-nutrition` | -| Path | `optional-skills/health/fitness-nutrition` | +| Path | `optional-skills/health\fitness-nutrition` | | Version | `1.0.0` | | Author | Hailey Marshall (haileymarshall), Hermes Agent | | License | MIT | @@ -117,9 +117,9 @@ Equipment: ```bash # Search exercises by name QUERY="$1" -ENCODED=$(python3 -c "import urllib.parse,sys; print(urllib.parse.quote(sys.argv[1]))" "$QUERY") +ENCODED=$(python -c "import urllib.parse,sys; print(urllib.parse.quote(sys.argv[1]))" "$QUERY") curl -s "https://wger.de/api/v2/exercise/search/?term=${ENCODED}&language=english&format=json" \ - | python3 -c " + | python -c " import json,sys data=json.load(sys.stdin) for s in data.get('suggestions',[])[:10]: @@ -132,7 +132,7 @@ for s in data.get('suggestions',[])[:10]: # Get full details for a specific exercise EXERCISE_ID="$1" curl -s "https://wger.de/api/v2/exerciseinfo/${EXERCISE_ID}/?format=json" \ - | python3 -c " + | python -c " import json,sys,html,re data=json.load(sys.stdin) trans=[t for t in data.get('translations',[]) if t.get('language')==2] @@ -154,7 +154,7 @@ if imgs: print(f\"Image : {imgs[0].get('image','')}\") # Combine filters as needed: ?muscles=4&equipment=1&language=2&status=2 FILTER="$1" # e.g. "muscles=4" or "category=11" or "equipment=3" curl -s "https://wger.de/api/v2/exercise/?${FILTER}&language=2&status=2&limit=20&format=json" \ - | python3 -c " + | python -c " import json,sys data=json.load(sys.stdin) print(f'Found {data.get(\"count\",0)} exercises.') @@ -172,9 +172,9 @@ DEMO_KEY = 30 requests/hour. Free signup key = 1,000 requests/hour. # Search foods by name FOOD="$1" API_KEY="${USDA_API_KEY:-DEMO_KEY}" -ENCODED=$(python3 -c "import urllib.parse,sys; print(urllib.parse.quote(sys.argv[1]))" "$FOOD") +ENCODED=$(python -c "import urllib.parse,sys; print(urllib.parse.quote(sys.argv[1]))" "$FOOD") curl -s "https://api.nal.usda.gov/fdc/v1/foods/search?api_key=${API_KEY}&query=${ENCODED}&pageSize=5&dataType=Foundation,SR%20Legacy" \ - | python3 -c " + | python -c " import json,sys data=json.load(sys.stdin) foods=data.get('foods',[]) @@ -195,7 +195,7 @@ for f in foods: FDC_ID="$1" API_KEY="${USDA_API_KEY:-DEMO_KEY}" curl -s "https://api.nal.usda.gov/fdc/v1/food/${FDC_ID}?api_key=${API_KEY}" \ - | python3 -c " + | python -c " import json,sys d=json.load(sys.stdin) print(f\"Food: {d.get('description','N/A')}\") @@ -213,11 +213,11 @@ for x in sorted(d.get('foodNutrients',[]),key=lambda x:x.get('nutrient',{}).get( Use the helper scripts in `scripts/` for batch operations, or run inline for single calculations: -- `python3 scripts/body_calc.py bmi ` -- `python3 scripts/body_calc.py tdee ` -- `python3 scripts/body_calc.py 1rm ` -- `python3 scripts/body_calc.py macros ` -- `python3 scripts/body_calc.py bodyfat [hip_cm] ` +- `python scripts/body_calc.py bmi ` +- `python scripts/body_calc.py tdee ` +- `python scripts/body_calc.py 1rm ` +- `python scripts/body_calc.py macros ` +- `python scripts/body_calc.py bodyfat [hip_cm] ` See `references/FORMULAS.md` for the science behind each formula. @@ -256,4 +256,4 @@ After calculators: sanity-check outputs (e.g. TDEE should be 1500-3500 for most | List muscles | wger | `GET /api/v2/muscle/` | | Search foods | USDA | `GET /fdc/v1/foods/search?query=&dataType=Foundation,SR Legacy` | | Food details | USDA | `GET /fdc/v1/food/{fdcId}` | -| BMI / TDEE / 1RM / macros | offline | `python3 scripts/body_calc.py` | +| BMI / TDEE / 1RM / macros | offline | `python scripts/body_calc.py` | diff --git a/website/docs/user-guide/skills/optional/health/health-neuroskill-bci.md b/website/docs/user-guide/skills/optional/health/health-neuroskill-bci.md index d011ca4455..1f381393d9 100644 --- a/website/docs/user-guide/skills/optional/health/health-neuroskill-bci.md +++ b/website/docs/user-guide/skills/optional/health/health-neuroskill-bci.md @@ -15,7 +15,7 @@ Use live BCI cognitive and mood state from NeuroSkill. | | | |---|---| | Source | Optional — install with `hermes skills install official/health/neuroskill-bci` | -| Path | `optional-skills/health/neuroskill-bci` | +| Path | `optional-skills/health\neuroskill-bci` | | Version | `1.0.0` | | Author | Hermes Agent + Nous Research | | License | MIT | diff --git a/website/docs/user-guide/skills/optional/mcp/mcp-fastmcp.md b/website/docs/user-guide/skills/optional/mcp/mcp-fastmcp.md index 8012434d42..2665417067 100644 --- a/website/docs/user-guide/skills/optional/mcp/mcp-fastmcp.md +++ b/website/docs/user-guide/skills/optional/mcp/mcp-fastmcp.md @@ -15,7 +15,7 @@ Build, test, and deploy Python MCP servers. | | | |---|---| | Source | Optional — install with `hermes skills install official/mcp/fastmcp` | -| Path | `optional-skills/mcp/fastmcp` | +| Path | `optional-skills/mcp\fastmcp` | | Version | `1.0.0` | | Author | Hermes Agent | | License | MIT | diff --git a/website/docs/user-guide/skills/optional/mcp/mcp-mcp-oauth-remote-gateway.md b/website/docs/user-guide/skills/optional/mcp/mcp-mcp-oauth-remote-gateway.md index 935382b96f..6e43ce44d1 100644 --- a/website/docs/user-guide/skills/optional/mcp/mcp-mcp-oauth-remote-gateway.md +++ b/website/docs/user-guide/skills/optional/mcp/mcp-mcp-oauth-remote-gateway.md @@ -15,7 +15,7 @@ Manual OAuth for remote MCP servers on headless gateways. | | | |---|---| | Source | Optional — install with `hermes skills install official/mcp/mcp-oauth-remote-gateway` | -| Path | `optional-skills/mcp/mcp-oauth-remote-gateway` | +| Path | `optional-skills/mcp\mcp-oauth-remote-gateway` | | Version | `1.0.0` | | Author | Ben Barclay (benbarclay), Hermes Agent | | License | MIT | diff --git a/website/docs/user-guide/skills/optional/mcp/mcp-mcporter.md b/website/docs/user-guide/skills/optional/mcp/mcp-mcporter.md index 0bc09c9a4f..cf48fc4297 100644 --- a/website/docs/user-guide/skills/optional/mcp/mcp-mcporter.md +++ b/website/docs/user-guide/skills/optional/mcp/mcp-mcporter.md @@ -15,7 +15,7 @@ List, auth, and call MCP servers/tools from the terminal. | | | |---|---| | Source | Optional — install with `hermes skills install official/mcp/mcporter` | -| Path | `optional-skills/mcp/mcporter` | +| Path | `optional-skills/mcp\mcporter` | | Version | `1.0.0` | | Author | community | | License | MIT | diff --git a/website/docs/user-guide/skills/optional/migration/migration-openclaw-migration.md b/website/docs/user-guide/skills/optional/migration/migration-openclaw-migration.md index f2e9fba4e7..43519fcac5 100644 --- a/website/docs/user-guide/skills/optional/migration/migration-openclaw-migration.md +++ b/website/docs/user-guide/skills/optional/migration/migration-openclaw-migration.md @@ -15,7 +15,7 @@ Import an OpenClaw setup (memories, skills) into Hermes. | | | |---|---| | Source | Optional — install with `hermes skills install official/migration/openclaw-migration` | -| Path | `optional-skills/migration/openclaw-migration` | +| Path | `optional-skills/migration\openclaw-migration` | | Version | `1.0.0` | | Author | Hermes Agent (Nous Research) | | License | MIT | @@ -247,37 +247,37 @@ The helper script still supports category-level `--include` / `--exclude`, but t Dry run with full discovery: ```bash -python3 ~/.hermes/skills/migration/openclaw-migration/scripts/openclaw_to_hermes.py +python ~/.hermes/skills/migration/openclaw-migration/scripts/openclaw_to_hermes.py ``` When using the terminal tool, prefer an absolute invocation pattern such as: ```json -{"command":"python3 /home/USER/.hermes/skills/migration/openclaw-migration/scripts/openclaw_to_hermes.py","workdir":"/home/USER"} +{"command":"python /home/USER/.hermes/skills/migration/openclaw-migration/scripts/openclaw_to_hermes.py","workdir":"/home/USER"} ``` Dry run with the user-data preset: ```bash -python3 ~/.hermes/skills/migration/openclaw-migration/scripts/openclaw_to_hermes.py --preset user-data +python ~/.hermes/skills/migration/openclaw-migration/scripts/openclaw_to_hermes.py --preset user-data ``` Execute a user-data migration: ```bash -python3 ~/.hermes/skills/migration/openclaw-migration/scripts/openclaw_to_hermes.py --execute --preset user-data --skill-conflict skip +python ~/.hermes/skills/migration/openclaw-migration/scripts/openclaw_to_hermes.py --execute --preset user-data --skill-conflict skip ``` Execute a full compatible migration: ```bash -python3 ~/.hermes/skills/migration/openclaw-migration/scripts/openclaw_to_hermes.py --execute --preset full --migrate-secrets --skill-conflict skip +python ~/.hermes/skills/migration/openclaw-migration/scripts/openclaw_to_hermes.py --execute --preset full --migrate-secrets --skill-conflict skip ``` Execute with workspace instructions included: ```bash -python3 ~/.hermes/skills/migration/openclaw-migration/scripts/openclaw_to_hermes.py --execute --preset user-data --skill-conflict rename --workspace-target "/absolute/workspace/path" +python ~/.hermes/skills/migration/openclaw-migration/scripts/openclaw_to_hermes.py --execute --preset user-data --skill-conflict rename --workspace-target "/absolute/workspace/path" ``` Do not use `$PWD` or the home directory as the workspace target by default. Ask for an explicit workspace path first. diff --git a/website/docs/user-guide/skills/optional/mlops/mlops-accelerate.md b/website/docs/user-guide/skills/optional/mlops/mlops-accelerate.md index ef74ff473a..13745edf3e 100644 --- a/website/docs/user-guide/skills/optional/mlops/mlops-accelerate.md +++ b/website/docs/user-guide/skills/optional/mlops/mlops-accelerate.md @@ -15,7 +15,7 @@ Run PyTorch training across GPUs with minimal changes. | | | |---|---| | Source | Optional — install with `hermes skills install official/mlops/accelerate` | -| Path | `optional-skills/mlops/accelerate` | +| Path | `optional-skills/mlops\accelerate` | | Version | `1.0.1` | | Author | Orchestra Research | | License | MIT | @@ -335,11 +335,11 @@ set_seed(42) ## Advanced topics -**Megatron integration**: See [references/megatron-integration.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops/accelerate/references/megatron-integration.md) for tensor parallelism, pipeline parallelism, and sequence parallelism setup. +**Megatron integration**: See [references/megatron-integration.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops\accelerate/references/megatron-integration.md) for tensor parallelism, pipeline parallelism, and sequence parallelism setup. -**Custom plugins**: See [references/custom-plugins.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops/accelerate/references/custom-plugins.md) for creating custom distributed plugins and advanced configuration. +**Custom plugins**: See [references/custom-plugins.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops\accelerate/references/custom-plugins.md) for creating custom distributed plugins and advanced configuration. -**Performance tuning**: See [references/performance.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops/accelerate/references/performance.md) for profiling, memory optimization, and best practices. +**Performance tuning**: See [references/performance.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops\accelerate/references/performance.md) for profiling, memory optimization, and best practices. ## Hardware requirements diff --git a/website/docs/user-guide/skills/optional/mlops/mlops-chroma.md b/website/docs/user-guide/skills/optional/mlops/mlops-chroma.md index 1dafc4cc54..0feb394e00 100644 --- a/website/docs/user-guide/skills/optional/mlops/mlops-chroma.md +++ b/website/docs/user-guide/skills/optional/mlops/mlops-chroma.md @@ -15,7 +15,7 @@ Embedding database for RAG and semantic search. | | | |---|---| | Source | Optional — install with `hermes skills install official/mlops/chroma` | -| Path | `optional-skills/mlops/chroma` | +| Path | `optional-skills/mlops\chroma` | | Version | `1.0.0` | | Author | Orchestra Research | | License | MIT | diff --git a/website/docs/user-guide/skills/optional/mlops/mlops-clip.md b/website/docs/user-guide/skills/optional/mlops/mlops-clip.md index e9266e443b..d0fded797e 100644 --- a/website/docs/user-guide/skills/optional/mlops/mlops-clip.md +++ b/website/docs/user-guide/skills/optional/mlops/mlops-clip.md @@ -15,7 +15,7 @@ Zero-shot image classification and image-text search. | | | |---|---| | Source | Optional — install with `hermes skills install official/mlops/clip` | -| Path | `optional-skills/mlops/clip` | +| Path | `optional-skills/mlops\clip` | | Version | `1.0.0` | | Author | Orchestra Research | | License | MIT | diff --git a/website/docs/user-guide/skills/optional/mlops/mlops-evaluation-evaluating-llms-harness.md b/website/docs/user-guide/skills/optional/mlops/mlops-evaluation-evaluating-llms-harness.md new file mode 100644 index 0000000000..8d449ee126 --- /dev/null +++ b/website/docs/user-guide/skills/optional/mlops/mlops-evaluation-evaluating-llms-harness.md @@ -0,0 +1,512 @@ +--- +title: "Evaluating Llms Harness — lm-eval-harness: benchmark LLMs (MMLU, GSM8K, etc.)" +sidebar_label: "Evaluating Llms Harness" +description: "lm-eval-harness: benchmark LLMs (MMLU, GSM8K, etc.)" +--- + +{/* 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. */} + +# Evaluating Llms Harness + +lm-eval-harness: benchmark LLMs (MMLU, GSM8K, etc.). + +## Skill metadata + +| | | +|---|---| +| Source | Optional — install with `hermes skills install official/mlops/evaluating-llms-harness` | +| Path | `optional-skills/mlops\evaluation\evaluating-llms-harness` | +| Version | `1.0.1` | +| Author | Orchestra Research | +| License | MIT | +| Dependencies | `lm-eval`, `transformers`, `vllm` | +| Platforms | linux, macos | +| Tags | `Evaluation`, `LM Evaluation Harness`, `Benchmarking`, `MMLU`, `HumanEval`, `GSM8K`, `EleutherAI`, `Model Quality`, `Academic Benchmarks`, `Industry Standard` | + +## 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. +::: + +# lm-evaluation-harness - LLM Benchmarking + +## What's inside + +Evaluates LLMs across 60+ academic benchmarks (MMLU, HumanEval, GSM8K, TruthfulQA, HellaSwag). Use when benchmarking model quality, comparing models, reporting academic results, or tracking training progress. Industry standard used by EleutherAI, HuggingFace, and major labs. Supports HuggingFace, vLLM, APIs. + +## Quick start + +lm-evaluation-harness evaluates LLMs across 60+ academic benchmarks using standardized prompts and metrics. + +**Installation**: +```bash +pip install lm-eval +``` + +**Evaluate any HuggingFace model**: +```bash +lm_eval --model hf \ + --model_args pretrained=meta-llama/Llama-2-7b-hf \ + --tasks mmlu,gsm8k,hellaswag \ + --device cuda:0 \ + --batch_size 8 +``` + +**View available tasks**: +```bash +lm-eval ls tasks +``` + +## Common workflows + +### Workflow 1: Standard benchmark evaluation + +Evaluate model on core benchmarks (MMLU, GSM8K, HumanEval). + +Copy this checklist: + +``` +Benchmark Evaluation: +- [ ] Step 1: Choose benchmark suite +- [ ] Step 2: Configure model +- [ ] Step 3: Run evaluation +- [ ] Step 4: Analyze results +``` + +**Step 1: Choose benchmark suite** + +**Core reasoning benchmarks**: +- **MMLU** (Massive Multitask Language Understanding) - 57 subjects, multiple choice +- **GSM8K** - Grade school math word problems +- **HellaSwag** - Common sense reasoning +- **TruthfulQA** - Truthfulness and factuality +- **ARC** (AI2 Reasoning Challenge) - Science questions + +**Code benchmarks**: +- **HumanEval** - Python code generation (164 problems) +- **MBPP** (Mostly Basic Python Problems) - Python coding + +**Standard suite** (recommended for model releases): +```bash +--tasks mmlu,gsm8k,hellaswag,truthfulqa,arc_challenge +``` + +**Step 2: Configure model** + +**HuggingFace model**: +```bash +lm_eval --model hf \ + --model_args pretrained=meta-llama/Llama-2-7b-hf,dtype=bfloat16 \ + --tasks mmlu \ + --device cuda:0 \ + --batch_size auto # Auto-detect optimal batch size +``` + +**Quantized model (4-bit/8-bit)**: +```bash +lm_eval --model hf \ + --model_args pretrained=meta-llama/Llama-2-7b-hf,load_in_4bit=True \ + --tasks mmlu \ + --device cuda:0 +``` + +**Custom checkpoint**: +```bash +lm_eval --model hf \ + --model_args pretrained=/path/to/my-model,tokenizer=/path/to/tokenizer \ + --tasks mmlu \ + --device cuda:0 +``` + +**Step 3: Run evaluation** + +```bash +# Full MMLU evaluation (57 subjects) +lm_eval --model hf \ + --model_args pretrained=meta-llama/Llama-2-7b-hf \ + --tasks mmlu \ + --num_fewshot 5 \ # 5-shot evaluation (standard) + --batch_size 8 \ + --output_path results/ \ + --log_samples # Save individual predictions + +# Multiple benchmarks at once +lm_eval --model hf \ + --model_args pretrained=meta-llama/Llama-2-7b-hf \ + --tasks mmlu,gsm8k,hellaswag,truthfulqa,arc_challenge \ + --num_fewshot 5 \ + --batch_size 8 \ + --output_path results/llama2-7b-eval.json +``` + +**Step 4: Analyze results** + +Results saved to `results/llama2-7b-eval.json`: + +```json +{ + "results": { + "mmlu": { + "acc": 0.459, + "acc_stderr": 0.004 + }, + "gsm8k": { + "exact_match": 0.142, + "exact_match_stderr": 0.006 + }, + "hellaswag": { + "acc_norm": 0.765, + "acc_norm_stderr": 0.004 + } + }, + "config": { + "model": "hf", + "model_args": "pretrained=meta-llama/Llama-2-7b-hf", + "num_fewshot": 5 + } +} +``` + +### Workflow 2: Track training progress + +Evaluate checkpoints during training. + +``` +Training Progress Tracking: +- [ ] Step 1: Set up periodic evaluation +- [ ] Step 2: Choose quick benchmarks +- [ ] Step 3: Automate evaluation +- [ ] Step 4: Plot learning curves +``` + +**Step 1: Set up periodic evaluation** + +Evaluate every N training steps: + +```bash +#!/bin/bash +# eval_checkpoint.sh + +CHECKPOINT_DIR=$1 +STEP=$2 + +lm_eval --model hf \ + --model_args pretrained=$CHECKPOINT_DIR/checkpoint-$STEP \ + --tasks gsm8k,hellaswag \ + --num_fewshot 0 \ # 0-shot for speed + --batch_size 16 \ + --output_path results/step-$STEP.json +``` + +**Step 2: Choose quick benchmarks** + +Fast benchmarks for frequent evaluation: +- **HellaSwag**: ~10 minutes on 1 GPU +- **GSM8K**: ~5 minutes +- **PIQA**: ~2 minutes + +Avoid for frequent eval (too slow): +- **MMLU**: ~2 hours (57 subjects) +- **HumanEval**: Requires code execution + +**Step 3: Automate evaluation** + +Integrate with training script: + +```python +# In training loop +if step % eval_interval == 0: + model.save_pretrained(f"checkpoints/step-{step}") + + # Run evaluation + os.system(f"./eval_checkpoint.sh checkpoints step-{step}") +``` + +Or use PyTorch Lightning callbacks: + +```python +from pytorch_lightning import Callback + +class EvalHarnessCallback(Callback): + def on_validation_epoch_end(self, trainer, pl_module): + step = trainer.global_step + checkpoint_path = f"checkpoints/step-{step}" + + # Save checkpoint + trainer.save_checkpoint(checkpoint_path) + + # Run lm-eval + os.system(f"lm_eval --model hf --model_args pretrained={checkpoint_path} ...") +``` + +**Step 4: Plot learning curves** + +```python +import json +import matplotlib.pyplot as plt + +# Load all results +steps = [] +mmlu_scores = [] + +for file in sorted(glob.glob("results/step-*.json")): + with open(file) as f: + data = json.load(f) + step = int(file.split("-")[1].split(".")[0]) + steps.append(step) + mmlu_scores.append(data["results"]["mmlu"]["acc"]) + +# Plot +plt.plot(steps, mmlu_scores) +plt.xlabel("Training Step") +plt.ylabel("MMLU Accuracy") +plt.title("Training Progress") +plt.savefig("training_curve.png") +``` + +### Workflow 3: Compare multiple models + +Benchmark suite for model comparison. + +``` +Model Comparison: +- [ ] Step 1: Define model list +- [ ] Step 2: Run evaluations +- [ ] Step 3: Generate comparison table +``` + +**Step 1: Define model list** + +```bash +# models.txt +meta-llama/Llama-2-7b-hf +meta-llama/Llama-2-13b-hf +mistralai/Mistral-7B-v0.1 +microsoft/phi-2 +``` + +**Step 2: Run evaluations** + +```bash +#!/bin/bash +# eval_all_models.sh + +TASKS="mmlu,gsm8k,hellaswag,truthfulqa" + +while read model; do + echo "Evaluating $model" + + # Extract model name for output file + model_name=$(echo $model | sed 's/\//-/g') + + lm_eval --model hf \ + --model_args pretrained=$model,dtype=bfloat16 \ + --tasks $TASKS \ + --num_fewshot 5 \ + --batch_size auto \ + --output_path results/$model_name.json + +done < models.txt +``` + +**Step 3: Generate comparison table** + +```python +import json +import pandas as pd + +models = [ + "meta-llama-Llama-2-7b-hf", + "meta-llama-Llama-2-13b-hf", + "mistralai-Mistral-7B-v0.1", + "microsoft-phi-2" +] + +tasks = ["mmlu", "gsm8k", "hellaswag", "truthfulqa"] + +results = [] +for model in models: + with open(f"results/{model}.json") as f: + data = json.load(f) + row = {"Model": model.replace("-", "/")} + for task in tasks: + # Get primary metric for each task + metrics = data["results"][task] + if "acc" in metrics: + row[task.upper()] = f"{metrics['acc']:.3f}" + elif "exact_match" in metrics: + row[task.upper()] = f"{metrics['exact_match']:.3f}" + results.append(row) + +df = pd.DataFrame(results) +print(df.to_markdown(index=False)) +``` + +Output: +``` +| Model | MMLU | GSM8K | HELLASWAG | TRUTHFULQA | +|------------------------|-------|-------|-----------|------------| +| meta-llama/Llama-2-7b | 0.459 | 0.142 | 0.765 | 0.391 | +| meta-llama/Llama-2-13b | 0.549 | 0.287 | 0.801 | 0.430 | +| mistralai/Mistral-7B | 0.626 | 0.395 | 0.812 | 0.428 | +| microsoft/phi-2 | 0.560 | 0.613 | 0.682 | 0.447 | +``` + +### Workflow 4: Evaluate with vLLM (faster inference) + +Use vLLM backend for 5-10x faster evaluation. + +``` +vLLM Evaluation: +- [ ] Step 1: Install vLLM +- [ ] Step 2: Configure vLLM backend +- [ ] Step 3: Run evaluation +``` + +**Step 1: Install vLLM** + +```bash +pip install vllm +``` + +**Step 2: Configure vLLM backend** + +```bash +lm_eval --model vllm \ + --model_args pretrained=meta-llama/Llama-2-7b-hf,tensor_parallel_size=1,dtype=auto,gpu_memory_utilization=0.8 \ + --tasks mmlu \ + --batch_size auto +``` + +**Step 3: Run evaluation** + +vLLM is 5-10× faster than standard HuggingFace: + +```bash +# Standard HF: ~2 hours for MMLU on 7B model +lm_eval --model hf \ + --model_args pretrained=meta-llama/Llama-2-7b-hf \ + --tasks mmlu \ + --batch_size 8 + +# vLLM: ~15-20 minutes for MMLU on 7B model +lm_eval --model vllm \ + --model_args pretrained=meta-llama/Llama-2-7b-hf,tensor_parallel_size=2 \ + --tasks mmlu \ + --batch_size auto +``` + +## When to use vs alternatives + +**Use lm-evaluation-harness when:** +- Benchmarking models for academic papers +- Comparing model quality across standard tasks +- Tracking training progress +- Reporting standardized metrics (everyone uses same prompts) +- Need reproducible evaluation + +**Use alternatives instead:** +- **HELM** (Stanford): Broader evaluation (fairness, efficiency, calibration) +- **AlpacaEval**: Instruction-following evaluation with LLM judges +- **MT-Bench**: Conversational multi-turn evaluation +- **Custom scripts**: Domain-specific evaluation + +## Common issues + +**Issue: Evaluation too slow** + +Use vLLM backend: +```bash +lm_eval --model vllm \ + --model_args pretrained=model-name,tensor_parallel_size=2 +``` + +Or reduce fewshot examples: +```bash +--num_fewshot 0 # Instead of 5 +``` + +Or evaluate subset of MMLU: +```bash +--tasks mmlu_stem # Only STEM subjects +``` + +**Issue: Out of memory** + +Reduce batch size: +```bash +--batch_size 1 # Or --batch_size auto +``` + +Use quantization: +```bash +--model_args pretrained=model-name,load_in_8bit=True +``` + +Enable CPU offloading: +```bash +--model_args pretrained=model-name,device_map=auto,offload_folder=offload +``` + +**Issue: Different results than reported** + +Check fewshot count: +```bash +--num_fewshot 5 # Most papers use 5-shot +``` + +Check exact task name: +```bash +--tasks mmlu # Not mmlu_direct or mmlu_fewshot +``` + +Verify model and tokenizer match: +```bash +--model_args pretrained=model-name,tokenizer=same-model-name +``` + +**Issue: HumanEval not executing code** + +Code-executing tasks (HumanEval, MBPP, etc.) are gated behind an explicit +confirmation flag — you must pass `--confirm_run_unsafe_code` to run them: + +```bash +lm_eval --model hf \ + --model_args pretrained=model-name \ + --tasks humaneval \ + --confirm_run_unsafe_code # Required to run tasks that execute generated code +``` + +Without this flag lm-eval refuses to run the task rather than silently skipping +code execution. + +## Advanced topics + +**Benchmark descriptions**: See [references/benchmark-guide.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops\evaluation\evaluating-llms-harness/references/benchmark-guide.md) for detailed description of all 60+ tasks, what they measure, and interpretation. + +**Custom tasks**: See [references/custom-tasks.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops\evaluation\evaluating-llms-harness/references/custom-tasks.md) for creating domain-specific evaluation tasks. + +**API evaluation**: See [references/api-evaluation.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops\evaluation\evaluating-llms-harness/references/api-evaluation.md) for evaluating OpenAI, Anthropic, and other API models. + +**Multi-GPU strategies**: See [references/distributed-eval.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops\evaluation\evaluating-llms-harness/references/distributed-eval.md) for data parallel and tensor parallel evaluation. + +## Hardware requirements + +- **GPU**: NVIDIA (CUDA 11.8+), works on CPU (very slow) +- **VRAM**: + - 7B model: 16GB (bf16) or 8GB (8-bit) + - 13B model: 28GB (bf16) or 14GB (8-bit) + - 70B model: Requires multi-GPU or quantization +- **Time** (7B model, single A100): + - HellaSwag: 10 minutes + - GSM8K: 5 minutes + - MMLU (full): 2 hours + - HumanEval: 20 minutes + +## Resources + +- GitHub: https://github.com/EleutherAI/lm-evaluation-harness +- Docs: https://github.com/EleutherAI/lm-evaluation-harness/tree/main/docs +- Task library: 60+ tasks including MMLU, GSM8K, HumanEval, TruthfulQA, HellaSwag, ARC, WinoGrande, etc. +- Leaderboard: https://huggingface.co/spaces/HuggingFaceH4/open_llm_leaderboard (uses this harness) diff --git a/website/docs/user-guide/skills/optional/mlops/mlops-evaluation-weights-and-biases.md b/website/docs/user-guide/skills/optional/mlops/mlops-evaluation-weights-and-biases.md new file mode 100644 index 0000000000..25b9a23ead --- /dev/null +++ b/website/docs/user-guide/skills/optional/mlops/mlops-evaluation-weights-and-biases.md @@ -0,0 +1,613 @@ +--- +title: "Weights And Biases — W&B: log ML experiments, sweeps, model registry, dashboards" +sidebar_label: "Weights And Biases" +description: "W&B: log ML experiments, sweeps, model registry, dashboards" +--- + +{/* 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. */} + +# Weights And Biases + +W&B: log ML experiments, sweeps, model registry, dashboards. + +## Skill metadata + +| | | +|---|---| +| Source | Optional — install with `hermes skills install official/mlops/weights-and-biases` | +| Path | `optional-skills/mlops\evaluation\weights-and-biases` | +| Version | `1.0.1` | +| Author | Orchestra Research | +| License | MIT | +| Dependencies | `wandb` | +| Platforms | linux, macos, windows | +| Tags | `MLOps`, `Weights And Biases`, `WandB`, `Experiment Tracking`, `Hyperparameter Tuning`, `Model Registry`, `Collaboration`, `Real-Time Visualization`, `PyTorch`, `TensorFlow`, `HuggingFace` | + +## 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. +::: + +# Weights & Biases: ML Experiment Tracking & MLOps + +## When to Use This Skill + +Use Weights & Biases (W&B) when you need to: +- **Track ML experiments** with automatic metric logging +- **Visualize training** in real-time dashboards +- **Compare runs** across hyperparameters and configurations +- **Optimize hyperparameters** with automated sweeps +- **Manage model registry** with versioning and lineage +- **Collaborate on ML projects** with team workspaces +- **Track artifacts** (datasets, models, code) with lineage + +**Users**: 200,000+ ML practitioners | **GitHub Stars**: 10.5k+ | **Integrations**: 100+ + +## Installation + +```bash +# Install W&B +pip install wandb + +# Login (creates API key) +wandb login + +# Or set API key programmatically +export WANDB_API_KEY=your_api_key_here +``` + +## Quick Start + +### Basic Experiment Tracking + +```python +import wandb + +# Initialize a run +run = wandb.init( + project="my-project", + config={ + "learning_rate": 0.001, + "epochs": 10, + "batch_size": 32, + "architecture": "ResNet50" + } +) + +# Training loop +for epoch in range(run.config.epochs): + # Your training code + train_loss = train_epoch() + val_loss = validate() + + # Log metrics + wandb.log({ + "epoch": epoch, + "train/loss": train_loss, + "val/loss": val_loss, + "train/accuracy": train_acc, + "val/accuracy": val_acc + }) + +# Finish the run +wandb.finish() +``` + +### With PyTorch + +```python +import torch +import wandb + +# Initialize +wandb.init(project="pytorch-demo", config={ + "lr": 0.001, + "epochs": 10 +}) + +# Access config +config = wandb.config + +# Training loop +for epoch in range(config.epochs): + for batch_idx, (data, target) in enumerate(train_loader): + # Forward pass + output = model(data) + loss = criterion(output, target) + + # Backward pass + optimizer.zero_grad() + loss.backward() + optimizer.step() + + # Log every 100 batches + if batch_idx % 100 == 0: + wandb.log({ + "loss": loss.item(), + "epoch": epoch, + "batch": batch_idx + }) + +# Save model +torch.save(model.state_dict(), "model.pth") +wandb.save("model.pth") # Upload to W&B + +wandb.finish() +``` + +## Core Concepts + +### 1. Projects and Runs + +**Project**: Collection of related experiments +**Run**: Single execution of your training script + +```python +# Create/use project +run = wandb.init( + project="image-classification", + name="resnet50-experiment-1", # Optional run name + tags=["baseline", "resnet"], # Organize with tags + notes="First baseline run" # Add notes +) + +# Each run has unique ID +print(f"Run ID: {run.id}") +print(f"Run URL: {run.url}") +``` + +### 2. Configuration Tracking + +Track hyperparameters automatically: + +```python +config = { + # Model architecture + "model": "ResNet50", + "pretrained": True, + + # Training params + "learning_rate": 0.001, + "batch_size": 32, + "epochs": 50, + "optimizer": "Adam", + + # Data params + "dataset": "ImageNet", + "augmentation": "standard" +} + +wandb.init(project="my-project", config=config) + +# Access config during training +lr = wandb.config.learning_rate +batch_size = wandb.config.batch_size +``` + +### 3. Metric Logging + +```python +# Log scalars +wandb.log({"loss": 0.5, "accuracy": 0.92}) + +# Log multiple metrics +wandb.log({ + "train/loss": train_loss, + "train/accuracy": train_acc, + "val/loss": val_loss, + "val/accuracy": val_acc, + "learning_rate": current_lr, + "epoch": epoch +}) + +# Log with custom x-axis +wandb.log({"loss": loss}, step=global_step) + +# Log media (images, audio, video) +wandb.log({"examples": [wandb.Image(img) for img in images]}) + +# Log histograms +wandb.log({"gradients": wandb.Histogram(gradients)}) + +# Log tables +table = wandb.Table(columns=["id", "prediction", "ground_truth"]) +wandb.log({"predictions": table}) +``` + +### 4. Model Checkpointing + +```python +import torch +import wandb + +# Save model checkpoint +checkpoint = { + 'epoch': epoch, + 'model_state_dict': model.state_dict(), + 'optimizer_state_dict': optimizer.state_dict(), + 'loss': loss, +} + +torch.save(checkpoint, 'checkpoint.pth') + +# Upload to W&B +wandb.save('checkpoint.pth') + +# Or use Artifacts (recommended) +artifact = wandb.Artifact('model', type='model') +artifact.add_file('checkpoint.pth') +wandb.log_artifact(artifact) +``` + +## Hyperparameter Sweeps + +Automatically search for optimal hyperparameters. + +### Define Sweep Configuration + +```python +sweep_config = { + 'method': 'bayes', # or 'grid', 'random' + 'metric': { + 'name': 'val/accuracy', + 'goal': 'maximize' + }, + 'parameters': { + 'learning_rate': { + 'distribution': 'log_uniform_values', + 'min': 1e-5, + 'max': 1e-1 + }, + 'batch_size': { + 'values': [16, 32, 64, 128] + }, + 'optimizer': { + 'values': ['adam', 'sgd', 'rmsprop'] + }, + 'dropout': { + 'distribution': 'uniform', + 'min': 0.1, + 'max': 0.5 + } + } +} + +# Initialize sweep +sweep_id = wandb.sweep(sweep_config, project="my-project") +``` + +### Define Training Function + +```python +def train(): + # Initialize run + run = wandb.init() + + # Access sweep parameters + lr = wandb.config.learning_rate + batch_size = wandb.config.batch_size + optimizer_name = wandb.config.optimizer + + # Build model with sweep config + model = build_model(wandb.config) + optimizer = get_optimizer(optimizer_name, lr) + + # Training loop + for epoch in range(NUM_EPOCHS): + train_loss = train_epoch(model, optimizer, batch_size) + val_acc = validate(model) + + # Log metrics + wandb.log({ + "train/loss": train_loss, + "val/accuracy": val_acc + }) + +# Run sweep +wandb.agent(sweep_id, function=train, count=50) # Run 50 trials +``` + +### Sweep Strategies + +```python +# Grid search - exhaustive +sweep_config = { + 'method': 'grid', + 'parameters': { + 'lr': {'values': [0.001, 0.01, 0.1]}, + 'batch_size': {'values': [16, 32, 64]} + } +} + +# Random search +sweep_config = { + 'method': 'random', + 'parameters': { + 'lr': {'distribution': 'uniform', 'min': 0.0001, 'max': 0.1}, + 'dropout': {'distribution': 'uniform', 'min': 0.1, 'max': 0.5} + } +} + +# Bayesian optimization (recommended) +sweep_config = { + 'method': 'bayes', + 'metric': {'name': 'val/loss', 'goal': 'minimize'}, + 'parameters': { + 'lr': {'distribution': 'log_uniform_values', 'min': 1e-5, 'max': 1e-1} + } +} +``` + +## Artifacts + +Track datasets, models, and other files with lineage. + +### Log Artifacts + +```python +# Create artifact +artifact = wandb.Artifact( + name='training-dataset', + type='dataset', + description='ImageNet training split', + metadata={'size': '1.2M images', 'split': 'train'} +) + +# Add files +artifact.add_file('data/train.csv') +artifact.add_dir('data/images/') + +# Log artifact +wandb.log_artifact(artifact) +``` + +### Use Artifacts + +```python +# Download and use artifact +run = wandb.init(project="my-project") + +# Download artifact +artifact = run.use_artifact('training-dataset:latest') +artifact_dir = artifact.download() + +# Use the data +data = load_data(f"{artifact_dir}/train.csv") +``` + +### Model Registry + +```python +# Log model as artifact +model_artifact = wandb.Artifact( + name='resnet50-model', + type='model', + metadata={'architecture': 'ResNet50', 'accuracy': 0.95} +) + +model_artifact.add_file('model.pth') +wandb.log_artifact(model_artifact, aliases=['best', 'production']) + +# Link to model registry +run.link_artifact(model_artifact, 'model-registry/production-models') +``` + +## Integration Examples + +### HuggingFace Transformers + +```python +from transformers import Trainer, TrainingArguments +import wandb + +# Initialize W&B +wandb.init(project="hf-transformers") + +# Training arguments with W&B +training_args = TrainingArguments( + output_dir="./results", + report_to="wandb", # Enable W&B logging + run_name="bert-finetuning", + logging_steps=100, + save_steps=500 +) + +# Trainer automatically logs to W&B +trainer = Trainer( + model=model, + args=training_args, + train_dataset=train_dataset, + eval_dataset=eval_dataset +) + +trainer.train() +``` + +### PyTorch Lightning + +```python +from pytorch_lightning import Trainer +from pytorch_lightning.loggers import WandbLogger +import wandb + +# Create W&B logger +wandb_logger = WandbLogger( + project="lightning-demo", + log_model=True # Log model checkpoints +) + +# Use with Trainer +trainer = Trainer( + logger=wandb_logger, + max_epochs=10 +) + +trainer.fit(model, datamodule=dm) +``` + +### Keras/TensorFlow + +```python +import wandb +from wandb.integration.keras import WandbMetricsLogger, WandbModelCheckpoint + +# Initialize +wandb.init(project="keras-demo") + +# Add callbacks (the monolithic WandbCallback was removed; +# use the dedicated callbacks from wandb.integration.keras instead) +model.fit( + x_train, y_train, + validation_data=(x_val, y_val), + epochs=10, + callbacks=[ + WandbMetricsLogger(), # Auto-logs metrics + WandbModelCheckpoint("models/model-{epoch}") # Saves checkpoints + ] +) +``` + +## Visualization & Analysis + +### Custom Charts + +```python +# Log custom visualizations +import matplotlib.pyplot as plt + +fig, ax = plt.subplots() +ax.plot(x, y) +wandb.log({"custom_plot": wandb.Image(fig)}) + +# Log confusion matrix +wandb.log({"conf_mat": wandb.plot.confusion_matrix( + probs=None, + y_true=ground_truth, + preds=predictions, + class_names=class_names +)}) +``` + +### Reports + +Create shareable reports in W&B UI: +- Combine runs, charts, and text +- Markdown support +- Embeddable visualizations +- Team collaboration + +## Best Practices + +### 1. Organize with Tags and Groups + +```python +wandb.init( + project="my-project", + tags=["baseline", "resnet50", "imagenet"], + group="resnet-experiments", # Group related runs + job_type="train" # Type of job +) +``` + +### 2. Log Everything Relevant + +```python +# Log system metrics +wandb.log({ + "gpu/util": gpu_utilization, + "gpu/memory": gpu_memory_used, + "cpu/util": cpu_utilization +}) + +# Log code version +wandb.log({"git_commit": git_commit_hash}) + +# Log data splits +wandb.log({ + "data/train_size": len(train_dataset), + "data/val_size": len(val_dataset) +}) +``` + +### 3. Use Descriptive Names + +```python +# ✅ Good: Descriptive run names +wandb.init( + project="nlp-classification", + name="bert-base-lr0.001-bs32-epoch10" +) + +# ❌ Bad: Generic names +wandb.init(project="nlp", name="run1") +``` + +### 4. Save Important Artifacts + +```python +# Save final model +artifact = wandb.Artifact('final-model', type='model') +artifact.add_file('model.pth') +wandb.log_artifact(artifact) + +# Save predictions for analysis +predictions_table = wandb.Table( + columns=["id", "input", "prediction", "ground_truth"], + data=predictions_data +) +wandb.log({"predictions": predictions_table}) +``` + +### 5. Use Offline Mode for Unstable Connections + +```python +import os + +# Enable offline mode +os.environ["WANDB_MODE"] = "offline" + +wandb.init(project="my-project") +# ... your code ... + +# Sync later +# wandb sync +``` + +## Team Collaboration + +### Share Runs + +```python +# Runs are automatically shareable via URL +run = wandb.init(project="team-project") +print(f"Share this URL: {run.url}") +``` + +### Team Projects + +- Create team account at wandb.ai +- Add team members +- Set project visibility (private/public) +- Use team-level artifacts and model registry + +## Pricing + +- **Free**: Unlimited public projects, 100GB storage +- **Academic**: Free for students/researchers +- **Teams**: $50/seat/month, private projects, unlimited storage +- **Enterprise**: Custom pricing, on-prem options + +## Resources + +- **Documentation**: https://docs.wandb.ai +- **GitHub**: https://github.com/wandb/wandb (10.5k+ stars) +- **Examples**: https://github.com/wandb/examples +- **Community**: https://wandb.ai/community +- **Discord**: https://wandb.me/discord + +## See Also + +- `references/sweeps.md` - Comprehensive hyperparameter optimization guide +- `references/artifacts.md` - Data and model versioning patterns +- `references/integrations.md` - Framework-specific examples diff --git a/website/docs/user-guide/skills/optional/mlops/mlops-faiss.md b/website/docs/user-guide/skills/optional/mlops/mlops-faiss.md index e83bc5a59b..a082372372 100644 --- a/website/docs/user-guide/skills/optional/mlops/mlops-faiss.md +++ b/website/docs/user-guide/skills/optional/mlops/mlops-faiss.md @@ -15,7 +15,7 @@ Fast vector similarity search at billion scale. | | | |---|---| | Source | Optional — install with `hermes skills install official/mlops/faiss` | -| Path | `optional-skills/mlops/faiss` | +| Path | `optional-skills/mlops\faiss` | | Version | `1.0.0` | | Author | Orchestra Research | | License | MIT | diff --git a/website/docs/user-guide/skills/optional/mlops/mlops-flash-attention.md b/website/docs/user-guide/skills/optional/mlops/mlops-flash-attention.md index 5269e41af2..52b717fee5 100644 --- a/website/docs/user-guide/skills/optional/mlops/mlops-flash-attention.md +++ b/website/docs/user-guide/skills/optional/mlops/mlops-flash-attention.md @@ -15,7 +15,7 @@ Speed up long-sequence transformer training and inference. | | | |---|---| | Source | Optional — install with `hermes skills install official/mlops/flash-attention` | -| Path | `optional-skills/mlops/flash-attention` | +| Path | `optional-skills/mlops\flash-attention` | | Version | `1.0.1` | | Author | Orchestra Research | | License | MIT | @@ -366,9 +366,9 @@ Flash Attention uses float16/bfloat16 for speed. Float32 not supported. ## Advanced topics -**Integration with HuggingFace Transformers**: See [references/transformers-integration.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops/flash-attention/references/transformers-integration.md) for enabling Flash Attention in BERT, GPT, Llama models. +**Integration with HuggingFace Transformers**: See [references/transformers-integration.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops\flash-attention/references/transformers-integration.md) for enabling Flash Attention in BERT, GPT, Llama models. -**Performance benchmarks**: See [references/benchmarks.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops/flash-attention/references/benchmarks.md) for detailed speed and memory comparisons across GPUs and sequence lengths. +**Performance benchmarks**: See [references/benchmarks.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops\flash-attention/references/benchmarks.md) for detailed speed and memory comparisons across GPUs and sequence lengths. ## Hardware requirements diff --git a/website/docs/user-guide/skills/optional/mlops/mlops-guidance.md b/website/docs/user-guide/skills/optional/mlops/mlops-guidance.md index d8f7de7512..56556cbce8 100644 --- a/website/docs/user-guide/skills/optional/mlops/mlops-guidance.md +++ b/website/docs/user-guide/skills/optional/mlops/mlops-guidance.md @@ -15,7 +15,7 @@ Constrain LLM output with grammars; guarantee valid JSON. | | | |---|---| | Source | Optional — install with `hermes skills install official/mlops/guidance` | -| Path | `optional-skills/mlops/guidance` | +| Path | `optional-skills/mlops\guidance` | | Version | `1.0.1` | | Author | Orchestra Research | | License | MIT | diff --git a/website/docs/user-guide/skills/optional/mlops/mlops-huggingface-tokenizers.md b/website/docs/user-guide/skills/optional/mlops/mlops-huggingface-tokenizers.md index 723cf707a7..b627c762ec 100644 --- a/website/docs/user-guide/skills/optional/mlops/mlops-huggingface-tokenizers.md +++ b/website/docs/user-guide/skills/optional/mlops/mlops-huggingface-tokenizers.md @@ -15,7 +15,7 @@ Fast BPE/WordPiece tokenization and custom vocab training. | | | |---|---| | Source | Optional — install with `hermes skills install official/mlops/huggingface-tokenizers` | -| Path | `optional-skills/mlops/huggingface-tokenizers` | +| Path | `optional-skills/mlops\huggingface-tokenizers` | | Version | `1.0.0` | | Author | Orchestra Research | | License | MIT | @@ -521,10 +521,10 @@ Browse all: https://huggingface.co/models?library=tokenizers ## References -- **[Training Guide](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops/huggingface-tokenizers/references/training.md)** - Train custom tokenizers, configure trainers, handle large datasets -- **[Algorithms Deep Dive](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops/huggingface-tokenizers/references/algorithms.md)** - BPE, WordPiece, Unigram explained in detail -- **[Pipeline Components](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops/huggingface-tokenizers/references/pipeline.md)** - Normalizers, pre-tokenizers, post-processors, decoders -- **[Transformers Integration](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops/huggingface-tokenizers/references/integration.md)** - AutoTokenizer, PreTrainedTokenizerFast, special tokens +- **[Training Guide](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops\huggingface-tokenizers/references/training.md)** - Train custom tokenizers, configure trainers, handle large datasets +- **[Algorithms Deep Dive](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops\huggingface-tokenizers/references/algorithms.md)** - BPE, WordPiece, Unigram explained in detail +- **[Pipeline Components](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops\huggingface-tokenizers/references/pipeline.md)** - Normalizers, pre-tokenizers, post-processors, decoders +- **[Transformers Integration](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops\huggingface-tokenizers/references/integration.md)** - AutoTokenizer, PreTrainedTokenizerFast, special tokens ## Resources diff --git a/website/docs/user-guide/skills/optional/mlops/mlops-inference-llama-cpp.md b/website/docs/user-guide/skills/optional/mlops/mlops-inference-llama-cpp.md new file mode 100644 index 0000000000..beb9091df0 --- /dev/null +++ b/website/docs/user-guide/skills/optional/mlops/mlops-inference-llama-cpp.md @@ -0,0 +1,267 @@ +--- +title: "Llama Cpp — llama.cpp local GGUF inference + HF Hub model discovery" +sidebar_label: "Llama Cpp" +description: "llama.cpp local GGUF inference + HF Hub model discovery" +--- + +{/* 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. */} + +# Llama Cpp + +llama.cpp local GGUF inference + HF Hub model discovery. + +## Skill metadata + +| | | +|---|---| +| Source | Optional — install with `hermes skills install official/mlops/llama-cpp` | +| Path | `optional-skills/mlops\inference\llama-cpp` | +| Version | `2.1.2` | +| Author | Orchestra Research | +| License | MIT | +| Dependencies | `llama-cpp-python>=0.2.0` | +| Platforms | linux, macos, windows | +| Tags | `llama.cpp`, `GGUF`, `Quantization`, `Hugging Face Hub`, `CPU Inference`, `Apple Silicon`, `Edge Deployment`, `AMD GPUs`, `Intel GPUs`, `NVIDIA`, `URL-first` | + +## 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. +::: + +# llama.cpp + GGUF + +Use this skill for local GGUF inference, quant selection, or Hugging Face repo discovery for llama.cpp. + +## When to use + +- Run local models on CPU, Apple Silicon, CUDA, ROCm, or Intel GPUs +- Find the right GGUF for a specific Hugging Face repo +- Build a `llama-server` or `llama-cli` command from the Hub +- Search the Hub for models that already support llama.cpp +- Enumerate available `.gguf` files and sizes for a repo +- Decide between Q4/Q5/Q6/IQ variants for the user's RAM or VRAM + +## Model Discovery workflow + +Prefer URL workflows before asking for `hf`, Python, or custom scripts. + +1. Search for candidate repos on the Hub: + - Base: `https://huggingface.co/models?apps=llama.cpp&sort=trending` + - Add `search=` for a model family + - Add `num_parameters=min:0,max:24B` or similar when the user has size constraints +2. Open the repo with the llama.cpp local-app view: + - `https://huggingface.co/?local-app=llama.cpp` +3. Treat the local-app snippet as the source of truth when it is visible: + - copy the exact `llama-server` or `llama-cli` command + - report the recommended quant exactly as HF shows it +4. Read the same `?local-app=llama.cpp` URL as page text or HTML and extract the section under `Hardware compatibility`: + - prefer its exact quant labels and sizes over generic tables + - keep repo-specific labels such as `UD-Q4_K_M` or `IQ4_NL_XL` + - if that section is not visible in the fetched page source, say so and fall back to the tree API plus generic quant guidance +5. Query the tree API to confirm what actually exists: + - `https://huggingface.co/api/models//tree/main?recursive=true` + - keep entries where `type` is `file` and `path` ends with `.gguf` + - use `path` and `size` as the source of truth for filenames and byte sizes + - separate quantized checkpoints from `mmproj-*.gguf` projector files and `BF16/` shard files + - use `https://huggingface.co//tree/main` only as a human fallback +6. If the local-app snippet is not text-visible, reconstruct the command from the repo plus the chosen quant: + - shorthand quant selection: `llama-server -hf :` + - exact-file fallback: `llama-server --hf-repo --hf-file ` +7. Only suggest conversion from Transformers weights if the repo does not already expose GGUF files. + +## Quick start + +### Install llama.cpp + +```bash +# macOS / Linux (simplest) +brew install llama.cpp +``` + +```bash +winget install llama.cpp +``` + +```bash +git clone https://github.com/ggml-org/llama.cpp +cd llama.cpp +cmake -B build +cmake --build build --config Release +``` + +### Run directly from the Hugging Face Hub + +```bash +llama-cli -hf bartowski/Llama-3.2-3B-Instruct-GGUF:Q8_0 +``` + +```bash +llama-server -hf bartowski/Llama-3.2-3B-Instruct-GGUF:Q8_0 +``` + +### Run an exact GGUF file from the Hub + +Use this when the tree API shows custom file naming or the exact HF snippet is missing. + +```bash +llama-server \ + --hf-repo microsoft/Phi-3-mini-4k-instruct-gguf \ + --hf-file Phi-3-mini-4k-instruct-q4.gguf \ + -c 4096 +``` + +### OpenAI-compatible server check + +```bash +curl http://localhost:8080/v1/chat/completions \ + -H "Content-Type: application/json" \ + -d '{ + "messages": [ + {"role": "user", "content": "Write a limerick about Python exceptions"} + ] + }' +``` + +## Python bindings (llama-cpp-python) + +`pip install llama-cpp-python` (CUDA: `CMAKE_ARGS="-DGGML_CUDA=on" pip install llama-cpp-python --force-reinstall --no-cache-dir`; Metal: `CMAKE_ARGS="-DGGML_METAL=on" ...`). + +### Basic generation + +```python +from llama_cpp import Llama + +llm = Llama( + model_path="./model-q4_k_m.gguf", + n_ctx=4096, + n_gpu_layers=35, # 0 for CPU, 99 to offload everything + n_threads=8, +) + +out = llm("What is machine learning?", max_tokens=256, temperature=0.7) +print(out["choices"][0]["text"]) +``` + +### Chat + streaming + +```python +llm = Llama( + model_path="./model-q4_k_m.gguf", + n_ctx=4096, + n_gpu_layers=35, + chat_format="llama-3", # or "chatml", "mistral", etc. +) + +resp = llm.create_chat_completion( + messages=[ + {"role": "system", "content": "You are a helpful assistant."}, + {"role": "user", "content": "What is Python?"}, + ], + max_tokens=256, +) +print(resp["choices"][0]["message"]["content"]) + +# Streaming +for chunk in llm("Explain quantum computing:", max_tokens=256, stream=True): + print(chunk["choices"][0]["text"], end="", flush=True) +``` + +### Embeddings + +```python +llm = Llama(model_path="./model-q4_k_m.gguf", embedding=True, n_gpu_layers=35) +vec = llm.embed("This is a test sentence.") +print(f"Embedding dimension: {len(vec)}") +``` + +You can also load a GGUF straight from the Hub: + +```python +llm = Llama.from_pretrained( + repo_id="bartowski/Llama-3.2-3B-Instruct-GGUF", + filename="*Q4_K_M.gguf", + n_gpu_layers=35, +) +``` + +## Choosing a quant + +Use the Hub page first, generic heuristics second. + +- Prefer the exact quant that HF marks as compatible for the user's hardware profile. +- For general chat, start with `Q4_K_M`. +- For code or technical work, prefer `Q5_K_M` or `Q6_K` if memory allows. +- For very tight RAM budgets, consider `Q3_K_M`, `IQ` variants, or `Q2` variants only if the user explicitly prioritizes fit over quality. +- For multimodal repos, mention `mmproj-*.gguf` separately. The projector is not the main model file. +- Do not normalize repo-native labels. If the page says `UD-Q4_K_M`, report `UD-Q4_K_M`. + +## Extracting available GGUFs from a repo + +When the user asks what GGUFs exist, return: + +- filename +- file size +- quant label +- whether it is a main model or an auxiliary projector + +Ignore unless requested: + +- README +- BF16 shard files +- imatrix blobs or calibration artifacts + +Use the tree API for this step: + +- `https://huggingface.co/api/models//tree/main?recursive=true` + +For a repo like `unsloth/Qwen3.6-35B-A3B-GGUF`, the local-app page can show quant chips such as `UD-Q4_K_M`, `UD-Q5_K_M`, `UD-Q6_K`, and `Q8_0`, while the tree API exposes exact file paths such as `Qwen3.6-35B-A3B-UD-Q4_K_M.gguf` and `Qwen3.6-35B-A3B-Q8_0.gguf` with byte sizes. Use the tree API to turn a quant label into an exact filename. + +## Search patterns + +Use these URL shapes directly: + +```text +https://huggingface.co/models?apps=llama.cpp&sort=trending +https://huggingface.co/models?search=&apps=llama.cpp&sort=trending +https://huggingface.co/models?search=&apps=llama.cpp&num_parameters=min:0,max:24B&sort=trending +https://huggingface.co/?local-app=llama.cpp +https://huggingface.co/api/models//tree/main?recursive=true +https://huggingface.co//tree/main +``` + +## Output format + +When answering discovery requests, prefer a compact structured result like: + +```text +Repo: +Recommended quant from HF: