Back to Details

agent-skill-stack

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Build an Agent Skill Stack

构建Agent Skill栈

Build the smallest useful stack for the user's actual outcome. Never force a domain example or a fixed lifecycle onto a different request.
为用户的实际成果构建最小可用的Skill栈。切勿将领域示例或固定生命周期强行套用到不同的请求上。

1. Choose the user-facing depth

1. 选择面向用户的展示深度

Default to plain-language mode. Assume the user does not need to understand paths, revisions, hashes, manifests, static analysis, or runtime details.
In plain-language mode, show:
  • what the user is trying to accomplish;
  • the steps in everyday language;
  • which capabilities are already available;
  • which Skills are recommended, optional, overlapping, or unsuitable;
  • how widely each candidate is used;
  • whether it passed an installation safety check and a safe trial;
  • what account access or external actions it may require.
Keep source paths, revisions, file fingerprints, raw scores, audit evidence, and dependency details in the internal record. Show them only when the user asks for technical details or when a specific technical fact is necessary for informed consent.
默认采用通俗语言模式。假设用户无需了解路径、版本修订、哈希值、清单、静态分析或运行时细节。
在通俗语言模式下，展示以下内容：
  • 用户试图达成的目标；
  • 用日常语言描述的步骤；
  • 已具备的能力；
  • 推荐、可选、重叠或不适用的Skill；
  • 每个候选Skill的使用广泛程度；
  • 是否通过安装安全检查和安全试运行；
  • 可能需要的账户权限或外部操作。
将源路径、版本修订、文件指纹、原始分数、审计证据和依赖项细节保留在内部记录中。仅当用户要求查看技术细节，或特定技术事实是知情同意的必要条件时，才展示这些内容。

2. Derive the workflow dynamically

2. 动态推导工作流

Read references/workflow-model.md. Begin with the final result the user wants, not the domain words in the request.
Ask only questions whose answers materially change the result, access boundary, cost, or stack. Derive the workflow backward from success, then validate it forward from the available starting point.
Do not reuse a previous numbered flow. Do not assume that every request needs research, content creation, publishing, analytics, storage, or automation. Add a step only when the user's outcome requires it.
Stop decomposing when a step has one understandable action, one main result, one access boundary, and one observable success condition. Keep the technical capability cards internal; show the user a short plain-language flow.
阅读references/workflow-model.md。从用户想要的最终结果入手，而非请求中的领域词汇。
仅提出那些答案会实质性改变结果、访问边界、成本或Skill栈的问题。从成功结果倒推工作流，然后从可用的起点正向验证。
请勿重复使用之前的编号流程。不要假设每个请求都需要研究、内容创建、发布、分析、存储或自动化。仅当用户的成果需要时才添加步骤。
当一个步骤包含一个易懂的操作、一个主要结果、一个访问边界和一个可观察的成功条件时，停止分解。将技术能力卡片保留在内部；向用户展示简短的通俗语言流程。

3. Search the local index first

3. 优先搜索本地索引

Read references/local-index-and-profiles.md.
If a current local Skill index exists, search it before the filesystem or internet. If it is missing or stale, rebuild it from the relevant Skill roots:
bash
python3 scripts/skill_index.py build \
  --root ~/.codex/skills \
  --root ~/.codex/plugins/cache \
  --root .codex/skills \
  --root ~/.agents/skills \
  --root ~/.hermes/skills \
  --output ~/.codex/skill-index.json
The index stores names, summaries, aliases, scope, capability terms, update time, and internal file fingerprints. It never executes a Skill and stores no usage history.
If the current project has 
.codex/skill-stack.json
, treat its active Skills and routing rules as the first-choice stack. Search outside the profile only for an uncovered capability or when the user asks for alternatives. Treat same-name entries from different local roots as a review item; do not silently merge them.
阅读references/local-index-and-profiles.md。
如果当前存在本地Skill索引，先搜索它，再搜索文件系统或互联网。如果索引缺失或过期，从相关的Skill根目录重建：
bash
python3 scripts/skill_index.py build \
  --root ~/.codex/skills \
  --root ~/.codex/plugins/cache \
  --root .codex/skills \
  --root ~/.agents/skills \
  --root ~/.hermes/skills \
  --output ~/.codex/skill-index.json
