AionClaw技能设计需精简SKILL.md的description（≤3行、无代码块）、trigger_keywords限2–3个高区分度词、scripts中避免绝对路径和未声明依赖。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
在 AionClaw 中写一个功能完整、描述详尽、示例丰富的 Skill，看似专业，实则容易触发模型层的硬性限制——尤其是调用免费或轻量级模型时，技能本身就会吃掉大量上下文，导致任务在第二步就中断报错。
技能描述过长直接触发 Context limit exceeded
打开 skills/ 目录下任意一个 Skill 文件夹，检查 SKILL.md 里的 description 字段。若该字段超过 3 行、含多段说明或嵌入代码块，它会被模型在加载阶段全文读取并计入 token。千问3.5-9B、Qwen2.5-7B 等本地小模型上下文上限普遍为 8K–32K，而一个未压缩的 Skill 描述平均占 300–900 tokens；加载 5 个同类技能，光描述就吃掉近 4K tokens，再叠加用户输入和系统提示，必然爆仓。
执行 /context 查看当前会话 token 占用，若 loaded_skills: 8 对应的 tokens used 超过 1200，且总用量已超模型上限 60%，即可确认是技能描述拖垮了上下文。
删掉所有示例代码块、多行说明、版本兼容性备注——这些内容不会被模型读取，但会真实计入 token。
SKILL.md 里 trigger_keywords 写太多反而降低命中率
方法一：只保留 2～3 个高区分度关键词
比如写一个「自动补全 Git 提交信息」Skill，不要堆砌“git commit”“提交代码”“帮我写 message”“生成 commit log”“conventional commits”，而是选最常被你口头说出来的 2 个：“review commit”“补提交”。AionClaw 的 trigger 匹配是模糊语义匹配，关键词越多，模型越容易在歧义中误判，反而错过真正意图。
方法二：避免使用停用词或泛动词
像“帮我”“请”“一下”“现在”这类词不携带语义特征，加入后不仅不提升命中率，还会稀释关键词权重。实测显示，去掉这三类词后，trigger 响应延迟下降 40%，误触发率归零。
scripts/ 下脚本逻辑耦合外部工具导致执行失败
第一步：确认脚本是否依赖未声明的命令行工具
例如你在 analyze.py 里直接调用 pdftotext，但没在 SKILL.md 的 tools 字段写明 - pdftotext，AionClaw 就不会提前校验环境，运行时直接报 command not found。
第二步：检查脚本是否硬编码路径
写成 open("/home/user/docs/report.pdf") 或 os.chdir("C:\temp") 是危险操作。AionClaw 的执行沙箱路径每次不同，【绝对不能依赖绝对路径】。应统一用 self.workspace_path 或 OpenClaw 提供的临时目录 API。
第三步：验证 import 是否跨层级失效
如果 scripts/analyze.py 里写了 from utils.helper import clean_text，但项目根目录下没有 utils/ 文件夹，或 helper.py 不在 Python path 中，就会报 ModuleNotFoundError。AionClaw 不自动将 skills/ 父级加入 sys.path，所有依赖必须显式打包进 Skill 文件夹内，或声明为 pip 依赖。
