npx skills add https://github.com/google/adk-docs --skill adk-dev-guide如果这是一个长会话,请在每个阶段前重新阅读相关技能——编写代码前阅读 /adk-cheatsheet,运行评估前阅读 /adk-eval-guide,部署前阅读 /adk-deploy-guide,创建脚手架前阅读 /adk-scaffold。上下文压缩可能已丢弃早期的技能内容。
重要提示:如果项目中存在 DESIGN_SPEC.md 文件,它是您的主要事实依据。
首先阅读它以了解:
规格说明就是您的契约。 所有实现决策都应与其保持一致。如有疑问,请查阅 DESIGN_SPEC.md。
在编写任何代码之前:
DESIGN_SPEC.md广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
实现智能体逻辑:
make playground(或 adk web .)进行交互式测试关于 ADK API 模式和代码示例,请使用 /adk-cheatsheet。
这是最重要的阶段。 评估使用评估集和评分指标端到端地验证智能体行为。
强制要求: 在运行评估之前,请激活 /adk-eval-guide。它包含评估集模式、配置格式和关键注意事项。切勿跳过此步骤。
测试(pytest)不等于评估。 它们测试代码正确性,但不能说明智能体行为是否正确。务必运行 adk eval。
adk eval(如果项目有 Makefile,则使用 make eval)预计此处需要 5-10+ 次迭代。
一旦达到评估阈值:
/adk-deploy-guide重要提示: 未经明确的人工批准,切勿部署。
在执行代码修改时,您的首要目标是精准操作。您必须仅更改用户请求直接针对的代码段,同时严格保留所有周围及无关的代码。
强制性的执行前验证:
在最终确定任何代码替换之前,请验证:
model、version、api_key)、注释和格式保持完全相同。示例:
用户请求: "将智能体的指令更改为食谱推荐器。"
错误(违规):
root_agent = Agent(
name="recipe_suggester",
model="gemini-1.5-flash", # 非预期 - 未要求更改模型
instruction="You are a recipe suggester."
)
正确(合规):
root_agent = Agent(
name="recipe_suggester", # 正确,与新用途相关
model="gemini-3-flash-preview", # 已保留
instruction="You are a recipe suggester." # 正确,直接目标
)
模型选择 —— 关键:
gemini-3-flash-preview,请保持为 gemini-3-flash-preview。不要"升级"或"修复"模型名称。gemini-3-flash-preview、gemini-3-pro-preview。gemini-2.0-flash、gemini-1.5-flash 等)。位置比模型更重要:
GOOGLE_CLOUD_LOCATION 问题(例如,需要 global 而不是 us-central1)。gemini-3-flash-preview)需要特定位置。请检查错误消息以获取提示。ADK 内置工具导入(需要精确):
# 正确 - 导入工具实例
from google.adk.tools.load_web_page import load_web_page
from google.adk.tools import load_web_page
将导入的工具直接传递给 tools=[load_web_page],而不是 tools=[load_web_page.load_web_page]。
运行 Python 命令:
uv 执行 Python 命令(例如,uv run python script.py)make install(或 uv sync)Makefile 和 README.md,请查阅其中的可用命令中断无限循环:
terraform import 导入现有资源,而不是重试创建terraform CLI),而不是调用有问题的工具故障排除:
/adk-cheatsheet——它涵盖了大多数常见模式python -c "import google.adk; print(google.adk.__path__[0])" 找到它——如果使用 uv,则使用 uv run python)references/docs-index.md 以获取 WebFetch URL当您需要特定的基础设施文件但不想直接为当前项目创建脚手架时,请使用 /adk-scaffold 技能在 /tmp/ 中创建一个临时的参考项目,并复制您需要的内容。
有关完整的 CLI 命令和选项,请参阅 /adk-scaffold。
通过 Agent Starter Pack CLI 创建的项目包含一个具有以下命令的 Makefile。要创建或增强项目,请参阅 /adk-scaffold 技能以获取完整说明。对于非脚手架项目,请使用 ADK CLI 等效命令。
| Make(脚手架项目) | ADK CLI 等效命令 | 用途 |
|---|---|---|
make playground | adk web . | 交互式本地测试 |
make test | pytest | 运行单元和集成测试 |
make eval | adk eval <agent_dir> <evalset> | 针对评估集运行评估 |
make lint | ruff check . | 检查代码质量 |
make setup-dev-env | —(仅限脚手架项目) | 设置开发基础设施(Terraform) |
make deploy | —(仅限脚手架项目) | 部署到开发环境(需要人工批准) |
故障排除提示: 如果您遇到重复错误、意外工具故障,或者这些技能中的说明看起来不完整或引用了您找不到的功能,则技能可能已过时。请运行:
npx skills check -g如果报告技能过时,请告知用户更新:
npx skills update -g不要在每个会话中都运行此检查——仅当您怀疑过时的技能导致问题时才运行。
每周安装量
1.1K
代码库
GitHub 星标数
1.2K
首次出现
Mar 9, 2026
安全审计
安装于
gemini-cli1.1K
codex1.1K
cursor1.1K
opencode1.1K
github-copilot1.1K
amp1.1K
If this is a long session, re-read the relevant skill before each phase — /adk-cheatsheet before writing code, /adk-eval-guide before running evals, /adk-deploy-guide before deploying, /adk-scaffold before scaffolding. Context compaction may have dropped earlier skill content.
IMPORTANT : If DESIGN_SPEC.md exists in this project, it is your primary source of truth.
Read it FIRST to understand:
The spec is your contract. All implementation decisions should align with it. When in doubt, refer back to DESIGN_SPEC.md.
Before writing any code:
DESIGN_SPEC.md thoroughlyImplement the agent logic:
make playground (or adk web .) for interactive testing during developmentFor ADK API patterns and code examples, use /adk-cheatsheet.
This is the most important phase. Evaluation validates agent behavior end-to-end using evalsets and scoring metrics.
MANDATORY: Activate /adk-eval-guide before running evaluation. It contains the evalset schema, config format, and critical gotchas. Do NOT skip this.
Tests (pytest) are NOT evaluation. They test code correctness but say nothing about whether the agent behaves correctly. Always run adk eval.
adk eval (or make eval if the project has a Makefile)Expect 5-10+ iterations here.
Once evaluation thresholds are met:
/adk-deploy-guide for deployment optionsIMPORTANT : Never deploy without explicit human approval.
When executing code modifications, your paramount objective is surgical precision. You must alter only the code segments directly targeted by the user's request, while strictly preserving all surrounding and unrelated code.
Mandatory Pre-Execution Verification:
Before finalizing any code replacement, verify:
model, version, api_key), comments, and formatting outside the identified target remain identical.Example:
User Request: "Change the agent's instruction to be a recipe suggester."
Incorrect (VIOLATION):
root_agent = Agent(
name="recipe_suggester",
model="gemini-1.5-flash", # UNINTENDED - model was not requested to change
instruction="You are a recipe suggester."
)
Correct (COMPLIANT):
root_agent = Agent(
name="recipe_suggester", # OK, related to new purpose
model="gemini-3-flash-preview", # PRESERVED
instruction="You are a recipe suggester." # OK, the direct target
)
Model Selection — CRITICAL:
gemini-3-flash-preview, keep it as gemini-3-flash-preview. Do NOT "upgrade" or "fix" model names.gemini-3-flash-preview, gemini-3-pro-preview.gemini-2.0-flash, gemini-1.5-flash, etc.) unless the user explicitly requests them.Location Matters More Than Model:
GOOGLE_CLOUD_LOCATION issue (e.g., needing instead of ).Pass the imported tool directly to tools=[load_web_page], not tools=[load_web_page.load_web_page].
Running Python Commands:
uv to execute Python commands (e.g., uv run python script.py)make install (or uv sync) before executing scriptsMakefile and README.md for available commands (if present)Breaking Infinite Loops:
terraform import instead of retrying creationWhen you need specific infrastructure files but don't want to scaffold the current project directly, use the /adk-scaffold skill to create a temporary reference project in /tmp/ and copy over what you need.
See /adk-scaffold for full CLI commands and options.
Projects created via the Agent Starter Pack CLI include a Makefile with these commands. To create or enhance a project, see the /adk-scaffold skill for full instructions. For non-scaffolded projects, use the ADK CLI equivalents.
| Make (scaffolded) | ADK CLI equivalent | Purpose |
|---|---|---|
make playground | adk web . | Interactive local testing |
make test | pytest | Run unit and integration tests |
make eval | adk eval <agent_dir> <evalset> | Run evaluation against evalsets |
make lint |
Troubleshooting hint: If you encounter repeated errors, unexpected tool failures, or instructions in these skills that seem incomplete or reference features you can't find, the skills may be outdated. Run:
npx skills check -gIf it reports outdated skills, tell the user to update:
npx skills update -gDo NOT run this check on every session — only when you suspect stale skills are causing problems.
Weekly Installs
1.1K
Repository
GitHub Stars
1.2K
First Seen
Mar 9, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
gemini-cli1.1K
codex1.1K
cursor1.1K
opencode1.1K
github-copilot1.1K
amp1.1K
React 组合模式指南:Vercel 组件架构最佳实践,提升代码可维护性
102,200 周安装
AI代码审查工具 - 自动化安全漏洞检测与代码质量分析 | 支持多领域检查清单
1,200 周安装
AI智能体长期记忆系统 - 精英级架构,融合6种方法,永不丢失上下文
1,200 周安装
AI新闻播客制作技能:实时新闻转对话式播客脚本与音频生成
1,200 周安装
Word文档处理器:DOCX创建、编辑、分析与修订痕迹处理全指南 | 自动化办公解决方案
1,200 周安装
React Router 框架模式指南:全栈开发、文件路由、数据加载与渲染策略
1,200 周安装
Nano Banana AI 图像生成工具:使用 Gemini 3 Pro 生成与编辑高分辨率图像
1,200 周安装
globalus-central1gemini-3-flash-preview) require specific locations. Check the error message for hints.ADK Built-in Tool Imports (Precision Required):
# CORRECT - imports the tool instance
from google.adk.tools.load_web_page import load_web_page
from google.adk.tools import load_web_page
terraform CLI) instead of calling problematic toolsTroubleshooting:
/adk-cheatsheet first — it covers most common patternspython -c "import google.adk; print(google.adk.__path__[0])" — use uv run python if using uv)references/docs-index.md in the cheatsheet skill for WebFetch URLsruff check . |
| Check code quality |
make setup-dev-env | — (scaffolded only) | Set up dev infrastructure (Terraform) |
make deploy | — (scaffolded only) | Deploy to dev (requires human approval) |