/horosa-agent
Call Horosa (星阙) local metaphysics tools correctly over MCP or CLI — 110 real techniques: Western natal/predictive astrology (returns, progressions, primary directions, horary 卜卦, election 择日), 八字, 紫微, 大六壬, 奇门遁甲, 太乙, 金口诀, 三式合一, 河洛理数, 邵子参评数, 六爻, 天文地占, 塔罗, and the full 14 神数. Use
$ npx -y skills add horace-maxwell/horosa-skill --skill horosa-agent --agent claude-codeHow it fires
How this skill gets triggered: by you, by Claude, or both.
- Fires itselfAuto-invocation. Claude auto-loads it when your prompt matches the work.Auto-invocation is when the right skill fires by itself at the right moment, driven by a FLOW.md router and a hook, instead of you invoking it by name. It is the difference between a skill being installed and a skill actually getting used.Read the full definition →
- You can call itInvoke it directly when you want it.
- Slash command
/horosa-agent
Context preview
The summary Claude sees to decide when to auto-load this skill.
Call Horosa (星阙) local metaphysics tools correctly over MCP or CLI — 110 real techniques: Western natal/predictive astrology (returns, progressions, primary directions, horary 卜卦, election 择日), 八字, 紫微, 大六壬, 奇门遁甲, 太乙, 金口诀, 三式合一, 河洛理数, 邵子参评数, 六爻, 天文地占, 塔罗, and the full 14 神数. Use
SKILL.md
horosa-agent.SKILL.mdname: horosa-agent
description: >-
Call Horosa (星阙) local metaphysics tools correctly over MCP or CLI — 110 real techniques: Western
natal/predictive astrology (returns, progressions, primary directions, horary 卜卦, election 择日),
八字, 紫微, 大六壬, 奇门遁甲, 太乙, 金口诀, 三式合一, 河洛理数, 邵子参评数, 六爻, 天文地占, 塔罗, and
the full 14 神数. Use whenever a user asks to 起盘 / 排盘 / 起课 / 起卦 / 算命 / 推运 / 看盘 / 合盘 /
卜卦 / 择日 or requests any Horosa/星阙 chart, reading, report, or stored run — and when debugging a
user-facing Horosa result. Enforces the clarify-before-call gate and the export-snapshot reading
contract; never hand-calculate these methods.
license: AGPL-3.0-only
compatibility: Requires the local Horosa Skill MCP server/CLI (Python 3.12 + uv + installed offline runtime)
metadata:
version: "0.41.0"
Horosa Skill Agent Guide
Use this guide when an AI agent is connected to Horosa Skill through MCP, CLI, Cursor, Claude, Codex, OpenClaw, Open WebUI, or another local-first client and needs to call Horosa metaphysics tools, generate reports, store memory, or debug user-facing results.
This file is the **single policy source for AI-client behaviour** (repo rules & maintainer law live in [`AGENTS.md`](../../AGENTS.md)). Detail lives in the reference sheets:
| Reference | Content | | --- | --- | | [`references/payloads.md`](./references/payloads.md) | Input payload defaults (event/birth JSON), coordinates, gender/timeAlg fields | | [`references/late-zi.md`](./references/late-zi.md) | 晚子时/日界 two-switch spec — canonical matrix, how to ask, status | | [`references/predictive.md`](./references/predictive.md) | Predictive astrology minimum contracts (returns/progressions/PD), PD engine parity | | [`references/chinese-methods.md`](./references/chinese-methods.md) | 大六壬 defaults, current-time casting flow, 奇门法奇门 sections, 中式技法 notes | | [`references/reports.md`](./references/reports.md) | Report/memory workflow, one-command CLI report, interpretation style detail | | [`references/troubleshooting.md`](./references/troubleshooting.md) | Debug commands, openclaw setup/check, symptom table, cross-platform notes |
Quickstart — 三步出 Word 报告
// 1) 起盘（确认设置后）——返回 memory_ref.run_id
horosa_cn_qimen {date, time, zone:"+08:00", lat:"31n13", lon:"121e28", agent_confirmed_settings:true, clarification_notes:"…"}
// 2) 读 data.export_snapshot.export_text / sections 写出你的解读（ai_report 各字段）
// 3) 渲染 —— ai_report 自动写回记忆，无需再调 memory_record_answer
horosa_report_render {run_id, tool_name:"qimen", format:"docx", ai_report:{executive_summary, answer_text, analysis_sections, recommendations, limitations}}报告 `output_path` 可省（写到报告输出目录的缺省产物路径）；给了则相对路径按输出目录解析，绝对路径必须在输出目录或 `HOROSA_REPORT_OUTPUT_ROOTS` 白名单目录内，越界返回 `report.output_path_not_allowed` 且不写文件——别替用户猜别的目录。
七政四余 `guolao_chart` 可传 `guolaoLifeMode`（asc/yumao/cotrans）、`guolaoBodyMode`、`moiraTransitDate`（[流年流曜] 的流年时刻，缺省今天）；[虚实]/[本命化曜]/[流年流曜] 三段来自 Java 规则层，Java 不可用时缺席并进 `warnings`。 河洛 `heluo` 可传 `liunianStep2`（ying/sequential）、`ziShuMode`、`jiGongMode` 等取法旋钮（全表见 guidance）。 只知道四柱不知道生日：`bazi_inverse {pillars:["甲子","丙寅","戊辰","庚申"], fromYear, count}` 反查候选出生时刻 （免确认门，候选每 60 年重现，请让用户确认年代）。八字口诀层：`knowledge_read {domain:"bazi_pithy", category:"三字诀", key:"甲"}` 或 `query` 全文检索（21 类 173 条，引必带出处）。
闸门问题带 `options` 的，直接把用户选的那一项原话记进 `clarification_notes`（同名 `values` 是该选项对应的 schema 值，可直接放进载荷）；`planetaryarc` 的弧源、神数的性别/地点这类工具自有敏感项闸门会点名问，别替用户默认。
找工具：每个工具描述带 `aka:` 别名（中文口语/拼音/英文）；不确定就 `horosa_dispatch`（路由覆盖全部技法， 含 10 个择日窗口搜索：`tianxing` + 9 支 `*zeri`）或 `horosa_agent_guidance`（响应里的 `server_profile` 告诉你本进程实际平铺了哪些域、 `HOROSA_TOOLSETS` 有没有拼错、`horosa_tool_run` 在不在）。`HOROSA_TOOLSETS` 的合法域 = `astro` / `predict` / `chart` / `cn` / `shenshu` / `other` / `export` / `knowledge`，别名 `western` / `chinese` / `reference` / `all` / `none`；认不出的词会被丢掉并进 warning。
**精简面（`HOROSA_MCP_COMPACT=1`，11 个门面级工具 = 10 门面 + `horosa_tool_run`）**：Cursor / VS Code / Codex / Gemini / Devin Desktop（原 Windsurf）/ Cline / Zed 默认拿到它（`setup --surface full|compact` 可改；Claude Code / Claude Desktop 默认全量 120）。`horosa_tool_run(tool_name=<注册键>, …)` 接受与平铺工具**完全相同**的载荷与闸门字段；`tool_name` 不认识时返回按域分组的 `details.catalog`，不要据此说「没有这个技法」。
tools/list 只广告每个工具的域核心字段 + 自有字段；BirthInput 长尾旋钮（`orbSystem`/`extraBodies`/`termsVariant`…） **顶层按名直接传即可、不会被丢**，全表用 `horosa_agent_guidance(tool_name=…)` 查（v0.36.0 两层 schema）。
省 token：技法工具可传 `response_view:"titles"`（只回段标题）或 `"sections"`；完整快照始终已存档（`horosa_memory_show(run_id)` 取回）。`export_snapshot.sections[*]` 只含 `body`；机读数据在 `data.<key>`（`data.pan` / `data.chart` / `data.liureng` …）只出现一次，别去段里找。注意 `horosa_report_from_tool` 会重新起盘——已有 run_id 用 `report_render`。
出错时看 `details.agent_recovery`：`kind` 说谁能修——`input`（问用户 / 修入参）、`retry_or_doctor`（重试一次再让用户跑 `uv run horosa-skill doctor`）、`transport`（冷启动 ≤ ~45 s，等几秒重试一次）、`runtime` / `js_engine`（装 runtime 或设 HOROSA_NODE_BIN）、 `environment`（本机环境：PATH / 编码 / 端口）、`decision_layer`（云端决策层不可用 = 已本地兜底）；`next_action` 是机器可读的下一步， `prompt_to_user` 双语可直接转述；不要把 `ok:false` 当成「该技法没有此项」。几条要记住的码：`runtime.starting` → 按 `retry_after_seconds` （5 s）原样重试同一调用，三次后 `horosa-skill runtime status`；`runtime.java_backend_unavailable` → 只影响农历/八字/紫微/六壬族，chart 族照常， 冷却后再试；`runtime.platform_unsupported` → Linux / Intel Mac 没有离线载荷，走网关模式（`HOROSA_SERVER_ROOT` / `HOROSA_CHART_SERVER_ROOT` 指向一台受支持的机器）；`runtime.path_not_ascii` → Windows 的 runtime 根必须纯 ASCII（`setx HOROSA_RUNTIME_ROOT C:\horosa` 后重装）； `runtime.stop_refused_clients_attached` / `stop_refused_foreign` → 另一个客户端或用户的桌面端还挂在服务上，**不要**自作主张加 `--force`。
**`warnings` 非空 = 结果不完整**（`ok` 仍为 true）：「降级：…」是某个子引擎/可选后端本次失败、对应段缺席； 「结果不完整：预设 N 段中 M 段未产出」列出缺了哪些段。报告里必须如实转述，不得把缺席的段当成「该技法没有此项」， 也不得自行补算；dispatch 的 `warnings` 只汇总哪些工具带说明，细节在 `results.<tool>.warnings`。
**每次给出结论后，把 `data.technique_card` 原样转述成一段技法尾注**（技法 / 口径 / 算源 / 段落 / 版本）—— 它是确定性元数据，`response_view` 精简时也在。要文件就调 `horosa_technique_report`（`run_id` 单次、 `group_id` 整场，后者还会检出跨技法口径冲突）。细则与两种报告的分界：[`references/reports.md`](./references/reports.md)。
Core Rule
Horosa Skill is **local-first**. After `horosa-skill install`, algo
Read more
name: horosa-agent description: >- Call Horosa (星阙) local metaphysics tools correctly over MCP or CLI — 110 real techniques: Western natal/predictive astrology (returns, progressions, primary directions, horary 卜卦, election 择日), 八字, 紫微, 大六壬, 奇门遁甲, 太乙, 金口诀, 三式合一, 河洛理数, 邵子参评数, 六爻, 天文地占, 塔罗, and the full 14 神数. Use whenever a user asks to 起盘 / 排盘 / 起课 / 起卦 / 算命 / 推运 / 看盘 / 合盘 / 卜卦 / 择日 or requests any Horosa/星阙 chart, reading, report, or stored run — and when debugging a user-facing Horosa result. Enforces the clarify-before-call gate and the export-snapshot reading contract; never hand-calculate these methods. license: AGPL-3.0-only compatibility: Requires the local Horosa Skill MCP server/CLI (Python 3.12 + uv + installed offline runtime) metadata: version: "0.41.0"
Horosa Skill Agent Guide
Use this guide when an AI agent is connected to Horosa Skill through MCP, CLI, Cursor, Claude, Codex, OpenClaw, Open WebUI, or another local-first client and needs to call Horosa metaphysics tools, generate reports, store memory, or debug user-facing results.
This file is the **single policy source for AI-client behaviour** (repo rules & maintainer law live in [`AGENTS.md`](../../AGENTS.md)). Detail lives in the reference sheets:
| Reference | Content | | --- | --- | | [`references/payloads.md`](./references/payloads.md) | Input payload defaults (event/birth JSON), coordinates, gender/timeAlg fields | | [`references/late-zi.md`](./references/late-zi.md) | 晚子时/日界 two-switch spec — canonical matrix, how to ask, status | | [`references/predictive.md`](./references/predictive.md) | Predictive astrology minimum contracts (returns/progressions/PD), PD engine parity | | [`references/chinese-methods.md`](./references/chinese-methods.md) | 大六壬 defaults, current-time casting flow, 奇门法奇门 sections, 中式技法 notes | | [`references/reports.md`](./references/reports.md) | Report/memory workflow, one-command CLI report, interpretation style detail | | [`references/troubleshooting.md`](./references/troubleshooting.md) | Debug commands, openclaw setup/check, symptom table, cross-platform notes |
Quickstart — 三步出 Word 报告
// 1) 起盘（确认设置后）——返回 memory_ref.run_id
horosa_cn_qimen {date, time, zone:"+08:00", lat:"31n13", lon:"121e28", agent_confirmed_settings:true, clarification_notes:"…"}
// 2) 读 data.export_snapshot.export_text / sections 写出你的解读（ai_report 各字段）
// 3) 渲染 —— ai_report 自动写回记忆，无需再调 memory_record_answer
horosa_report_render {run_id, tool_name:"qimen", format:"docx", ai_report:{executive_summary, answer_text, analysis_sections, recommendations, limitations}}报告 `output_path` 可省（写到报告输出目录的缺省产物路径）；给了则相对路径按输出目录解析，绝对路径必须在输出目录或 `HOROSA_REPORT_OUTPUT_ROOTS` 白名单目录内，越界返回 `report.output_path_not_allowed` 且不写文件——别替用户猜别的目录。
七政四余 `guolao_chart` 可传 `guolaoLifeMode`（asc/yumao/cotrans）、`guolaoBodyMode`、`moiraTransitDate`（[流年流曜] 的流年时刻，缺省今天）；[虚实]/[本命化曜]/[流年流曜] 三段来自 Java 规则层，Java 不可用时缺席并进 `warnings`。 河洛 `heluo` 可传 `liunianStep2`（ying/sequential）、`ziShuMode`、`jiGongMode` 等取法旋钮（全表见 guidance）。 只知道四柱不知道生日：`bazi_inverse {pillars:["甲子","丙寅","戊辰","庚申"], fromYear, count}` 反查候选出生时刻 （免确认门，候选每 60 年重现，请让用户确认年代）。八字口诀层：`knowledge_read {domain:"bazi_pithy", category:"三字诀", key:"甲"}` 或 `query` 全文检索（21 类 173 条，引必带出处）。
闸门问题带 `options` 的，直接把用户选的那一项原话记进 `clarification_notes`（同名 `values` 是该选项对应的 schema 值，可直接放进载荷）；`planetaryarc` 的弧源、神数的性别/地点这类工具自有敏感项闸门会点名问，别替用户默认。
找工具：每个工具描述带 `aka:` 别名（中文口语/拼音/英文）；不确定就 `horosa_dispatch`（路由覆盖全部技法， 含 10 个择日窗口搜索：`tianxing` + 9 支 `*zeri`）或 `horosa_agent_guidance`（响应里的 `server_profile` 告诉你本进程实际平铺了哪些域、 `HOROSA_TOOLSETS` 有没有拼错、`horosa_tool_run` 在不在）。`HOROSA_TOOLSETS` 的合法域 = `astro` / `predict` / `chart` / `cn` / `shenshu` / `other` / `export` / `knowledge`，别名 `western` / `chinese` / `reference` / `all` / `none`；认不出的词会被丢掉并进 warning。
**精简面（`HOROSA_MCP_COMPACT=1`，11 个门面级工具 = 10 门面 + `horosa_tool_run`）**：Cursor / VS Code / Codex / Gemini / Devin Desktop（原 Windsurf）/ Cline / Zed 默认拿到它（`setup --surface full|compact` 可改；Claude Code / Claude Desktop 默认全量 120）。`horosa_tool_run(tool_name=<注册键>, …)` 接受与平铺工具**完全相同**的载荷与闸门字段；`tool_name` 不认识时返回按域分组的 `details.catalog`，不要据此说「没有这个技法」。
tools/list 只广告每个工具的域核心字段 + 自有字段；BirthInput 长尾旋钮（`orbSystem`/`extraBodies`/`termsVariant`…） **顶层按名直接传即可、不会被丢**，全表用 `horosa_agent_guidance(tool_name=…)` 查（v0.36.0 两层 schema）。
省 token：技法工具可传 `response_view:"titles"`（只回段标题）或 `"sections"`；完整快照始终已存档（`horosa_memory_show(run_id)` 取回）。`export_snapshot.sections[*]` 只含 `body`；机读数据在 `data.<key>`（`data.pan` / `data.chart` / `data.liureng` …）只出现一次，别去段里找。注意 `horosa_report_from_tool` 会重新起盘——已有 run_id 用 `report_render`。
出错时看 `details.agent_recovery`：`kind` 说谁能修——`input`（问用户 / 修入参）、`retry_or_doctor`（重试一次再让用户跑 `uv run horosa-skill doctor`）、`transport`（冷启动 ≤ ~45 s，等几秒重试一次）、`runtime` / `js_engine`（装 runtime 或设 HOROSA_NODE_BIN）、 `environment`（本机环境：PATH / 编码 / 端口）、`decision_layer`（云端决策层不可用 = 已本地兜底）；`next_action` 是机器可读的下一步， `prompt_to_user` 双语可直接转述；不要把 `ok:false` 当成「该技法没有此项」。几条要记住的码：`runtime.starting` → 按 `retry_after_seconds` （5 s）原样重试同一调用，三次后 `horosa-skill runtime status`；`runtime.java_backend_unavailable` → 只影响农历/八字/紫微/六壬族，chart 族照常， 冷却后再试；`runtime.platform_unsupported` → Linux / Intel Mac 没有离线载荷，走网关模式（`HOROSA_SERVER_ROOT` / `HOROSA_CHART_SERVER_ROOT` 指向一台受支持的机器）；`runtime.path_not_ascii` → Windows 的 runtime 根必须纯 ASCII（`setx HOROSA_RUNTIME_ROOT C:\horosa` 后重装）； `runtime.stop_refused_clients_attached` / `stop_refused_foreign` → 另一个客户端或用户的桌面端还挂在服务上，**不要**自作主张加 `--force`。
**`warnings` 非空 = 结果不完整**（`ok` 仍为 true）：「降级：…」是某个子引擎/可选后端本次失败、对应段缺席； 「结果不完整：预设 N 段中 M 段未产出」列出缺了哪些段。报告里必须如实转述，不得把缺席的段当成「该技法没有此项」， 也不得自行补算；dispatch 的 `warnings` 只汇总哪些工具带说明，细节在 `results.<tool>.warnings`。
**每次给出结论后，把 `data.technique_card` 原样转述成一段技法尾注**（技法 / 口径 / 算源 / 段落 / 版本）—— 它是确定性元数据，`response_view` 精简时也在。要文件就调 `horosa_technique_report`（`run_id` 单次、 `group_id` 整场，后者还会检出跨技法口径冲突）。细则与两种报告的分界：[`references/reports.md`](./references/reports.md)。
Core Rule
Horosa Skill is **local-first**. After `horosa-skill install`, algo
把星阙（Horosa）的 110 个真实术数 / 占星技法，做成任何 AI 都能本地调用的 MCP server 与 CLI。 A local-first MCP server & CLI that exposes 110 real astrology / metaphysics techniques from Horosa (星阙) to any AI client.