该索引存储名称、摘要、别名、范围、能力术语、更新时间和内部文件指纹。它从不执行Skill，也不存储使用历史。
如果当前项目有
.codex/skill-stack.json
，将其活跃Skill和路由规则视为首选栈。仅当存在未覆盖的能力或用户要求替代方案时，才在配置文件外搜索。将来自不同本地根目录的同名条目视为待审核项；请勿静默合并。

4. Map capabilities, including indirect helpers

4. 映射能力，包括辅助工具

For every necessary step, record internally:
  • required input, action, and output;
  • constraints, frequency, and scale;
  • local/read-external/write-external boundary;
  • account, permission, and approval needs;
  • success condition and fallback;
  • predecessor and successor steps.
Then consider cross-cutting needs only where relevant: quality/style, accuracy, compliance, privacy, localization, data quality, orchestration, and observability.
Match Skills by 
input -> operation -> output
, not by title similarity. This allows a Humanizer to match a natural-writing requirement even when the user's domain never appears in its name.
Do not force one Skill per step. A Skill may cover several steps; a step may need a tool, MCP, connector, or general agent capability rather than another Skill.
对于每个必要步骤，在内部记录：
  • 所需的输入、操作和输出；
  • 约束条件、频率和规模；
  • 本地/读取外部/写入外部的边界；
  • 账户、权限和审批需求；
  • 成功条件和 fallback 方案；
  • 前置和后置步骤。
然后仅在相关情况下考虑跨领域需求：质量/风格、准确性、合规性、隐私、本地化、数据质量、编排和可观测性。
通过
输入 -> 操作 -> 输出
匹配Skill，而非标题相似度。这使得即使Skill名称中从未出现用户的领域词汇，文本润色器也能匹配自然写作需求。
请勿强制每个步骤对应一个Skill。一个Skill可能涵盖多个步骤；一个步骤可能需要工具、MCP、连接器或通用Agent能力，而非另一个Skill。

5. Search with four lenses

5. 从四个维度搜索

Read references/discovery-ranking.md. Search each uncovered capability through:
  1. Direct need: the user's domain and action.
  2. Underlying operation: the actual transformation or data task.
  3. Supporting outcome: quality, safety, style, compliance, evaluation, and monitoring.
  4. Connection method: CLI, MCP, API, connector, browser automation, storage, and handoff.
Expand Chinese/English aliases, verbs, nouns, outputs, and adjacent terminology. Search titles, descriptions, headings, and full 
SKILL.md
content when possible.
Use multiple sources because no registry is complete:
  • the local Skill index and installed inventory;
  • GitHub connector or GitHub file/repository search;
  • npx skills find <query>
    and skills.sh;
  • agentskill.sh or another registry when available;
  • OpenCLI for broad web discovery and platform-specific research.
Run browser-backed OpenCLI searches sequentially. Do not log in, add credentials, or enable a connector without user approval.
阅读references/discovery-ranking.md。通过以下四个维度搜索每个未覆盖的能力：
  1. 直接需求：用户的领域和操作。
  2. 底层操作：实际的转换或数据任务。
  3. 支持性成果：质量、安全、风格、合规性、评估和监控。
  4. 连接方式：CLI、MCP、API、连接器、浏览器自动化、存储和交接。
扩展中英文别名、动词、名词、输出和相邻术语。尽可能搜索标题、描述、标题和完整的
SKILL.md
内容。
使用多个来源，因为没有哪个注册表是完整的：
  • 本地Skill索引和已安装清单；
  • GitHub连接器或GitHub文件/仓库搜索；
  • npx skills find <query>
    和skills.sh；
  • agentskill.sh或其他可用注册表；
  • OpenCLI用于广泛的网络发现和特定平台研究。
按顺序运行基于浏览器的OpenCLI搜索。未经用户批准，请勿登录、添加凭据或启用连接器。

6. Verify and rank candidates

6. 验证并排序候选Skill

