fix(skills): address PR #5834 review feedback

- Fix skill directory naming: controller/ → egg-controller/ in CLAUDE.md
- Fix /ant-skill-creator → /skill-creator reference
- Add language specifiers to fenced code blocks
- Update egg-core/egg-controller descriptions with new capabilities
- Fix BackgroundTaskHelper.run() execution timing: task starts
  immediately, framework waits at Context preDestroy
- Fix error log format to match implementation (no space after colon)
- Fix example file path to match module directory convention
- Remove hardcoded 422 status from AjvInvalidParamError description

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: gxkl

packages/skills/CLAUDE.md

@@ -2,16 +2,16 @@
 
 `packages/skills/` 目录包含 AI agent skills — 纯 markdown 文档，指导 AI 助手使用 Egg 框架。以 `@eggjs/skills` npm 包发布，仅含 `.md` 文件。
 
-> **Skill 编写基础知识**：SKILL.md 格式、frontmatter 规范、目录结构、progressive disclosure、写作风格等通用知识请使用 `/ant-skill-creator` skill 获取指导。以下仅记录 Egg 项目特有的约定。
+> **Skill 编写基础知识**：SKILL.md 格式、frontmatter 规范、目录结构、progressive disclosure、写作风格等通用知识请使用 `/skill-creator` skill 获取指导。以下仅记录 Egg 项目特有的约定。
 
 ## Egg Skills 架构
 
 Skills 采用分层路由模式：
 
 - **入口 skill** (`egg/`) — 分析用户意图，通过关键词匹配和决策逻辑路由到专业 skill
 - **专业 skills** — 提供特定领域的深度指导：
-  - `egg-core/` — 核心概念：模块、依赖注入、生命周期、AccessLevel
-  - `controller/` — 实现指导：HTTPController、MCPController、Schedule
+  - `egg-core/` — 核心概念：模块、依赖注入、生命周期、AccessLevel、后台任务
+  - `egg-controller/` — 实现指导：HTTPController、MCPController、Schedule、Ajv 校验
 
 ## Egg Skill Frontmatter 约定
 
@@ -36,10 +36,10 @@ Skills 采用分层路由模式：
 
 **专业 Skill 两种组织模式：**
 
-| 模式                           | ant-skill-creator 对应 | 适用场景           | SKILL.md 内容           | references/ 用途   |
-| ------------------------------ | ---------------------- | ------------------ | ----------------------- | ------------------ |
-| **概念型**（如 `egg-core/`）   | Reference-Based        | 概念解释、架构理解 | 自包含的深度内容        | 更深入的专题文档   |
-| **索引型**（如 `controller/`） | Workflow-Based         | 多种实现方式的选择 | 精简的决策树 + 快速参考 | 每种实现的详细指南 |
+| 模式                               | ant-skill-creator 对应 | 适用场景           | SKILL.md 内容           | references/ 用途   |
+| ---------------------------------- | ---------------------- | ------------------ | ----------------------- | ------------------ |
+| **概念型**（如 `egg-core/`）       | Reference-Based        | 概念解释、架构理解 | 自包含的深度内容        | 更深入的专题文档   |
+| **索引型**（如 `egg-controller/`） | Workflow-Based         | 多种实现方式的选择 | 精简的决策树 + 快速参考 | 每种实现的详细指南 |
 
 **概念型 Skill 内容结构：**
 
