企业官网建设流程全解析

Agentic Awesome Skills 常见问题全解：安装路径、风险标签、调用方式与故障排查实战指南

【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,115+ agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/gh_mirrors/an/agentic-awesome-skills

本篇指南围绕 Agentic Awesome Skills（AAS）官方 FAQ（越南语版 FAQ.vi.md）展开，系统回答关于 Skills 概念、多工具安装、风险分级、调用方式、更新维护与贡献规范的高频问题，并结合作品仓库内安装器源码与真实 SKILL.md 结构给出可验证的实操依据。读完本文，你将能明确判断自己的 AI 工具该把 Skills 装到哪个目录、如何用@skill-id正确调用、如何通过 Risk Labels 甄别高危技能，以及遇到"AI 不识别技能""PR 未通过质量检查"时如何快速定位并解决。

一、Skills 到底是什么？FAQ 通用问题精讲

1.1 "Skills（技能）"的确切定义

FAQ 给出了一个通俗而准确的定义：Skills 是教 AI 助手处理特定任务的专用指令文件，可以把它们理解为一组可随时按需加载的"专家知识模块"。类比现实生活：就像你会在不同场景咨询律师、医生或机械师一样，这些 Skills 让 AI 在需要时成为不同领域的专家。

在仓库中，每个 Skill 就是一个目录下的SKILL.md文件。以 skills/brainstorming/SKILL.md 为例，它的 YAML frontmatter 包含name、description、risk、source、date_added等字段，正文则完整定义了该技能的 Purpose、执行流程、退出条件和关键原则——这正是 FAQ 中"技能就是指令文件"说法的直接证据。

1.2 我需要把 2000+ 个 Skills 全部安装吗？

不需要。当仓库被安装后，所有 Skills 都是"可用"状态，但 AI 只会在你通过@skill-name显式请求时才加载它们。FAQ 用了一个很好的比喻：就像一座图书馆，所有书都在书架上，但你只读自己需要的那些。

补充两个官方建议（来自 FAQ 与英文原版 docs/users/faq.md）：

• 使用 Starter Packs 入门包 只安装符合你角色需要的子集；
• 在英文原版 FAQ 中还有更进一步的工程化约束：不要把所有SKILL.md拼接进单个 system prompt，这几乎必然撑爆模型上下文窗口。正确做法是把 skills_index.json 作为发现用的规范清单，仅在技能被调用（如对话中出现@skill-id）时才加载单个文件。相关契约见 schemas/skills-index.v1.schema.json。

1.3 哪些 AI 工具可以使用这些 Skills？

FAQ 明确列出的兼容工具包括：

• ✅Claude Code（Anthropic 的命令行工具）
• ✅Gemini CLI（Google）
• ✅Codex CLI（OpenAI）
• ✅Cursor（AI 集成 IDE）
• ✅Antigravity IDE
• ✅OpenCode
• 🧪GitHub Copilot（通过 GitHub CLI 的gh skill处于 preview 支持状态）

对 Copilot，FAQ 特别提醒：仓库同时存在 canonical 与 mirror 版本，必须使用准确的路径，只有确定要安装所有发现的技能时才使用--all：

gh skill preview sickn33/agentic-awesome-skills skills/brainstorming/SKILL.md gh skill install sickn33/agentic-awesome-skills skills/brainstorming/SKILL.md --agent github-copilot --scope user --pin v14.2.0

（英文原版 FAQ 还补充了Kiro CLI / IDE（Amazon）与AdaL CLI，并注明 Copilot 为"部分支持（复制粘贴方式）"。）

1.4 免费吗？离线可用吗？

免费。仓库采用 MIT 许可：个人使用免费、商业使用免费、允许修改。英文原版补充了细节：原创代码与工具按 MIT 许可（见 LICENSE），原创文档与非代码内容按 CC BY 4.0 许可（见 LICENSE-CONTENT）。

离线方面：Skill 文件本身存储在你的本地电脑上，但 AI 助手运行仍需联网。

二、安全与信任：Risk Labels 风险标签体系

2.1 Risk Labels（风险标签）代表什么？

AAS 对每个技能做了风险分级，这些值直接映射到每个SKILL.mdfrontmatter 的risk:字段。在 skills/brainstorming/SKILL.md 中可以看到risk: critical的真实写法。分级含义如下：

2.2 这些 Skills 会"黑掉"我的电脑吗？

不会直接执行。Skills 本质是文本文件，但它们会指导AI 运行命令——如果技能内容写着"删除所有文件"，一个顺从的 AI 可能会真的尝试去执行。因此 FAQ 的建议是：始终先看风险标签，并在使用前审查源码内容。

英文原版 FAQ 对这个问题的表述更严谨：Markdown 文件本身不是运行中的进程，但"只是文本"并不能构成完整的安全模型——被加载的技能可以指示 Agent 运行命令、使用凭据、访问网络或修改文件；安装行为本身不等于"发生了任何执行"，只有执行日志与系统变更才是证据。更完整的讨论见英文原版指引对应的安全文档（docs/users/security-and-antivirus.md，越南语版对应 SECURITY.vi.md）。

