企业官网建设流程全解析

如何在Gajae-Code中编写自定义SKILL.md技能？面向新手的完整教程

【免费下载链接】gajae-codeGajae Code MVP项目地址: https://gitcode.com/gh_mirrors/ga/gajae-code

Gajae-Code 是一个 AI 编程代理 CLI 工具，支持把"专家经验"写成纯文本的SKILL.md 技能文件让 AI 自动发现并执行。本文将手把手教你从零编写一个自定义 SKILL.md 技能：只需要一个 Markdown 文件、两个配置位置、一条调用命令，不需要编译、不需要配置中心，新手也能 5 分钟上手。

1. 什么是 SKILL.md 自定义技能？

在 Gajae-Code（简称 GJC）中，技能（Skill）就是一个放在磁盘上的 Markdown 文件，采用与 Claude Code、OpenAI Codex 相同的文件约定。它不是插件、不是脚本，而是"写给 AI 的操作说明书"：

• 自动发现：文件系统技能发现默认开启，把合法的技能文件放进规范目录，会话就会自动列出它，无需任何注册步骤；
• 一行命令调用：新会话中直接输入/skill:<技能名>即可调用，AI 也会通过skill_discovery工具自行发现；
• 正文即提示词：技能正文会以完整 Markdown 形式注入会话，指导 AI 按你的流程工作。

GJC 自带 4 个工作流技能：autoresearch、deep-interview、ralplan和ultragoal，它们始终可用，且无法被同名的自定义技能覆盖（这是受保护的保留名称，撞名只会产生警告）。

2. 编写技能：一个文件的 3 个关键点

创建自定义技能只需要满足 3 个要求，这也是新手最常踩的坑：

1. YAML frontmatter 必须位于文件第一行（---开头），否则扫描器会直接跳过并给出诊断提示；
2. frontmatter 必须包含name和description，缺少description同样会被跳过；
3. 正文用自然语言写清操作步骤——它会被完整读入上下文，写得像给实习生的 SOP 就对了。

一个最小可用的技能骨架如下（代码量已经压到最小）：

--- name: my-skill description: 当用户需要提交规范化的 Conventional Commits 时使用此技能 --- # My Skill ## 操作步骤 1. 先用 git status 确认变更范围 2. 按 "type(scope): summary" 格式生成提交信息 3. 提交前检查是否包含敏感信息

💡description的写法很关键：它同时是 AI 判断"何时使用这个技能"的依据，建议以"Use when …"句式描述触发场景，可参考官方技能 gjc-sdk-discover 的写法。

3. 技能放在哪里？2 个规范目录

GJC 按"作用域"加载技能，两个规范位置任选其一：

同名技能的优先级规则（先命中者生效，被遮蔽时会有诊断提示而非静默忽略）：

1. 项目级 优先于 用户级；
2. 项目级内部：从cwd向上走到仓库根，离cwd最近的.gjc/skills胜出；
3. 用户级内部：<config>/agent/skills> 旧的<config>/skills> 旧的~/.gjc/skills。

📌 完整的位置表、Claude Code / Codex 目录的导入方式与信任开关说明，见官方文档：docs/skills.md。

4. 最快上手：3 步安装并调用技能

# 第 1 步：放入技能（以项目级为例） mkdir -p .gjc/skills/my-skill # 将第 2 节的骨架保存为 .gjc/skills/my-skill/SKILL.md # 第 2 步：命令行检查发现结果 gjc skills discover

第 3 步：开一个新会话，输入/skill:my-skill即可调用（支持自动补全）。

如果你手头已有 Claude Code（.claude/skills）或 Codex（.codex/skills）格式的技能，GJC不会静默加载它们，但gjc skills discover会把它们识别为"导入候选"，并直接给出对应的cp复制命令，照做即可导入。

5. 调试技巧：技能没出现怎么办？

技能未生效时 GJC 会给出可执行的诊断信息而不是静默跳过，常见原因对照表：

善用这几个排查命令（--json可输出结构化结果）：

gjc skills discover # 查看全部技能与诊断 gjc skills discover --query 关键词 # 按名称/描述过滤 gjc skills discover --limit 10 # 分页查看

6. 进阶：向官方示例技能学写法

仓库里自带了多份高质量技能范例，强烈建议写之前先读一遍：

• sdk-skills/gjc-sdk-author/SKILL.md —— 带模板目录（templates/direct-sdk.ts、direct-sdk.py）的技能写法，展示"技能可以附带模板文件"；
• sdk-skills/manifest.json —— 技能清单文件，说明技能目录如何组织；
• plugins/gajae-code/skills/ —— 插件内置技能（如gjc-sdk-guides的"纯参考资料型"技能）；
• docs/extragoal-skill-template.md —— 一个可一键安装的完整本地技能模板（外部评审门禁），是学习"复杂工作流技能"的最佳范文；
• docs/gjc-dogfood-skill-template.md —— 另一个本地技能模板，演示内部流程固化成技能的模式。

7. 总结：自定义 SKILL.md 技能的核心要点

写技能的心法只有一句：把你自己重复做过的流程，写成一份 AI 能照章操作的说明书。从 10 行的小技能开始，逐渐沉淀成团队共享的项目级资产——这就是 Gajae-Code 技能体系的精髓。🚀

【免费下载链接】gajae-codeGajae Code MVP项目地址: https://gitcode.com/gh_mirrors/ga/gajae-code