@@ -92,11 +92,11 @@ Skill 的价值 = 文档 + 实践经验 - 重复内容。如果内容和 `site/d
 ## 添加新 Skill
 
 1. 在 `packages/skills/` 下创建目录：`packages/skills/<skill-name>/`
-2. 创建 `SKILL.md`（格式规范参考 `/ant-skill-creator`，frontmatter 遵循上述 Egg 约定）
+2. 创建 `SKILL.md`（格式规范参考 `/skill-creator`，frontmatter 遵循上述 Egg 约定）
 3. 创建 `references/` 目录（初始为空时放置 `.gitkeep`）
 4. 按需在 `references/*.md` 中添加详细参考文档
 5. 更新入口 skill（`egg/SKILL.md`）的路由逻辑以包含新 skill
-6. 如果 skill 涉及 controller 类型，同时更新 `controller/SKILL.md` 决策树
+6. 如果 skill 涉及 controller 类型，同时更新 `egg-controller/SKILL.md` 决策树
 
 ## 添加新 Reference 文档
 
@@ -112,7 +112,7 @@ Skill 的价值 = 文档 + 实践经验 - 重复内容。如果内容和 `site/d
 
 **评测文件结构：**
 
-```
+```text
 packages/skills/eval/
 ├── evals-egg-core.json        # egg-core skill 评测用例
 ├── evals-egg-controller.json  # egg-controller skill 评测用例
@@ -169,7 +169,7 @@ packages/skills/eval/
 
 with-skill 环境：
 
-```
+```text
 你是 EGG 框架开发专家。你只能通过 Read 工具读取 packages/skills/ 目录下的文件，不能访问 site/docs/ 或项目源码。
 
 {egg/SKILL.md 的完整内容}
@@ -180,7 +180,7 @@ with-skill 环境：
 
 site-docs 环境：
 
-```
+```text
 你是 EGG 框架开发专家。你只能通过 Read 工具读取 site/docs/ 目录下的文件，不能访问 packages/skills/ 或项目源码。项目文档目录如下：
 
 {完整的 site/docs/ 文件列表，通过 find site/docs -name '*.md' | sort 生成}

packages/skills/egg-controller/references/ajv-validate.md

@@ -31,7 +31,7 @@ import { Ajv, Type, Static, TransformEnum } from 'egg/ajv';
 ### 完整示例
 
 ```typescript
-// app/modules/demo/FooController.ts
+// app/userModule/UserController.ts
 import {
   HTTPController,
   HTTPMethod,
@@ -66,7 +66,7 @@ export class UserController {
     path: '/api/users',
   })
   async create(@HTTPBody() body: CreateUserParams) {
-    // 校验失败自动抛出 AjvInvalidParamError（422）
+    // 校验失败自动抛出 AjvInvalidParamError
     this.ajv.validate(CreateUserSchema, body);
 
     // 校验通过，body 已经有完整类型提示
@@ -142,5 +142,5 @@ Type.String({
 
 - **Schema 与 Controller 同文件** — Schema 定义放在使用它的 Controller 文件中，保持就近原则
 - **校验在 Controller 层** — 不要在 Service 层做入参校验，Service 信任上层传入的数据
-- **善用 Optional** — 非必填字段用 `Type.Optional()` 包装，避免前端遗漏字段导致 422
+- **善用 Optional** — 非必填字段用 `Type.Optional()` 包装，避免前端遗漏字段导致校验失败
 - **善用 transform** — 对用户输入做 trim 预处理，减少脏数据

packages/skills/egg-core/references/background-task.md

@@ -16,7 +16,7 @@
 
 ### 基本用法
 
-通过 `@Inject()` 注入 `BackgroundTaskHelper`，调用 `run()` 方法。`run()` 接受一个异步函数，在请求返回后执行。
+通过 `@Inject()` 注入 `BackgroundTaskHelper`，调用 `run()` 方法。`run()` 接受一个异步函数，任务会立即开始执行但不阻塞当前流程。框架在请求结束（Context preDestroy）时会等待所有后台任务完成（最多等待 timeout），然后再释放上下文。
 
 ```typescript
 import { BackgroundTaskHelper, Inject, SingletonProto, AccessLevel } from 'egg';
@@ -27,10 +27,9 @@ export class MetricsService {
   private backgroundTaskHelper: BackgroundTaskHelper;
 
   async reportAfterResponse(data: Record<string, unknown>) {
-    // run() 是非阻塞的，调用后立即返回
+    // run() 是非阻塞的，任务立即开始执行但不会被 await
     this.backgroundTaskHelper.run(async () => {
-      // 这里的代码在 HTTP 响应发送后执行
-      // 可以安全访问注入的服务和上下文
+      // 框架会保持上下文存活直到任务完成或超时
       await this.sendMetrics(data);
     });
   }
@@ -86,7 +85,7 @@ BackgroundTaskHelper 内部会捕获所有错误并记录日志，**不会**抛
 this.backgroundTaskHelper.run(async () => {
   // 即使这里抛出异常，也不会影响其他后台任务或框架
   throw new Error('something went wrong');
-  // 错误会被记录为: [BackgroundTaskHelper] background throw error: something went wrong
+  // 错误会被记录为: [BackgroundTaskHelper] background throw error:something went wrong
 });
 
 // 如果需要自定义错误处理
@@ -108,9 +107,9 @@ this.backgroundTaskHelper.run(async () => {
 
 BackgroundTaskHelper 的作用是：
 
-1. 告诉框架"先不要释放上下文"
-2. 排队执行异步任务
-3. 等待完成（或超时）
-4. 然后再释放上下文
+1. `run()` 被调用时，任务立即开始执行（不是延后到响应发送后）
+2. 任务不会被 await，因此不阻塞当前请求的返回
+3. 请求结束时（Context preDestroy），框架等待所有后台任务完成（最多等待 timeout）
+4. 等待结束后才释放上下文
 
-这就是为什么必须用 `backgroundTaskHelper.run()` 而不是 `setTimeout` — 后者绕过了框架的上下文生命周期管理。
+这就是为什么必须用 `backgroundTaskHelper.run()` 而不是 `setTimeout` — 后者绕过了框架的上下文生命周期管理，执行时上下文可能已被释放。