Treat every search hit as a candidate, not a recommendation. Identify the canonical repository and exact Skill path. Read the full Skill and every executable file that installation would make reachable.
Reject or quarantine a candidate when:
  • its source or claimed capability cannot be verified;
  • its structure cannot be installed;
  • mandatory dependencies are incompatible or unavailable;
  • critical credential access, data upload, prompt injection, destructive action, or obfuscation remains unexplained;
  • its only possible test would publish, send, purchase, delete, or change a real account;
  • license or platform terms make the intended use materially uncertain.
Rank candidates that pass these gates with the rubric in references/discovery-ranking.md. Real-world adoption and community evidence account for 25% of the score. Preserve unknown values as unknown.
Prefer the smallest stack that meets all required success conditions. Classify candidates as:
  • Required: needed to complete the outcome.
  • Helpful: improves quality, safety, or efficiency.
  • Alternative: mutually exclusive substitute.
  • Not recommended: blocked, redundant, incompatible, or too uncertain.
将每个搜索结果视为候选项，而非推荐项。识别规范仓库和确切的Skill路径。阅读完整的Skill以及安装后可访问的每个可执行文件。
当出现以下情况时，拒绝或隔离候选项：
  • 其来源或声称的能力无法验证；
  • 其结构无法安装；
  • 强制依赖项不兼容或不可用；
  • 关键凭证访问、数据上传、提示注入、破坏性操作或混淆行为无法解释；
  • 唯一可能的测试会发布、发送、购买、删除或更改真实账户；
  • 许可证或平台条款使预期用途存在实质性不确定性。
使用references/discovery-ranking.md中的评分标准对通过这些检查的候选项进行排序。实际采用率和社区证据占总分的25%。未知值保留为未知。
优先选择满足所有必要成功条件的最小栈。将候选项分类为：
  • 必需：完成成果所必需的。
  • 有用：提升质量、安全性或效率。
  • 替代：互斥的替代方案。
  • 不推荐：被阻止、冗余、不兼容或不确定性过高。

7. Analyze conflicts and scope

7. 分析冲突和范围

Read references/security-installation.md. Check identity, activation, instruction, resource, dependency, data-format, permission, and compliance conflicts.
Resolve overlap by selecting one primary Skill, defining a narrow handoff to helpers, keeping alternatives mutually exclusive, or not installing the redundant candidate.
Prefer project-local Skills and a project Skill Stack Profile for task-specific capabilities. Use global installation only for capabilities that should be available broadly.
阅读references/security-installation.md。检查身份、激活、指令、资源、依赖项、数据格式、权限和合规性冲突。
通过选择一个主Skill、定义与辅助工具的窄范围交接、保持替代项互斥或不安装冗余候选项来解决重叠问题。
优先选择项目本地Skill和项目Skill栈配置文件来实现任务特定能力。仅对需要广泛可用的能力使用全局安装。

8. Present recommendations in plain language

8. 用通俗语言呈现推荐内容

Default output:
  1. What you want to achieve: one short restatement.
  2. How the work breaks down: a short numbered flow derived for this request.
  3. What you already have: existing useful Skills and uncovered gaps.
  4. Recommended combination: Required, Helpful, Alternative, and Not recommended.
  5. Why these were chosen: fit, adoption, safety check, safe trial, and conflicts in everyday language.
  6. What needs your decision: account access, paid services, external publishing, or installation selection.
Use labels such as 
已具备
, 
推荐
, 
可选
, 
不建议
, 
安全检查通过
, 
安全试跑通过
, and 
最近确认可用
. Do not show a hash or local path in the default response.
Offer 
查看技术详情
when useful. The technical view may include canonical source, revision, file fingerprint, exact destination, raw evidence, dependencies, permissions, and rollback details.
When the user wants a reusable artifact, create a shareable recommendation card from structured JSON:
bash
python3 scripts/render_stack_card.py \
  --input /path/to/stack-card.json \
  --output /path/to/stack-card.svg