2.3 安装器如何辅助风险评估？

仓库的安装器 tools/bin/install.js 把风险标签直接做成了安装过滤维度：

• --risk <csv>：只安装匹配这些风险标签的技能（如--risk safe,none）；
• 安装前会生成 Risk Summary，列出待装技能按风险标签的分布统计（对应源码buildRiskSummary函数）；
• 未提供任何选择时，安装器会打印警告，提示完整目录可能包含 offensive 与 unknown 风险技能，并建议优先使用--skills、--risk、--category或--tags；
• 提供audit --skills <ids>静态预检：对选中的技能做模式扫描（命令执行、网络访问、凭据、文件系统写入、提权、破坏性/不可逆操作、二进制文件与符号链接），不会执行任何技能内容，报告后再决定是否安装。

三、安装与设置：路径、工具标志与更新

3.1 默认安装到哪里？

安装器的默认目标路径是 Antigravity 全局目录~/.agents/skills/，一条命令即可完成：

npx agentic-awesome-skills

这个默认行为在安装器源码 tools/bin/install.js 的getTargets()中有直接体现：未指定任何工具标志时，默认目标为path.join(HOME, ".agents", "skills")。

3.2 各工具的专用安装路径

FAQ 给出各工具对应的目录约定：

安装器源码为多数路径提供了对应的--cursor、--claude、--gemini、--codex、--kiro、--antigravity、--agy标志，使用这些标志后无需手动指定目录。例如--codex会解析CODEX_HOME环境变量，未设置时回退到~/.codex/skills。

3.3 Windows 上能否安装？

可以。直接使用标准安装命令：

npx agentic-awesome-skills

FAQ 明确指出：旧方案中的core.symlinks=trueworkaround 或启用 Developer Mode 已不再需要。

3.4 如何更新 Skills？

两种方式，任选其一：

# 方式一：重新运行安装器获取最新版本 npx agentic-awesome-skills # 方式二：若使用 git clone 方式安装，进入目录后拉取 cd ~/.agents/skills git pull origin main

3.5 进阶：精确选择安装（源码级支撑）

FAQ 只给了最基础的安装用法，而安装器 tools/bin/install.js 的实际能力远超于此，这里结合源码补充几个高频实战场景：

只装指定技能（精确 ID/路径）：

npx agentic-awesome-skills --skills brainstorming

--skills接受技能名、ID 或嵌套路径；未知或歧义的值会直接失败关闭（fail closed），同名技能会要求给出更精确的嵌套路径（源码resolveExactSkillSelections）。

按风险/类别/标签过滤安装：

npx agentic-awesome-skills --cursor --risk safe,none npx agentic-awesome-skills --path .agents/skills --category development,backend --risk safe,none npx agentic-awesome-skills --path .agents/skills --tags debugging,typescript-

过滤规则（源码parseSelectorArg/matchesInstallSelectors）：

• 同一标志内逗号分隔的值之间是OR关系；
• 尾缀-表示排除，如legal-表示排除 legal 类；
• --risk、--category、--tags三个标志之间是AND关系；
• 精确选择（--skills）与元数据过滤可以组合，也是 AND 关系。

安装前预览（不写盘）：

npx agentic-awesome-skills --skills brainstorming --dry-run npx agentic-awesome-skills --all --dry-run

--dry-run会为每个目标预览将要发生的安装/更新/移除，但不写入任何文件——这是 FAQ"先审查再安装"原则的工程化落地。

固定版本发布（身份校验）：

npx agentic-awesome-skills --release 4.6.0 --skills brainstorming

默认与--release安装采用"fail closed"策略：克隆出的 Git commit 必须与 npm 上该精确版本记录的不可变gitHead一致，否则拒绝安装未经审查的内容；而--tag会跳过该身份校验并打印警告，因为它接受可变 Git 引用。

Antigravity 的特别要求：由于完整目录可能撑爆宿主上下文导致启动缓慢、截断错误甚至崩溃循环，安装器对 Antigravity 目标强制要求提供--skills、元数据过滤或显式--all同意（源码assertAntigravityInstallSelection）。推荐流程是：让配置了只读 AAS Core MCP 的 Codex/Claude Agent 审查项目、从完整目录中挑选精确 skill ID，然后用--dry-run预览，确认后再去掉--dry-run正式安装。

四、使用 Skills：调用、组合与选择

4.1 如何调用一个技能？

使用@符号加技能名：

@brainstorming 帮我设计一个 todo 应用

4.2 能否同时使用多个技能？

可以。在同一条对话中连续引用多个技能：

@brainstorming 帮我设计这部分，然后用 @writing-plans 生成任务清单

4.3 如何判断该用哪个技能？

FAQ 给出三步法：

