从bazi-skill到你的AI命理工具：SKILL.md提示工程与references知识文件架构完全指南-开发者社区

从bazi-skill到你的AI命理工具：SKILL.md提示工程与references知识文件架构完全指南

【免费下载链接】bazi-skill四柱八字命理分析项目地址: https://gitcode.com/gh_mirrors/ba/bazi-skill

bazi-skill 是一个基于 Claude Code 的四柱八字命理分析工具：一份 SKILL.md 提示词 + 五份 references 知识文件 + 一个零依赖排盘脚本，就能让 AI 像专业命理师一样收集出生信息、排出四柱大运，并引用九本经典典籍给出分析。本文带你完整拆解它的 SKILL.md 提示工程技巧与 references 知识文件架构，你也可以照着搭出自己的 AI Skill。

一、3步装好 bazi-skill，关键词触发排盘

安装只需要两条命令。本机需已安装python3（3.6+ 即可，只用标准库，无需 pip 装任何包）：

# 安装到当前项目（在 git 仓库根目录执行） mkdir -p .claude/skills git clone https://gitcode.com/gh_mirrors/ba/bazi-skill .claude/skills/bazi # 或安装到全局（所有项目都能用） git clone https://gitcode.com/gh_mirrors/ba/bazi-skill ~/.claude/skills/bazi

注意：Claude Code 从仓库根目录的.claude/skills/查找 skill，请在正确位置执行。

安装后，在对话中输入算八字、看八字、排盘、命盘、bazi等任意关键词即可触发。Skill 会逐步引导你提供姓名、生日、时辰、性别、出生地，然后自动跑排盘脚本并输出综合分析。

二、SKILL.md 提示工程：一个文件如何"教会"AI 算命

SKILL.md 是整个项目的入口，也是提示工程的精华所在。它只有 250 多行，却包含了四个关键设计。

1. YAML 元数据头：告诉 AI"什么时候该出场"

文件开头的 frontmatter 定义了 skill 的触发规则：

name: bazi— 技能名；
description— 用中英文双语描述能力，并列出算八字、四柱、fortune telling、birth chart等一长串触发词（Triggers）；
还写明"即使只是提到'算命'、'八字'而没有明确说要用 skill，也应该使用此 skill"。

启示：description 不是写给人看的简介，而是写给 AI 的路由规则。触发词覆盖得越全（中英文、口语化说法都列上），AI 越不容易"该出手时不出手"。

2. 角色设定 + 参考文件索引：给 AI 一本"工作手册"

角色设定一句话立住人设："你是一位中国传统四柱八字命理的专业研究者"，并列出九本熟读的典籍。紧接着重要参考文件一节用清单形式索引了全部 6 份外部文件：

文件	职责
scripts/pai_pan.py	排盘计算（四柱/大运/流年以脚本 stdout 为准）
references/wuxing-tables.md	五行、天干地支、十神、藏干参考表
references/shichen-table.md	时辰对照表、日上起时法（五鼠遁元）
references/dayun-rules.md	大运顺逆排规则、起运年龄计算
references/shensha-table.md	神煞吉凶、查法与口诀
references/classical-texts.md	九本经典典籍核心规则摘要

启示：不要在提示词里塞满所有知识。用"索引 + 按需查阅"的方式，把大知识拆进独立文件，AI 需要时才去读，上下文更省、规则更准。

3. 三阶段流水线：信息收集 → 排盘 → 综合分析

SKILL.md 把整个流程切成三阶段，每阶段都有明确的操作指令：

第一阶段：信息收集（Step 1-9）— 9 小步逐一收集姓名、阳历/农历生日、时辰、性别、出生地等，并明确要求"不要一次问所有问题，一步一步来"。有选项的步骤用选择题工具，自由文本（姓名、地址）直接文字询问，最后用一张汇总卡片让用户确认；
第二阶段：排盘计算（命令行示例）— 确认信息后必须先跑脚本，并给出字段到 CLI 参数的映射表（如阳历生日 →--solar、时辰不确定 → 两参都不传）；
第三阶段：综合分析（八大分析框架）— 日主强弱 → 十神 → 神煞 → 五行平衡 → 格局 → 大运 → 流年 → 历史事件校准 → 综合建议，且要求"所有分析都引用经典典籍的论断并标注出处"。

4. 用"硬规则"约束 AI，杜绝幻觉

