[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7AV24SHHA4HKGEWF1F2YDN3":3,"skill-same:01M7AV24SHHA4HKGEWF1F2YDN3":54},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":33,"commitSha":34,"skillDirectory":35,"forksCount":14,"repositoryHtmlUrl":36,"repositoryHomepageUrl":6,"ownerHtmlUrl":37,"ownerBlogUrl":37,"ownerDescription":38,"updatedAt":39,"install":40,"resources":53},"01M7AV24SHHA4HKGEWF1F2YDN3","hermes-custom-provider",null,"Use when adding custom LLM providers to Hermes.","peterlau123\u002Fskills-you-need","peterlau123","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F19188200?v=4","01M7AV0Y55C30Y4E2TGRQ8X7WR","Sloth","01M7AV0Y5SNAJQ4E3FG1EEK8S4",0,"MIT","https:\u002F\u002Fgithub.com\u002Fpeterlau123\u002Fskills-you-need\u002Fblob\u002Fmain\u002Fautonomous-ai-agents\u002Fhermes-custom-provider\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: hermes-custom-provider\ndescription: \"Use when adding custom LLM providers to Hermes.\"\nversion: 1.0.0\nlicense: MIT\nmetadata:\n  hermes:\n    tags: [hermes, provider, openai-compatible, plugin, config]\n---\n\n# Adding a Custom OpenAI-Compatible Provider to Hermes\n\nUse when the user gives you a custom LLM endpoint (\"add provider\", base URL + API key, e.g. an\ninternal MaaS gateway like yicloud) and wants Hermes to use it — as a test switch, a new default,\nor a fallback. Verified end-to-end on mx001 2026-08-05 with yicloud (`https:\u002F\u002Fmaas.yicloud.com\u002Fv1`).\n\n## Steps\n\n1. **Store the API key in `.env` FIRST** (never config.yaml — secrets belong in the profile's\n   `.env`). Append with terminal `printf '%s\\n' 'NAME_API_KEY=\u003Ckey>' >> ~\u002F.hermes\u002Fprofiles\u002F\u003Cprofile>\u002F.env`.\n   Then always source it, never embed the literal in commands:\n   `export NAME_API_KEY=$(grep '^NAME_API_KEY=' ~\u002F.hermes\u002Fprofiles\u002F\u003Cprofile>\u002F.env | cut -d= -f2)`\n2. **Verify the endpoint directly with curl before touching Hermes config**:\n   - List models: `curl -s -H \"Authorization: Bearer $KEY\" \u003Cbase>\u002Fmodels` → confirms auth AND gives\n     the exact model ids (don't guess — e.g. yicloud exposes `glm5.2`, `glm5.2-pd`, `glm4.7`, `kimi-k3`).\n   - Chat test: `POST \u003Cbase>\u002Fchat\u002Fcompletions` with `{\"model\":\"\u003Cid>\",\"messages\":[...],\"max_tokens\":300}`.\n     Note: reasoning models (glm5.2) eat `max_tokens` on thinking — a 20-token cap returns empty\n     `content` with nonzero `reasoning_tokens`; use ≥200 to see real text.\n3. **Create the user provider plugin** (this is the pattern the shipped providers use):\n   `~\u002F.hermes\u002Fprofiles\u002F\u003Cprofile>\u002Fplugins\u002Fmodel-providers\u002F\u003Cname>\u002F__init__.py`:\n   ```python\n   from providers import register_provider\n   from providers.base import ProviderProfile\n\n   \u003Cname> = ProviderProfile(\n       name=\"\u003Cname>\",\n       aliases=(\"\u003Cname>-maas\",),\n       display_name=\"\u003CName> MaaS\",\n       description=\"...\",\n       env_vars=(\"\u003CNAME>_API_KEY\",),\n       base_url=\"https:\u002F\u002F\u003Chost>\u002Fv1\",\n       auth_type=\"api_key\",\n       default_aux_model=\"\u003Ca cheap chat model id>\",\n       fallback_models=(\"\u003Cid2>\", \"\u003Cid3>\"),\n   )\n   register_provider(\u003Cname>)\n   ```\n   plus a sibling `plugin.yaml`:\n   ```yaml\n   name: \u003Cname>-provider\n   kind: model-provider\n   version: 1.0.0\n   description: ...\n   ```\n4. **Enable the plugin**: `hermes plugins list | grep \u003Cname>` → shows `not enabled`; then\n   `hermes plugins enable \u003Cname>-provider`. A \"may not override built-in tools\" warning is benign.\n5. **Test through Hermes** (explicit override, before changing defaults):\n   `hermes chat -q \"\u003Cprompt>\" -m \u003Cmodel-id> --provider \u003Cname>` — confirm the response text.\n6. **Switch the default only after the test passes**:\n   `hermes config set model.provider \u003Cname>` and `hermes config set model.default \u003Cmodel-id>`.\n   Verify with `hermes config get model`; final check: `hermes chat -q \"回复OK即可\"` with no overrides.\n\n## Pitfalls\n\n- Config changes affect NEW sessions only — the current live conversation keeps its old model.\n  Tell the user; switching the live session needs a gateway restart or `\u002Fmodel`.\n- **config.yaml can be silently reverted by an external actor** (observed on mx001 2026-08-06: the\n  default was set to yicloud\u002Fglm5.2 and verified, but hours later `hermes config get model` showed\n  deepseek again — another session\u002Ftool had overwritten the file). The RUNNING gateway keeps the\n  config it started with, so the live session may still show the new model while the file says\n  otherwise. When verifying later, be explicit: `hermes config get model -p \u003Cprofile>` (the CLI\n  default profile may differ from the live session's), and distinguish \"file state\" from \"live\n  session state\" — check BOTH before claiming the switch stuck.\n- The user-plugin dir is per-profile: `plugins\u002Fmodel-providers\u002F\u003Cname>\u002F` under the ACTIVE profile's\n  home (resolve via `$HERMES_HOME`), not the bundled repo's `plugins\u002F`.\n- ProviderProfile fields that matter: `env_vars` (which .env var carries the key), `base_url`,\n  `auth_type=\"api_key\"`, `default_aux_model` (aux\u002Fvision model — pick a cheap id from the \u002Fmodels\n  list to avoid resolution failures).\n- After adding a provider, configure a fallback so the new default has a fallback chain\n  (single-provider setups break on provider outages). See \"Fallback configuration\" below.\n- If the user says \"switch to model X\" but X has no exact id, list `\u002Fv1\u002Fmodels` and match by\n  substring (e.g. \"glm 5.2\" → `glm5.2`).\n\n## Fallback configuration\n\n`hermes fallback add` is an **interactive picker only** — it does NOT accept provider\u002Fmodel\narguments on the CLI (`hermes fallback add deepseek` → error). Two ways to configure:\n\n**Option A (preferred): edit config.yaml directly.** Add a **top-level** `fallback_providers` key\n(NOT under `model:`, NOT `model.fallbacks` — that key is ignored):\n\n```yaml\nfallback_providers:\n  - provider: deepseek\n    model: deepseek-chat\n```\n\nWrite it with Python+PyYAML (preserves existing structure), then verify:\n```bash\nhermes fallback list   # should show: Primary + Fallback chain\n```\n\n**Option B: `hermes fallback` (no args)** launches the interactive picker — works but not\nscriptable.\n\n### Fallback pitfalls (observed 2026-08-06)\n\n- `hermes config set model.fallbacks '[{...}]'` writes to `model.fallbacks` — **wrong key**,\n  silently ignored by `hermes fallback list`. The correct key is top-level `fallback_providers`.\n- `hermes config set` with `--delete` flag → `unrecognized arguments` (no such flag exists).\n  Use `sed -i` or PyYAML to remove unwanted keys from config.yaml.\n- Each fallback entry needs BOTH `provider` and `model` — entries missing either are ignored.\n- `fallback_model` (singular) is the legacy key, still honored for back-compat, but\n  `fallback_providers` (plural list) takes priority. Use the plural form.\n\n## Provider self-check (run after setup or when asked to verify)\n\nSystematic check that all configured providers actually work:\n\n1. **Config state vs live state** — `hermes config get model -p \u003Cprofile>` reads the file;\n   the running gateway may differ (config can be silently reverted — see Pitfalls above).\n   Check BOTH file content (`grep -A2 \"^model:\" config.yaml`) and what the live session reports.\n2. **Per-model curl test** — for each model on each provider, send a minimal chat request:\n   ```bash\n   curl -s --max-time 30 -X POST \"\u003Cbase>\u002Fchat\u002Fcompletions\" \\\n     -H \"Authorization: Bearer $KEY\" -H \"Content-Type: application\u002Fjson\" \\\n     -d '{\"model\":\"\u003Cid>\",\"messages\":[{\"role\":\"user\",\"content\":\"回复OK\"}],\"max_tokens\":100}' \\\n     | python3 -c \"import json,sys; d=json.load(sys.stdin); c=d.get('choices',[{}])[0].get('message',{}); print('✅' if c else '❌', (c.get('content') or json.dumps(d,ensure_ascii=False))[:80])\"\n   ```\n3. **Listed ≠ callable** — models in `\u002Fv1\u002Fmodels` may return \"Invalid model name\" on actual\n   calls (observed: yicloud `glm5.2-pd` listed but errors). Test with a real chat request, not\n   just the models endpoint.\n4. **Reasoning models** — glm4.7, kimi-k3, and glm5.2 (at low max_tokens) return empty `content`\n   with nonzero `reasoning_tokens`. Use `max_tokens ≥ 200` and check `reasoning_content` field\n   to distinguish \"broken\" from \"thinking too much.\"\n5. **Fallback chain** — `hermes fallback list` should show Primary + fallback entries. If empty,\n   the fallback key is wrong (see pitfalls above).\n","# Adding a Custom OpenAI-Compatible Provider to Hermes\n\nUse when the user gives you a custom LLM endpoint (\"add provider\", base URL + API key, e.g. an\ninternal MaaS gateway like yicloud) and wants Hermes to use it — as a test switch, a new default,\nor a fallback. Verified end-to-end on mx001 2026-08-05 with yicloud (`https:\u002F\u002Fmaas.yicloud.com\u002Fv1`).\n\n## Steps\n\n1. **Store the API key in `.env` FIRST** (never config.yaml — secrets belong in the profile's\n   `.env`). Append with terminal `printf '%s\\n' 'NAME_API_KEY=\u003Ckey>' >> ~\u002F.hermes\u002Fprofiles\u002F\u003Cprofile>\u002F.env`.\n   Then always source it, never embed the literal in commands:\n   `export NAME_API_KEY=$(grep '^NAME_API_KEY=' ~\u002F.hermes\u002Fprofiles\u002F\u003Cprofile>\u002F.env | cut -d= -f2)`\n2. **Verify the endpoint directly with curl before touching Hermes config**:\n   - List models: `curl -s -H \"Authorization: Bearer $KEY\" \u003Cbase>\u002Fmodels` → confirms auth AND gives\n     the exact model ids (don't guess — e.g. yicloud exposes `glm5.2`, `glm5.2-pd`, `glm4.7`, `kimi-k3`).\n   - Chat test: `POST \u003Cbase>\u002Fchat\u002Fcompletions` with `{\"model\":\"\u003Cid>\",\"messages\":[...],\"max_tokens\":300}`.\n     Note: reasoning models (glm5.2) eat `max_tokens` on thinking — a 20-token cap returns empty\n     `content` with nonzero `reasoning_tokens`; use ≥200 to see real text.\n3. **Create the user provider plugin** (this is the pattern the shipped providers use):\n   `~\u002F.hermes\u002Fprofiles\u002F\u003Cprofile>\u002Fplugins\u002Fmodel-providers\u002F\u003Cname>\u002F__init__.py`:\n   ```python\n   from providers import register_provider\n   from providers.base import ProviderProfile\n\n   \u003Cname> = ProviderProfile(\n       name=\"\u003Cname>\",\n       aliases=(\"\u003Cname>-maas\",),\n       display_name=\"\u003CName> MaaS\",\n       description=\"...\",\n       env_vars=(\"\u003CNAME>_API_KEY\",),\n       base_url=\"https:\u002F\u002F\u003Chost>\u002Fv1\",\n       auth_type=\"api_key\",\n       default_aux_model=\"\u003Ca cheap chat model id>\",\n       fallback_models=(\"\u003Cid2>\", \"\u003Cid3>\"),\n   )\n   register_provider(\u003Cname>)\n   ```\n   plus a sibling `plugin.yaml`:\n   ```yaml\n   name: \u003Cname>-provider\n   kind: model-provider\n   version: 1.0.0\n   description: ...\n   ```\n4. **Enable the plugin**: `hermes plugins list | grep \u003Cname>` → shows `not enabled`; then\n   `hermes plugins enable \u003Cname>-provider`. A \"may not override built-in tools\" warning is benign.\n5. **Test through Hermes** (explicit override, before changing defaults):\n   `hermes chat -q \"\u003Cprompt>\" -m \u003Cmodel-id> --provider \u003Cname>` — confirm the response text.\n6. **Switch the default only after the test passes**:\n   `hermes config set model.provider \u003Cname>` and `hermes config set model.default \u003Cmodel-id>`.\n   Verify with `hermes config get model`; final check: `hermes chat -q \"回复OK即可\"` with no overrides.\n\n## Pitfalls\n\n- Config changes affect NEW sessions only — the current live conversation keeps its old model.\n  Tell the user; switching the live session needs a gateway restart or `\u002Fmodel`.\n- **config.yaml can be silently reverted by an external actor** (observed on mx001 2026-08-06: the\n  default was set to yicloud\u002Fglm5.2 and verified, but hours later `hermes config get model` showed\n  deepseek again — another session\u002Ftool had overwritten the file). The RUNNING gateway keeps the\n  config it started with, so the live session may still show the new model while the file says\n  otherwise. When verifying later, be explicit: `hermes config get model -p \u003Cprofile>` (the CLI\n  default profile may differ from the live session's), and distinguish \"file state\" from \"live\n  session state\" — check BOTH before claiming the switch stuck.\n- The user-plugin dir is per-profile: `plugins\u002Fmodel-providers\u002F\u003Cname>\u002F` under the ACTIVE profile's\n  home (resolve via `$HERMES_HOME`), not the bundled repo's `plugins\u002F`.\n- ProviderProfile fields that matter: `env_vars` (which .env var carries the key), `base_url`,\n  `auth_type=\"api_key\"`, `default_aux_model` (aux\u002Fvision model — pick a cheap id from the \u002Fmodels\n  list to avoid resolution failures).\n- After adding a provider, configure a fallback so the new default has a fallback chain\n  (single-provider setups break on provider outages). See \"Fallback configuration\" below.\n- If the user says \"switch to model X\" but X has no exact id, list `\u002Fv1\u002Fmodels` and match by\n  substring (e.g. \"glm 5.2\" → `glm5.2`).\n\n## Fallback configuration\n\n`hermes fallback add` is an **interactive picker only** — it does NOT accept provider\u002Fmodel\narguments on the CLI (`hermes fallback add deepseek` → error). Two ways to configure:\n\n**Option A (preferred): edit config.yaml directly.** Add a **top-level** `fallback_providers` key\n(NOT under `model:`, NOT `model.fallbacks` — that key is ignored):\n\n```yaml\nfallback_providers:\n  - provider: deepseek\n    model: deepseek-chat\n```\n\nWrite it with Python+PyYAML (preserves existing structure), then verify:\n```bash\nhermes fallback list   # should show: Primary + Fallback chain\n```\n\n**Option B: `hermes fallback` (no args)** launches the interactive picker — works but not\nscriptable.\n\n### Fallback pitfalls (observed 2026-08-06)\n\n- `hermes config set model.fallbacks '[{...}]'` writes to `model.fallbacks` — **wrong key**,\n  silently ignored by `hermes fallback list`. The correct key is top-level `fallback_providers`.\n- `hermes config set` with `--delete` flag → `unrecognized arguments` (no such flag exists).\n  Use `sed -i` or PyYAML to remove unwanted keys from config.yaml.\n- Each fallback entry needs BOTH `provider` and `model` — entries missing either are ignored.\n- `fallback_model` (singular) is the legacy key, still honored for back-compat, but\n  `fallback_providers` (plural list) takes priority. Use the plural form.\n\n## Provider self-check (run after setup or when asked to verify)\n\nSystematic check that all configured providers actually work:\n\n1. **Config state vs live state** — `hermes config get model -p \u003Cprofile>` reads the file;\n   the running gateway may differ (config can be silently reverted — see Pitfalls above).\n   Check BOTH file content (`grep -A2 \"^model:\" config.yaml`) and what the live session reports.\n2. **Per-model curl test** — for each model on each provider, send a minimal chat request:\n   ```bash\n   curl -s --max-time 30 -X POST \"\u003Cbase>\u002Fchat\u002Fcompletions\" \\\n     -H \"Authorization: Bearer $KEY\" -H \"Content-Type: application\u002Fjson\" \\\n     -d '{\"model\":\"\u003Cid>\",\"messages\":[{\"role\":\"user\",\"content\":\"回复OK\"}],\"max_tokens\":100}' \\\n     | python3 -c \"import json,sys; d=json.load(sys.stdin); c=d.get('choices',[{}])[0].get('message',{}); print('✅' if c else '❌', (c.get('content') or json.dumps(d,ensure_ascii=False))[:80])\"\n   ```\n3. **Listed ≠ callable** — models in `\u002Fv1\u002Fmodels` may return \"Invalid model name\" on actual\n   calls (observed: yicloud `glm5.2-pd` listed but errors). Test with a real chat request, not\n   just the models endpoint.\n4. **Reasoning models** — glm4.7, kimi-k3, and glm5.2 (at low max_tokens) return empty `content`\n   with nonzero `reasoning_tokens`. Use `max_tokens ≥ 200` and check `reasoning_content` field\n   to distinguish \"broken\" from \"thinking too much.\"\n5. **Fallback chain** — `hermes fallback list` should show Primary + fallback entries. If empty,\n   the fallback key is wrong (see pitfalls above).\n",{"name":5,"license":15,"version":24,"metadata":25,"description":7},"1.0.0",{"hermes":26},{"tags":27},[28,29,30,31,32],"hermes","provider","openai-compatible","plugin","config","main","c0b220603dea88e986e5b31268098ef2f5b07fd0","autonomous-ai-agents\u002Fhermes-custom-provider","https:\u002F\u002Fgithub.com\u002Fpeterlau123\u002Fskills-you-need","https:\u002F\u002Fgithub.com\u002Fpeterlau123","A software engineer in deep learning\r\n","2026-08-19 16:46:00",{"source":8,"skillName":5,"commands":41,"prompt":51,"zipAvailable":52},[42,45,48],{"tool":43,"command":44},"npx","npx skills add peterlau123\u002Fskills-you-need --skill hermes-custom-provider",{"tool":46,"command":47},"bunx","bunx skills add peterlau123\u002Fskills-you-need --skill hermes-custom-provider",{"tool":49,"command":50},"pnpm","pnpm dlx skills add peterlau123\u002Fskills-you-need --skill hermes-custom-provider","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fpeterlau123\u002Fskills-you-need\u002Fblob\u002Fmain\u002Fautonomous-ai-agents\u002Fhermes-custom-provider\u002FSKILL.md",true,[],[55,62,69,76,83,90],{"skillNo":56,"name":57,"nameZh":6,"description":58,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":59,"categories":60,"keywords":61,"publishedAt":19},"01M7AVH2D16QBRC8T2P6SVXSTS","jekyll-chirpy-blog","Use when editing the Jekyll\u002FChirpy blog or fixing mermaid.","https:\u002F\u002Fgithub.com\u002Fpeterlau123\u002Fskills-you-need\u002Fblob\u002Fmain\u002Fweb\u002Fjekyll-chirpy-blog\u002FSKILL.md",[],[],{"skillNo":63,"name":64,"nameZh":6,"description":65,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":66,"categories":67,"keywords":68,"publishedAt":19},"01M7AVGYYFDK4GKCSNHBCP59Y6","test-driven-development","TDD: enforce RED-GREEN-REFACTOR, tests before code.","https:\u002F\u002Fgithub.com\u002Fpeterlau123\u002Fskills-you-need\u002Fblob\u002Fmain\u002Fsoftware-development\u002Ftest-driven-development\u002FSKILL.md",[],[],{"skillNo":70,"name":71,"nameZh":6,"description":72,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":73,"categories":74,"keywords":75,"publishedAt":19},"01M7AVGT9GAVB5EBKZ2616R27Z","systematic-debugging","4-phase root cause debugging: understand bugs before fixing.","https:\u002F\u002Fgithub.com\u002Fpeterlau123\u002Fskills-you-need\u002Fblob\u002Fmain\u002Fsoftware-development\u002Fsystematic-debugging\u002FSKILL.md",[],[],{"skillNo":77,"name":78,"nameZh":6,"description":79,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":80,"categories":81,"keywords":82,"publishedAt":19},"01M7AVGQ23T5EHRQP5GZ45KZC5","spike","Throwaway experiments to validate an idea before build.","https:\u002F\u002Fgithub.com\u002Fpeterlau123\u002Fskills-you-need\u002Fblob\u002Fmain\u002Fsoftware-development\u002Fspike\u002FSKILL.md",[],[],{"skillNo":84,"name":85,"nameZh":6,"description":86,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":87,"categories":88,"keywords":89,"publishedAt":19},"01M7AVGKZ0ZD91ATKD9QB44E1B","simplify-code","Parallel 4-agent cleanup of recent code changes.","https:\u002F\u002Fgithub.com\u002Fpeterlau123\u002Fskills-you-need\u002Fblob\u002Fmain\u002Fsoftware-development\u002Fsimplify-code\u002FSKILL.md",[],[],{"skillNo":91,"name":92,"nameZh":6,"description":93,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":94,"categories":95,"keywords":96,"publishedAt":19},"01M7AVGFBR76BWQNG2X4CN5SQT","requesting-code-review","Pre-commit review: security scan, quality gates, auto-fix.","https:\u002F\u002Fgithub.com\u002Fpeterlau123\u002Fskills-you-need\u002Fblob\u002Fmain\u002Fsoftware-development\u002Frequesting-code-review\u002FSKILL.md",[],[]]