1. 浏览目录：查看 Skill 目录 CATALOG.md；
2. 搜索：ls skills/ | grep "关键词"；
3. 直接问 AI："你有没有测试（testing）方面的技能？"

英文原版 FAQ 补充：使用 AAS Core 时，可描述项目目标与约束，让 Agent 搜索并阅读完整目录、挑选精确 ID 并调用compose_stack，在批准栈之前审查 Agent 的理由与提议的 ID。仓库顶层skills/目录下有 2000+ 个技能子目录（当前仓库可见 2035 个），足以支撑按需检索。

4.4 Bundles（捆绑包）与 Workflows（工作流）的区别

• Bundles：按角色或领域分组的策展推荐集合，用于回答"该包含哪些技能"；
• Workflows：面向具体成果的有序执行剧本，用于"需要一步步执行"的场景。

FAQ 强调：Bundle 是技能清单而非可独立调用的"超级技能"，不能直接@Essentials或/web-wizard；应从 bundle 中挑选单个技能调用，或安装专门的 bundle 插件。入门起点见 BUNDLES.vi.md 与仓库的 workflows.json 相关文档。

五、故障排查（Troubleshooting）

5.1 AI 助手不识别我的技能

FAQ 归纳了三大常见原因：

1. 安装路径不对：检查你所用工具的文档；尝试安装器默认的~/.agents/skills/或对应工具标志；
2. 需要重启：安装完成后重启 AI/IDE；
3. 拼写错误：是否把@brainstorming打成了@brain-storming？

5.2 技能给出了错误或过时的建议

请前往仓库的 Issues 页面提交反馈，并附上：

• 是哪个技能（which skill）；
• 发生了什么（what went wrong）；
• 预期应该发生什么（what should happen instead）。

5.3 语境过载与崩溃循环（英文原版补充的典型场景）

英文原版 FAQ 记录了两个高发问题及其缓解思路：

• Windows 截断崩溃循环：若宿主反复报TrajectoryChatConverter: could not convert a single message before hitting truncation，需清理损坏的 Local Storage / Session Storage / IndexedDB 状态，并先备份默认 Antigravity Windows 路径（对应英文文档docs/users/windows-truncation-recovery.md）；
• Linux/macOS 语境过载：仅当完整技能库激活时宿主不稳定，应改用激活流程，只让所需 bundle 或技能 ID 保持激活（对应英文文档docs/users/agent-overload-recovery.md，激活脚本见 scripts/activate-skills.sh）。

通用缓解原则：先缩小激活集（如--category development,backend --risk safe,none）、增量添加技能并逐个回归测试、更频繁地开启新会话。

六、参与贡献：Quality Bar 与官方技能更新

6.1 开源新手也能贡献吗？

完全可以。FAQ 明确欢迎新手，推荐从以下低门槛工作入手：

• 修正拼写错误；
• 添加示例；
• 改进文档。

详细指引见 CONTRIBUTING.md。

6.2 我的 PR 为何未通过 "Quality Bar" 检查？

Quality Bar 是仓库自动化的质量控制门禁。技能缺失的内容通常包括：

1. 合法的description（描述）；
2. 使用示例。

本地提交前先运行校验命令：

npm run validate

该命令在 package.json 中定义，实际执行tools/scripts/validate_skills.py。英文原版 FAQ 还补充了第三项：PR 正文需包含默认模板的 Quality Bar 检查清单，另外还有security:docs门禁（npm run security:docs）与skill-review自动检查（针对改动SKILL.md的 PR，审查质量门槛、触发词与危险命令模式）。质量标准的完整说明见 docs/QUALITY_BAR.md。

6.3 能否直接更新 "Official" 官方技能？

不能直接改。从外部来源导入的技能通过 frontmatter 中的source、source_repo、source_type字段标识。若某个技能来自其他供应商或仓库，正确做法是提交 issue 或附带清晰来源的小型 PR，而不是随意修改。在 skills/brainstorming/SKILL.md 中可以看到source: community的真实写法——这就是 provenance（来源）元数据的实际样例。

七、专业技巧速查

FAQ 给出的四条高价值入门路径：

• 构建任何新东西之前，先@brainstorming梳理思路；
• 遇到棘手的 bug，用@systematic-debugging；
• 想要更高质量的代码，尝试@test-driven-development；
• 想创造自己的技能，探索@skill-creator。

结语

FAQ 的核心结论可以浓缩为三句话：Skills 是按需加载的专家指令文件，不必全量安装；风险标签 + 安装器审计 +--dry-run预览构成"先审查后安装"的完整安全链路；先定位正确的安装路径与调用语法，再按 Quality Bar 规范参与贡献。若仍有疑问，可对照英文原版 docs/users/faq.md、入门指南 GETTING_STARTED.vi.md 与使用文档 USAGE.vi.md 继续深入，或在仓库 Discussions 中发起讨论。

【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,115+ agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/gh_mirrors/an/agentic-awesome-skills