如果以上都不适用，则无需采取行动。不要为了创建而创建。

步骤 2：更新 AGENTS.md

更新 AGENTS.md 时，请遵循以下规则：

代码库地图更新

1. 阅读 AGENTS.md 中的当前地图。
2. 使用 find 或 ls（非递归全树）查看实际的顶层结构。
3. 仅更新已更改的部分。不要重写整个地图。
4. 关注：入口点、目录角色、配置文件、测试位置。

添加规范或防护栏

1. 将规则写成一个 简短、命令式的陈述 —— 如果可能，一行搞定。
2. 将其放在正确的部分：
   • 本地规范 → 如何在此仓库中构建、测试、运行或格式化代码
   • 防护栏 → 智能体绝对不能做的事情
   • 模式与陷阱 → 关于代码库的非显而易见的发现
3. 如果某个纠正与现有条目矛盾，请更新现有条目，而不是添加重复项。

质量检查

• 保持条目简洁。智能体每次会话都会阅读此文件——简洁会带来复利效应。
• 一旦有了真实的条目，就移除占位符/示例条目（斜体部分）。
• 不要添加通用建议。每个条目都应该是 特定于此仓库的。

步骤 3：创建新技能

当你确定了一个值得捕捉的可重复工作流程时，使用此流程。

决策：这是技能还是 AGENTS.md 条目？

Is it a multi-step procedure with a clear output?
  → YES → Skill
  → NO  → AGENTS.md entry

Is it specific to HOW this repo works (norms, navigation)?
  → YES → AGENTS.md entry
  → NO  → Skill

Am I unsure?
  → Start as an AGENTS.md entry. Promote to skill if it grows.

创建技能

1. 选择名称。 使用反映工作的动词-名词模式：debug-ci、draft-release-notes、run-migration 等。

2. 创建文件夹和文件：

   skills/<skill-name>/SKILL.md

3. 使用以下结构编写 SKILL.md：

   ---

   name: <skill-name> description: <one-line description of what job this skill does>

   <Skill Name>

   When to use: <clear trigger condition>

   Steps

   1. <Step 1 — be specific and imperative>
   2. <Step 2>
   3. ...

   Output Contract

   <What "done" looks like. Be specific about format, location, and quality.>

4. 优秀技能的关键原则：

 * 围绕 **要完成的工作** 来构建，而不是工具（"调试 CI 失败"，而不是"使用 grep"）

 * 明确 **触发条件** —— 智能体何时应该使用此技能？
 * 定义 **输出契约** —— "完成"是什么样子的？
 * 如果有助于理解，可以包含 **良好输出的示例** 作为资产（放在 `skills/<name>/examples/` 中）
 * 保持步骤 **命令式和具体化** —— 避免模糊的指令

5. 将新技能添加到 AGENTS.md 中的技能表：

     | [<skill-name>](skills/<skill-name>/SKILL.md) | <purpose> | <trigger> |
     

为技能添加脚本或资产

如果某个技能需要确定性执行（不仅仅是 LLM 的判断），请添加脚本：

skills/<skill-name>/
├── SKILL.md          # 操作手册（始终必需）
├── scripts/          # 用于确定性步骤的辅助脚本
│   └── validate.sh
└── examples/         # 展示"良好"质量的参考输出
    └── example-output.md

在 SKILL.md 中引用它们："运行 scripts/validate.sh 来验证输出。"

步骤 4：决定范围 —— 仓库本地 vs 全局 vs 共享

Does this skill only matter for THIS repo?
  → Keep it in skills/ within this repo (repo-local)

Have I felt this pain in another repo too?
  → Promote to ~/.agent/skills/<name>/ (machine-global)
  → Copy the skill folder there

Does my team keep repeating this workflow?
  → Promote to a shared repo or registry (shared)
  → Move the skill folder into the team's shared skills repo

升级清单

当将技能从仓库本地升级到全局时：

1. 从 SKILL.md 中移除任何仓库特定的路径或引用。
2. 使指令足够通用，适用于任何项目。
3. 测试它在没有原始仓库上下文的情况下是否有效。
4. 如果仓库本地版本有仓库特定的定制，请保留它。

步骤 5：验证改进

进行任何更改（更新 AGENTS.md 或新增技能）后：

1. 重新阅读更新后的文件。 它读起来清晰吗？一个新的智能体会话会从中受益吗？

2. 检查矛盾。 新条目是否与任何现有内容冲突？

3. 检查臃肿。 这个文件是否变得太长了？如果 AGENTS.md 超过约 200 行，请考虑： * 归档不再相关的旧陷阱 * 将详细流程移到技能中 * 总结冗长的条目

4. 提交更改 并附上清晰的消息：

   docs: update AGENTS.md with <what you learned>

或

     feat: add <skill-name> skill for <job description>
     

需要避免的反模式

快速参考：复利循环

Work on task
    ↓
Complete task
    ↓
Reflect: Did I wander? Get corrected? Repeat a workflow? Discover a gotcha?
    ↓
    ├── Navigation miss     → Update Codebase Map
    ├── Behavior correction → Add to Local Norms / Guardrails
    ├── Repeated workflow   → Create a Skill
    ├── Surprise discovery  → Add to Patterns & Gotchas
    └── Nothing notable     → Move on
    ↓
Next task starts from a better baseline

"最有价值的技能是观察自己工作的习惯。" 每一次改进都让未来的改进变得更容易。这就是智能体如何实现复利。

每周安装量

276

仓库

grail-computer/…ng-agent

首次出现

2026年2月14日

安全审计

