#技能与指令文件

这一页说明两类可以写入 Hunea 提示词的外部内容：

1. 指令文件（AGENTS.md / CLAUDE.md）
2. 技能（Agent Skills）

这两类内容各有不同的适用场景。

#两者的区别

业界把后一种东西称为 Agent Skills（可参考 Agent Skills 规范）。常见形态是：一个目录 + 一份 SKILL.md（YAML frontmatter + Markdown 正文）。Claude Code、Codex、Pi 等工具都在用相近约定；Hunea 也兼容其中常见的 .agents/skills/ 发现路径。

如果不需要自定义，可以都不配置。Hunea 内置的核心 system prompt 与工具使用说明已经可以支持基本使用。

#指令文件：AGENTS.md / CLAUDE.md

#查找范围

因此在 monorepo 中，子目录与仓库根目录可以各自放置指令文件；Hunea 会按发现结果加入 instructions 列表。

#生效方式

• 内容会作为 instructions 来源进入 prompt assembly。
• 是否真正写入下一次新会话的 system prompt，取决于 /prompt 中该来源是否启用，以及是否被更高优先级来源遮蔽（shadow）。
• 当前已有内容的会话不会因为刚修改了 AGENTS.md 就自动重新组装。组装状态面向下一次新会话（或当前仍为空的会话）。

如果需要确认是否生效：打开 /prompt，在左侧 Active 列表中查找 instructions，查看其状态是 missing / disabled / shadowed，或在正文预览中是否出现对应内容。

#适合写什么

没有强制模板。常见内容包括：

• 仓库的测试、格式化命令
• 不建议修改的目录
• 提交信息、分支命名等约定
• 回复语言、禁止的危险操作等约束

内容过长会增加上下文占用（可在 /context 中查看 system 侧占比）。较长的专项流程更适合做成 skill，而不是全部写进 AGENTS.md。

#技能（Agent Skills）是什么

Skill 可以理解成：可发现、可按需加载的专项说明包。

设计上常见做法是「渐进披露」：

1. 先只把每个 skill 的 名称 + 描述（以及文件路径）告诉模型，方便它判断「当前任务是否相关」
2. 真正需要时，再读取 SKILL.md 正文（以及正文里引用的同目录其它文件）
3. 这样即使装了很多 skill，也不会一上来就把全部正文塞进上下文

Hunea 里，技能发现片段的语义大致是：列出可用 skill，并提示模型在任务匹配时用 read 工具去加载对应文件；SKILL.md 中若引用相对路径，应按技能目录解析。

这和 AGENTS.md 不同：AGENTS.md 是常驻指令；skill 是「有这项任务时再启用」的专项能力说明。

#Hunea 如何发现技能

每个 skill 是一个目录，目录内需要有 SKILL.md。

同名 skill 在多处出现时，会按发现顺序去重，列表中只保留先发现的一项。

#SKILL.md 格式

需要包含 YAML frontmatter 与 Markdown 正文。Hunea 解析时要求 frontmatter 中至少有非空的 name 与 description：

---
name: rspress-docs-generator
description: 在本仓库中生成或维护 Rspress 文档站点时使用。涉及 rspress.config、docs 目录结构与 _meta.json 时优先加载。
disable-model-invocation: false
---

# Rspress Docs Generator

具体步骤、约定与限制……

需要更长的参考材料时，可放到同目录其它文件，并在正文中写明相对路径，
以便模型用 read 再打开。

字段说明（以 Hunea 当前实现为准）：

业界其它工具还可能支持更多 frontmatter（例如 allowed-tools 等），Hunea 当前以 name / description / disable-model-invocation 为主；请注意，并非所有扩展字段都能在 Hunea 中生效。

#在 Hunea 里怎么用

需要区分：

• @skill名：这一轮你显式附带某本说明
• skill discovery：让模型知道有哪些 skill 可按描述选用
• long-lived skill：把某本说明长期写进 system 侧

自定义 prompt（输入框 # 前缀）是另一条路径，存放在 .hunea/prompts/ 等相关位置，不是 .agents/skills/。两者都可以在 /prompt 中管理，但目录与发现规则不同。

#与 /prompt 的关系

• 改 skill discovery 是否启用、长期 skill 的启用与顺序：在 /prompt 中操作；保存后主要影响之后的新会话。
• 确认组装结果：在 /prompt 中预览 Active 列表与组装正文。
• 修改磁盘上的 SKILL.md 或 AGENTS.md 后，若当前会话已有内容，通常需要 /clear 或新会话后再观察效果。

#一点使用建议

• 仓库级通用约定写 AGENTS.md；只在特定任务需要的流程做成 skill。
• description 建议写具体触发场景（例如“维护 Rspress 文档站点、修改 _meta.json 时使用”），比只写“一个有用的技能”会更实用。
• 正文尽量聚焦步骤与约束；过长的参考材料放到同目录其它文件，在 SKILL.md 里用相对路径引用。
• 全局 ~/.agents/skills/ 适合个人跨项目复用；项目 .agents/skills/ 适合随仓库提交、供协作者共用（也便于与同样扫描 .agents/skills/ 的其它工具共享）。
• 只想自己手动触发、不希望模型自行选用时，设置 disable-model-invocation: true，再用 @ 绑定。
• 若要停用某段 instructions 或 skill：在 /prompt 中禁用即可，不必删除文件。