feat(skills): add ajv-validate and background-task skills with eval framework#5834
feat(skills): add ajv-validate and background-task skills with eval framework#5834
Conversation
- Add ajv-validate.md reference for egg-controller skill covering TypeBox schema definition, @Inject() Ajv pattern, built-in formats, and transform preprocessing - Update egg-controller SKILL.md with ajv validation quick reference and decision tree entry - Add import path guidance to egg-core SKILL.md (use 'egg' not '@eggjs/tegg') - Add 7 ajv-related eval cases (id 19-25) to evals-egg-controller.json - Update CLAUDE.md with skill evaluation workflow and case design principles Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The formatter broke the last row of the common errors table by prepending '## ' to the pipe character. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Move skill writing conventions, reference doc guidelines, and eval workflow from root CLAUDE.md to packages/skills/CLAUDE.md. Claude Code loads subdirectory CLAUDE.md on demand when accessing files in that directory, keeping the root file focused on monorepo-wide concerns. Root CLAUDE.md reduced from 1226 to 1067 lines. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Add references/background-task.md covering common errors, usage, timeout configuration, error handling, and lifecycle explanation - Update egg-core SKILL.md with async task decision tree and BackgroundTaskHelper in quick reference table - Update entry skill routing keywords for background task queries - Add 8 background-task eval cases (id 19-26) to evals-egg-core.json Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…te-docs) Add section explaining the two evaluation environments: with-skill (using packages/skills/ content) and site-docs (using site/docs/ content), with naming conventions and guidance on interpreting results. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Delegate eval execution, grading, and result display to /skill-creator - Remove generate_review.py and directory structure implementation details - Keep only project-specific content: prompt templates, env constraints, eval case design principles - Update egg-workspace directory structure to match /skill-creator format Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly enhances the AI agent capabilities for the Egg framework by introducing two new skills: one for robust parameter validation using Ajv and TypeBox, and another for managing asynchronous background tasks. These additions aim to provide AI assistants with more precise and practical guidance for common development scenarios. Concurrently, the PR streamlines the skill documentation structure and strengthens the evaluation process, ensuring the quality and effectiveness of the AI's code generation and problem-solving abilities. Highlights
Changelog
Activity
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
📝 WalkthroughWalkthroughRestructures and expands the Skills Package documentation in the Egg framework. Replaces the root CLAUDE.md guide with a concise summary, adds comprehensive skill architecture documentation at packages/skills/CLAUDE.md, introduces new reference guides for Ajv parameter validation and background task handling, updates existing skill SKILL.md files with new guidance, and adds evaluation test cases covering these new topics. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
📝 Coding Plan
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment Tip You can disable sequence diagrams in the walkthrough.Disable the |
Deploying egg with
|
| Latest commit: |
2bfa2fb
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://4b8724bf.egg-cci.pages.dev |
| Branch Preview URL: | https://feat-skills-ajv-and-backgrou.egg-cci.pages.dev |
Deploying egg-v3 with
|
| Latest commit: |
2bfa2fb
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://e4b65b11.egg-v3.pages.dev |
| Branch Preview URL: | https://feat-skills-ajv-and-backgrou.egg-v3.pages.dev |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces two new skills, ajv-validate and background-task, for the AI agent, along with their corresponding documentation and evaluation frameworks. The changes also include a significant refactoring of the skills documentation, moving detailed guidelines into a dedicated packages/skills/CLAUDE.md file. My review focuses on ensuring consistency within the new and updated documentation. I've pointed out a couple of minor inconsistencies: one regarding outdated skill descriptions in the new central documentation file, and another where an example doesn't follow a recommended best practice mentioned elsewhere. Overall, this is a well-structured addition that enhances the agent's capabilities and maintainability of the skills documentation.
| - `egg-core/` — 核心概念：模块、依赖注入、生命周期、AccessLevel | ||
| - `controller/` — 实现指导：HTTPController、MCPController、Schedule |
There was a problem hiding this comment.
There are a few minor inconsistencies in this document that could be aligned with the rest of the project's conventions and the changes in this PR:
- The skill descriptions for
egg-coreandegg-controllerare slightly out of date.egg-coreis missing the new background task capability, andegg-controlleris missing the Ajv validation capability. - The skill name
controller/should beegg-controller/to align with the naming convention. This also applies to line 42 and line 99.
| - `egg-core/` — 核心概念：模块、依赖注入、生命周期、AccessLevel | |
| - `controller/` — 实现指导：HTTPController、MCPController、Schedule | |
| - `egg-core/` — 核心概念：模块、依赖注入、生命周期、AccessLevel、后台任务 | |
| - `egg-controller/` — 实现指导：HTTPController、MCPController、Schedule、Ajv 校验 |
| }); | ||
|
|
||
| // 2. 从 Schema 推导类型 | ||
| type CreateUserParams = Static<typeof CreateUserSchema>; |
There was a problem hiding this comment.
This example uses a type alias to derive the TypeScript type from the schema. However, packages/skills/egg-controller/SKILL.md (in the '常见问题排查' table) recommends using interface ... extends Static<...> for better type inference. To maintain consistency and promote best practices, this example should also use an interface.
| type CreateUserParams = Static<typeof CreateUserSchema>; | |
| interface CreateUserParams extends Static<typeof CreateUserSchema> {} |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🧹 Nitpick comments (1)
packages/skills/egg/SKILL.md (1)
29-39: Keep routing tables consistent with the new background-task intent.Line 29 and Line 38 add
BackgroundTaskHelperrouting signals, but the “协议/用例”表 and “快速参考表” still don’t include this scenario. Consider adding one row in each table so all decision sections stay aligned.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/skills/egg/SKILL.md` around lines 29 - 39, The docs added BackgroundTaskHelper to the trigger keywords but did not update the routing decision tables; update both the “协议/用例” table and the “快速参考表” to include a row describing the background-task scenario (use BackgroundTaskHelper, background task/async task, post-response execution) so the routing tables reflect the new background-task intent and remain consistent with the triggers shown in the list; ensure the new rows reference BackgroundTaskHelper and a concise decision/action for routing.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@packages/skills/CLAUDE.md`:
- Line 14: Update the documentation line that currently names the skill
directory as "controller/" to the correct specialized skill name
"egg-controller/" so it matches the frontmatter convention and related files
(e.g., egg-controller/SKILL.md and evals-egg-controller.json); locate the string
in CLAUDE.md (the line listing controller/) and replace it with
"egg-controller/" ensuring the naming is consistent with the rest of the PR.
- Line 115: In CLAUDE.md update the fenced code block that contains the path
"packages/skills/eval/" to include a language specifier (e.g., change the
opening triple backticks from ``` to ```text) so the block renders and lints
correctly; locate the fence in the file CLAUDE.md around the
"packages/skills/eval/" snippet and replace the code fence accordingly.
- Line 172: The fenced code block that begins before the prompt template ("你是
EGG 框架开发专家。你只能通过 Read 工具读取 packages/skills/ 目录下的文件，不能访问 site/docs/ 或项目源码。") is
missing a language specifier; update the opening fence to include a language
(e.g., change ``` to ```text or ```markdown) so the code block renders and lints
correctly in CLAUDE.md.
- Line 183: The fenced code block in CLAUDE.md is missing a language specifier;
update the code fence that currently reads "```" to include a language (e.g.,
"```text" or "```markdown") so the prompt template renders and lints
correctly—locate the code block around the text starting "你是 EGG 框架开发专家..." and
change the opening fence to "```text" as shown in the proposed fix.
---
Nitpick comments:
In `@packages/skills/egg/SKILL.md`:
- Around line 29-39: The docs added BackgroundTaskHelper to the trigger keywords
but did not update the routing decision tables; update both the “协议/用例” table
and the “快速参考表” to include a row describing the background-task scenario (use
BackgroundTaskHelper, background task/async task, post-response execution) so
the routing tables reflect the new background-task intent and remain consistent
with the triggers shown in the list; ensure the new rows reference
BackgroundTaskHelper and a concise decision/action for routing.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 65d6e0cc-ec08-4f13-a48d-ed52b1857a1a
📒 Files selected for processing (9)
CLAUDE.mdpackages/skills/CLAUDE.mdpackages/skills/egg-controller/SKILL.mdpackages/skills/egg-controller/references/ajv-validate.mdpackages/skills/egg-core/SKILL.mdpackages/skills/egg-core/references/background-task.mdpackages/skills/egg/SKILL.mdpackages/skills/eval/evals-egg-controller.jsonpackages/skills/eval/evals-egg-core.json
| - **入口 skill** (`egg/`) — 分析用户意图，通过关键词匹配和决策逻辑路由到专业 skill | ||
| - **专业 skills** — 提供特定领域的深度指导： | ||
| - `egg-core/` — 核心概念：模块、依赖注入、生命周期、AccessLevel | ||
| - `controller/` — 实现指导：HTTPController、MCPController、Schedule |
There was a problem hiding this comment.
Fix skill directory naming to match frontmatter convention.
This line lists controller/ but should be egg-controller/ to match the frontmatter naming convention stated at line 18 (specialized skills prefixed with egg-). Other files in this PR (egg-controller/SKILL.md, evals-egg-controller.json) confirm the correct name is egg-controller.
📝 Proposed fix
- - `controller/` — 实现指导：HTTPController、MCPController、Schedule
+ - `egg-controller/` — 实现指导：HTTPController、MCPController、Schedule📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - `controller/` — 实现指导：HTTPController、MCPController、Schedule | |
| - `egg-controller/` — 实现指导：HTTPController、MCPController、Schedule |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@packages/skills/CLAUDE.md` at line 14, Update the documentation line that
currently names the skill directory as "controller/" to the correct specialized
skill name "egg-controller/" so it matches the frontmatter convention and
related files (e.g., egg-controller/SKILL.md and evals-egg-controller.json);
locate the string in CLAUDE.md (the line listing controller/) and replace it
with "egg-controller/" ensuring the naming is consistent with the rest of the
PR.
|
|
||
| **评测文件结构：** | ||
|
|
||
| ``` |
There was a problem hiding this comment.
Add language specifier to code block.
The fenced code block should specify a language for proper rendering and linting compliance.
📝 Proposed fix
-```
+```text
packages/skills/eval/🧰 Tools
🪛 markdownlint-cli2 (0.21.0)
[warning] 115-115: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@packages/skills/CLAUDE.md` at line 115, In CLAUDE.md update the fenced code
block that contains the path "packages/skills/eval/" to include a language
specifier (e.g., change the opening triple backticks from ``` to ```text) so the
block renders and lints correctly; locate the fence in the file CLAUDE.md around
the "packages/skills/eval/" snippet and replace the code fence accordingly.
|
|
||
| with-skill 环境： | ||
|
|
||
| ``` |
There was a problem hiding this comment.
Add language specifier to code block.
The prompt template should specify a language (e.g., text or markdown) for proper rendering and linting compliance.
📝 Proposed fix
-```
+```text
你是 EGG 框架开发专家。你只能通过 Read 工具读取 packages/skills/ 目录下的文件，不能访问 site/docs/ 或项目源码。📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ``` |
🧰 Tools
🪛 markdownlint-cli2 (0.21.0)
[warning] 172-172: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@packages/skills/CLAUDE.md` at line 172, The fenced code block that begins
before the prompt template ("你是 EGG 框架开发专家。你只能通过 Read 工具读取 packages/skills/
目录下的文件，不能访问 site/docs/ 或项目源码。") is missing a language specifier; update the
opening fence to include a language (e.g., change ``` to ```text or ```markdown)
so the code block renders and lints correctly in CLAUDE.md.
|
|
||
| site-docs 环境： | ||
|
|
||
| ``` |
There was a problem hiding this comment.
Add language specifier to code block.
The prompt template should specify a language (e.g., text or markdown) for proper rendering and linting compliance.
📝 Proposed fix
-```
+```text
你是 EGG 框架开发专家。你只能通过 Read 工具读取 site/docs/ 目录下的文件，不能访问 packages/skills/ 或项目源码。项目文档目录如下：📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ``` |
🧰 Tools
🪛 markdownlint-cli2 (0.21.0)
[warning] 183-183: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@packages/skills/CLAUDE.md` at line 183, The fenced code block in CLAUDE.md is
missing a language specifier; update the code fence that currently reads "```"
to include a language (e.g., "```text" or "```markdown") so the prompt template
renders and lints correctly—locate the code block around the text starting "你是
EGG 框架开发专家..." and change the opening fence to "```text" as shown in the
proposed fix.
There was a problem hiding this comment.
Pull request overview
This PR expands the @eggjs/skills documentation/eval corpus by adding new reference guides for Ajv validation and background tasks, wiring them into the existing skill routing, and documenting the skills authoring + evaluation workflow.
Changes:
- Add new reference docs:
egg-controller/references/ajv-validate.mdandegg-core/references/background-task.md, and link them from the relevantSKILL.mdfiles. - Extend eval suites for
egg-coreandegg-controllerwith new cases covering background-task and ajv-validate scenarios. - Move skills authoring/eval conventions from root
CLAUDE.mdintopackages/skills/CLAUDE.mdand simplify the root doc.
Reviewed changes
Copilot reviewed 9 out of 9 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| packages/skills/eval/evals-egg-core.json | Adds background-task eval cases and updates eval suite description. |
| packages/skills/eval/evals-egg-controller.json | Adds ajv-validate eval cases and updates eval suite description. |
| packages/skills/egg/SKILL.md | Adds routing keywords/coverage for BackgroundTaskHelper. |
| packages/skills/egg-core/references/background-task.md | New BackgroundTaskHelper reference guide (usage, timeout, error handling, rationale). |
| packages/skills/egg-core/SKILL.md | Adds import-path guidance and async-task decision guidance linking to the new reference. |
| packages/skills/egg-controller/references/ajv-validate.md | New Ajv + TypeBox validation reference guide (imports, schema patterns, formats, transforms). |
| packages/skills/egg-controller/SKILL.md | Adds Ajv validation quick reference and troubleshooting entries. |
| packages/skills/CLAUDE.md | New centralized skills writing + evaluation workflow documentation. |
| CLAUDE.md | Removes the moved skills guideline section and replaces it with a pointer to packages/skills/CLAUDE.md. |
You can also share your feedback on Copilot code review. Take the survey.
| ### 完整示例 | ||
|
|
||
| ```typescript | ||
| // app/modules/demo/FooController.ts |
| - **入口 skill** (`egg/`) — 分析用户意图，通过关键词匹配和决策逻辑路由到专业 skill | ||
| - **专业 skills** — 提供特定领域的深度指导： | ||
| - `egg-core/` — 核心概念：模块、依赖注入、生命周期、AccessLevel | ||
| - `controller/` — 实现指导：HTTPController、MCPController、Schedule |
| 通过 `@Inject()` 注入 `BackgroundTaskHelper`，调用 `run()` 方法。`run()` 接受一个异步函数，在请求返回后执行。 | ||
|
|
| this.backgroundTaskHelper.run(async () => { | ||
| // 这里的代码在 HTTP 响应发送后执行 | ||
| // 可以安全访问注入的服务和上下文 | ||
| await this.sendMetrics(data); |
| this.backgroundTaskHelper.run(async () => { | ||
| // 即使这里抛出异常，也不会影响其他后台任务或框架 | ||
| throw new Error('something went wrong'); | ||
| // 错误会被记录为: [BackgroundTaskHelper] background throw error: something went wrong |
| path: '/api/users', | ||
| }) | ||
| async create(@HTTPBody() body: CreateUserParams) { | ||
| // 校验失败自动抛出 AjvInvalidParamError（422） |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## next #5834 +/- ##
=======================================
Coverage 85.62% 85.63%
=======================================
Files 665 665
Lines 13004 13004
Branches 1495 1495
=======================================
+ Hits 11135 11136 +1
+ Misses 1745 1744 -1
Partials 124 124 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
|
|
||
| `packages/skills/` 目录包含 AI agent skills — 纯 markdown 文档，指导 AI 助手使用 Egg 框架。以 `@eggjs/skills` npm 包发布，仅含 `.md` 文件。 | ||
|
|
||
| > **Skill 编写基础知识**：SKILL.md 格式、frontmatter 规范、目录结构、progressive disclosure、写作风格等通用知识请使用 `/ant-skill-creator` skill 获取指导。以下仅记录 Egg 项目特有的约定。 |
There was a problem hiding this comment.
/ant-skill-creator 这是在那里配置的？我试了一下 cc 里面没有出来这个命令
- 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>
Summary
ajv-validate.mdreference for egg-controller skill (Ajv + TypeBox parameter validation)background-task.mdreference for egg-core skill (BackgroundTaskHelper async tasks)packages/skills/CLAUDE.mdChanges
New skill content
egg-controller/references/ajv-validate.md— Common errors table, TypeBox schema definition, built-in formats, transform preprocessingegg-core/references/background-task.md— Common errors table (setTimeout vs run()), timeout config, error handling, lifecycle explanationegg-core/SKILL.md— Added async task decision tree (BackgroundTask vs EventBus vs Schedule), import path guidanceegg-controller/SKILL.md— Added ajv validation quick referenceegg/SKILL.md— Added BackgroundTaskHelper routing keywordsEval cases
packages/skills/CLAUDE.mdwith prompt templates and environment constraintsCLAUDE.md refactoring
packages/skills/CLAUDE.md(loaded on demand by Claude Code)Eval results (iteration-4, 59 cases)
With-skill pass rate: 100% (59/59 based on expected_output)
Test plan
🤖 Generated with Claude Code
Summary by CodeRabbit
Release Notes