提示工程最难的不是教会 AI，而是禁止它乱来。SKILL.md 里反复出现的强约束值得抄作业（见排盘计算阶段）：

"禁止口算、禁止查记忆中的万年历、禁止自行推日柱/月柱/大运后覆盖脚本结果"；
"节气交界 / 立春前后：只看脚本警告，严格采用脚本给出的那套年柱/月柱"；
"神煞以脚本为准，只解释脚本已列出的条目，不要补算未列出的神煞"；
"解释必须服从脚本数字，不能反过来改盘"。

启示：凡是能交给确定性代码算的（干支、节气、起运年龄），就让脚本算，提示词只负责解释和裁决。把"以 X 为准""禁止 Y"写死，AI 的输出才会稳定可复现。

三、references 知识文件架构：让"规则"与"计算"保持同一口径

references/目录的 5 份 Markdown 是这份架构的第二个亮点。它们不是随便写的笔记，而是被设计成与代码互相咬合的知识库：

📊 每份文件只解决一类问题

wuxing-tables.md：纯查表数据——十天干阴阳五行、十神推导规则、十二长生、地支藏干；
shichen-table.md：时辰对照 + 早晚子时处理 + 五鼠遁元口诀与完整查表；
dayun-rules.md：大运顺逆规则表（阳男阴女顺排）与起运年龄公式；
shensha-table.md：神煞吉凶、查法与口诀，分"吉"与"凶/中性"两块；
classical-texts.md：九本典籍的核心规则摘要（调候用神、格局论命、旺衰判断……），把厚重古籍压缩成 AI 可直接引用的条目。

🔗 "唯一口径"设计

shensha-table.md 开头明确声明："本表是本仓库唯一神煞口径，与scripts/pai_pan.py的计算规则完全一致"。SKILL.md 也对应要求 AI "解释时读references/shensha-table.md（与脚本同一口径）"。

规则文档、计算脚本、提示词三处指向同一张表，AI 解释的每个神煞都能在脚本输出里找到出处——这是"知识文件架构"最核心的价值：不是知识越多越好，而是知识与计算零偏差。

四、pai_pan.py：零依赖脚本，给 AI 打好数学底座

scripts/pai_pan.py（约 1400 行）只用 Python 标准库，却实现了完整的排盘引擎，文件头部的算法锚点注释本身就是一份精妙的"QA 规格书"：

日柱：儒略日（JDN）→ 六十甲子，公式gz_index = (JDN + 49) % 60，并给了1990-05-15 = 庚辰这样的可验证锚点；
年柱/月柱：以立春、十二"节"的精确太阳视黄经时刻分界（立春 = 黄经 315°），而不是写死"2 月 4 日"；
节气与农历：用 Meeus 简式太阳黄经 + 定朔算法，精确到小时，覆盖 1900–2100 年；
大运：阳年男/阴年女顺排，起运年龄 = 出生日到最近"节"的天数 ÷ 3，与 dayun-rules.md 完全一致；
输出结构化：stdout 按## 输入 / ## 四柱 / ## 大运 / ## 流年 / ## 神煞 / ## 警告分段，AI 直接引用。

配套还有 test_pai_pan.py 回归测试——每个关键算法（日柱锚点、立春分界、早晚子时、顺逆排）都有测试用例，保证"唯一口径"永不漂移。

启示：给 AI 写工具链时，"确定性计算 + 结构化输出 + 回归测试"三件套，比在提示词里反复叮嘱"要算得准"有效得多。

五、复刻指南：4步搭出你自己的 AI Skill

想把这套架构搬到自己的领域（比如塔罗、星座、起名、占星），照下面 4 步走：

写 SKILL.md 入口：YAML 头写全name/description/ 触发词（中英文 + 口语变体），正文写角色设定、参考文件索引、分阶段流程；
拆 references 知识文件：按"查表数据 / 规则流程 / 理论摘要"拆成独立 md，每份文件只回答一类问题，开头声明"本文件与脚本同一口径"；
写确定性脚本：能算的绝不靠 AI 口算。只用标准库（或最小依赖），输出结构化 stdout，头部注释写清算法锚点；
建回归测试 + 硬规则：给脚本写锚点测试；在 SKILL.md 中用"以 X 为准 / 禁止 Y"句式锁死 AI 的行为边界，并加好边界情况表与免责说明（参考边界情况处理与注意事项）。