Gen Agent Trust HubFailSocketPassSnykPass

安装于

opencode270

codex270

gemini-cli269

cursor269

github-copilot268

kimi-cli267

• → Create a new skill (see Step 3 below)

If none of these apply, no action is needed. Don't create artifacts for the sake of it.

Step 2: Update AGENTS.md

When updating AGENTS.md, follow these rules:

Codebase Map Updates

1. Read the current map in AGENTS.md.
2. Use find or ls (not recursive full-tree) to see the actual top-level structure.
3. Update only the parts that have changed. Don't rewrite the whole map.
4. Focus on: entry points, directory roles, config files, test locations.

Adding Norms or Guardrails

1. Write the rule as a short, imperative statement — one line if possible.
2. Place it in the correct section:
   • Local Norms → How to build, test, run, or style code in this repo
   • Guardrails → What the agent must NEVER do
   • Patterns & Gotchas → Non-obvious discoveries about the codebase
3. If a correction contradicts an existing entry, update the existing entry rather than adding a duplicate.

Quality Checks

• Keep entries concise. Agents read this every session — brevity compounds.
• Remove placeholder/example entries (italicized) once real entries exist.
• Don't add generic advice. Every entry should be specific to this repo.

Step 3: Create a New Skill

Use this procedure when you've identified a repeatable workflow worth capturing.

Decision: Is This a Skill or an AGENTS.md Entry?

Is it a multi-step procedure with a clear output?
  → YES → Skill
  → NO  → AGENTS.md entry

Is it specific to HOW this repo works (norms, navigation)?
  → YES → AGENTS.md entry
  → NO  → Skill

Am I unsure?
  → Start as an AGENTS.md entry. Promote to skill if it grows.

Creating the Skill

1. Choose a name. Use a verb-noun pattern reflecting the job: debug-ci, draft-release-notes, run-migration, etc.

2. Create the folder and file:

   skills/<skill-name>/SKILL.md
   

3. Write the SKILL.md with this structure:

   ---
   name: <skill-name>
   description: <one-line description of what job this skill does>
   ---
   
   # <Skill Name>
   
   > **When to use:** <clear trigger condition>
   
   ## Steps
   
   1. <Step 1 — be specific and imperative>
   2. <Step 2>
   3. ...
   
   ## Output Contract
   
   <What "done" looks like. Be specific about format, location, and quality.>
   

4. Key principles for good skills:

   • Frame around a job to be done , not a tool ("debug CI failure", not "use grep")
   • Make the trigger clear — when should an agent reach for this?
   • Define the output contract — what does "done" look like?
   • Include examples of good output as assets if helpful (put in skills/<name>/examples/)
   • Keep steps imperative and specific — avoid vague instructions

5. Add the new skill to the skills table in AGENTS.md:

   | [<skill-name>](skills/<skill-name>/SKILL.md) | <purpose> | <trigger> |
   

Adding Scripts or Assets to a Skill

If a skill needs deterministic execution (not just LLM judgment), add scripts:

skills/<skill-name>/
├── SKILL.md          # The playbook (always required)
├── scripts/          # Helper scripts for deterministic steps
│   └── validate.sh
└── examples/         # Reference outputs showing "good" quality
    └── example-output.md

Reference these from SKILL.md: "Run scripts/validate.sh to verify the output."

Step 4: Decide Scope — Repo-Local vs Global vs Shared

Does this skill only matter for THIS repo?
  → Keep it in skills/ within this repo (repo-local)

Have I felt this pain in another repo too?
  → Promote to ~/.agent/skills/<name>/ (machine-global)
  → Copy the skill folder there

Does my team keep repeating this workflow?
  → Promote to a shared repo or registry (shared)
  → Move the skill folder into the team's shared skills repo

Promotion Checklist

When promoting a skill from repo-local to global:

1. Remove any repo-specific paths or references from the SKILL.md.
2. Make the instructions generic enough for any project.
3. Test it works without the original repo's context.
4. Keep the repo-local version if it has repo-specific customizations.

Step 5: Validate the Improvement

After making any changes (AGENTS.md update or new skill):

1. Re-read the updated file. Does it read clearly? Would a fresh agent session benefit from it?

2. Check for contradictions. Does the new entry conflict with anything existing?

3. Check for bloat. Is this file getting too long? If AGENTS.md exceeds ~200 lines, consider:

   • Archiving old gotchas that are no longer relevant
   • Moving detailed procedures into skills
   • Summarizing verbose entries

4. Commit the changes with a clear message:

   docs: update AGENTS.md with <what you learned>
   

or

     feat: add <skill-name> skill for <job description>
     

Anti-Patterns to Avoid

Quick Reference: The Compounding Loop

Work on task
    ↓
Complete task
    ↓
Reflect: Did I wander? Get corrected? Repeat a workflow? Discover a gotcha?
    ↓
    ├── Navigation miss     → Update Codebase Map
    ├── Behavior correction → Add to Local Norms / Guardrails
    ├── Repeated workflow   → Create a Skill
    ├── Surprise discovery  → Add to Patterns & Gotchas
    └── Nothing notable     → Move on
    ↓
Next task starts from a better baseline

"The most valuable skill is the habit of watching yourself work." Each improvement makes future improvements easier. That's how agents compound.

Weekly Installs

276

Repository

grail-computer/…ng-agent

First Seen

Feb 14, 2026

Security Audits

Gen Agent Trust HubFailSocketPassSnykPass

Installed on

opencode270

codex270

gemini-cli269

cursor269

github-copilot268

kimi-cli267