Keep the card understandable without technical paths or raw hashes. Include the goal, selected Skills, each role and status, safety boundary, and verification date.
默认输出：
  1. 你的目标：简短重述一次。
  2. 工作分解：为该请求推导的简短编号流程。
  3. 已具备的能力：现有可用的Skill和未覆盖的缺口。
  4. 推荐组合：必需、有用、替代和不推荐的Skill。
  5. 选择理由：用日常语言说明适配度、采用率、安全检查、安全试运行和冲突情况。
  6. 需你决策的事项：账户访问、付费服务、外部发布或安装选择。
使用
已具备
、
推荐
、
可选
、
不建议
、
安全检查通过
、
安全试跑通过
和
最近确认可用
等标签。默认响应中不显示哈希值或本地路径。
在有用时提供
查看技术详情
选项。技术视图可能包括规范源、版本修订、文件指纹、确切目标位置、原始证据、依赖项、权限和回滚细节。
当用户需要可复用的工件时，从结构化JSON创建可共享的推荐卡片：
bash
python3 scripts/render_stack_card.py \
  --input /path/to/stack-card.json \
  --output /path/to/stack-card.svg
确保卡片无需技术路径或原始哈希值即可理解。包含目标、选定的Skill、每个Skill的角色和状态、安全边界以及验证日期。

9. Install only after consent

9. 仅在获得同意后安装

Recommendation does not authorize installation. Follow references/security-installation.md after the user chooses.
Default to staged installation. Allow a one-click batch only when every selected Skill passed the hard gates, has an exact pinned identity, has no unresolved conflict, will not overwrite an existing destination, and the user explicitly approves the batch.
For already downloaded and checked Skill directories, preview first:
bash
python3 scripts/stage_install.py \
  --source /path/to/skill-a \
  --dest ~/.codex/skills \
  --manifest ./skill-stack-lock.json
Repeat with 
--apply
only after approval. Never silently add credentials, accept new permissions, overwrite an installed Skill, or publish/send/delete external data.
After the user selects the stack, offer to create a project profile in dry-run mode:
bash
python3 scripts/project_profile.py \
  --project /path/to/project \
  --name project-stack \
  --skill skill-a \
  --skill skill-b
Use 
--apply
only after the user confirms the profile.
推荐并不授权安装。用户选择后，请遵循references/security-installation.md的要求。
默认采用分阶段安装。仅当每个选定的Skill都通过严格检查、具有确切的固定身份、无未解决的冲突、不会覆盖现有目标位置，且用户明确批准批量安装时，才允许一键批量安装。
对于已下载并检查过的Skill目录，先进行预览：
bash
python3 scripts/stage_install.py \
  --source /path/to/skill-a \
  --dest ~/.codex/skills \
  --manifest ./skill-stack-lock.json
仅在获得批准后添加
--apply
参数执行安装。请勿静默添加凭据、接受新权限、覆盖已安装的Skill，或发布/发送/删除外部数据。
用户选择栈后，提供以试运行模式创建项目配置文件的选项：
bash
python3 scripts/project_profile.py \
  --project /path/to/project \
  --name project-stack \
  --skill skill-a \
  --skill skill-b
仅在用户确认配置文件后添加
--apply
参数执行。

10. Run a recall check

10. 运行召回检查

After installation or profile changes, run a recall check, not a performance benchmark:
  1. a direct request that names the task;
  2. a natural paraphrase that uses different words;
  3. a supporting request that should bring in a helper such as writing quality, fact checking, or compliance.
Confirm that the correct primary and supporting Skills are selected and unrelated Skills stay out. Report a simple result such as 
3/3 种说法都能正确识别
; keep raw prompts and routing details in the technical view.
Do not collect or store user prompt history, hit/miss logs, or routing feedback.
安装或配置文件更改后，运行召回检查，而非性能基准测试：
  1. 直接命名任务的请求；
  2. 使用不同表述的自然转述请求；
  3. 应触发辅助工具（如写作质量检查、事实核查或合规检查）的支持性请求。
确认正确的主Skill和辅助Skill被选中，无关Skill未被触发。报告简单结果，如
3/3 种说法都能正确识别
；将原始提示和路由细节保留在技术视图中。
请勿收集或存储用户提示历史、命中/未命中日志或路由反馈。