346 lines
12 KiB
Markdown
346 lines
12 KiB
Markdown
# 常见问题解答 (FAQ)
|
||
|
||
**有问题？**你并不孤单！这里是关于 Antigravity Awesome Skills 最常见问题的答案。
|
||
|
||
---
|
||
|
||
## 一般问题
|
||
|
||
### "技能"究竟是什么？
|
||
|
||
技能是专门的指令文件，用于教 AI 助手如何处理特定任务。将它们想象成你的 AI 可以按需加载的专业知识模块。
|
||
**简单类比：**就像你可能咨询不同的专家（律师、医生、机械师），这些技能让你的 AI 在需要时成为不同领域的专家。
|
||
|
||
### 我需要安装每个技能吗？
|
||
|
||
**不需要！**当你克隆仓库时，所有技能都可用，但你的 AI 仅在你使用 `@skill-name` 显式调用它们时才加载它们。
|
||
这就像拥有一个图书馆 - 所有书籍都在那里，但你只阅读你需要的那本。
|
||
**专业提示：**使用 [入门包](bundles.md) 首先专注于与你角色匹配的技能。
|
||
|
||
### 捆绑包和工作流有什么区别？
|
||
|
||
- **捆绑包**是按角色或域分类的精选推荐。
|
||
- **工作流**是具体结果的有序执行剧本。
|
||
|
||
当你决定_包括哪些技能_时使用捆绑包。当你需要_逐步执行_时使用工作流。
|
||
|
||
从以下开始：
|
||
|
||
- [bundles.md](bundles.md)
|
||
- [workflows.md](workflows.md)
|
||
|
||
### 技能和 MCP 工具有什么区别？
|
||
|
||
- **技能**是可重用的 `SKILL.md` 剧本，用于指导 AI 助手完成工作流。
|
||
- **MCP 工具**是集成或可调用功能，让助手能够与外部系统交互。
|
||
|
||
当你想要更好的流程、结构和执行质量时使用技能。当你需要访问 API、服务、数据库或其他系统时使用 MCP 工具。当你想要可靠的工作流加上外部功能时，同时使用两者。
|
||
|
||
有关更长的解释，请阅读 [skills-vs-mcp-tools.md](skills-vs-mcp-tools.md)。
|
||
|
||
### 哪些 AI 工具可以使用这些技能？
|
||
|
||
- ✅ **Claude Code** (Anthropic CLI)
|
||
- ✅ **Gemini CLI** (Google)
|
||
- ✅ **Codex CLI** (OpenAI)
|
||
- ✅ **Cursor** (AI IDE)
|
||
- ✅ **Antigravity IDE**
|
||
- ✅ **OpenCode**
|
||
- ✅ **Kiro CLI** (Amazon)
|
||
- ✅ **Kiro IDE** (Amazon)
|
||
- ✅ **AdaL CLI**
|
||
- ⚠️ **GitHub Copilot**（通过复制粘贴部分支持）
|
||
|
||
### 这些技能可以免费使用吗？
|
||
|
||
**可以。**原始代码和工具采用 MIT 许可，原始文档/非代码书面内容采用 CC BY 4.0 许可。
|
||
|
||
- ✅ 免费供个人使用
|
||
- ✅ 免费供商业使用
|
||
- ✅ 你可以修改它们
|
||
|
||
有关归属和第三方许可详细信息，请参阅 [../../LICENSE](../../LICENSE)、[../../LICENSE-CONTENT](../../LICENSE-CONTENT) 和 [../sources/sources.md](../sources/sources.md)。
|
||
|
||
### 这些技能如何避免溢出模型上下文？
|
||
|
||
一些主机工具（例如，在 Jetski/Cortex + Gemini 上构建的自定义代理）可能想要**将每个 `SKILL.md` 文件连接到单个系统提示词中**。
|
||
这**不是**设计使用此仓库的方式，如果你将整个仓库连接到一个提示词中，几乎肯定会溢出模型的上下文窗口。
|
||
|
||
相反，主机应该：
|
||
|
||
- 使用 `data/skills_index.json` 作为**轻量级清单**进行发现；以及
|
||
- **仅在调用技能时**（例如，通过对话中的 `@skill-id`）加载单个 `SKILL.md` 文件。
|
||
|
||
有关具体示例（包括伪代码），请参阅：
|
||
|
||
- [`docs/integrations/jetski-cortex.md`](../integrations/jetski-cortex.md)
|
||
|
||
### 技能可以离线工作吗？
|
||
|
||
技能文件本身存储在你的计算机上，但你的 AI 助手需要互联网连接才能运行。
|
||
|
||
---
|
||
|
||
## 安全与信任
|
||
|
||
### 风险标签是什么意思？
|
||
|
||
我们对技能进行分类，以便你知道你正在运行什么。这些值直接映射到每个 `SKILL.md` 前置元数据中的 `risk:` 字段：
|
||
|
||
- 🔵 **`none`**：纯参考或规划内容 — 无 shell 命令、无变更、无网络访问。
|
||
- ⚪ **`safe`**：非破坏性的社区技能（只读、规划、代码审查、分析）。
|
||
- 🔴 **`critical`**：修改文件、删除数据、使用网络扫描器或执行破坏性操作的技能。**谨慎使用。**
|
||
- 🟣 **`offensive`**：专注于安全性的进攻技术（渗透测试、利用）。**仅授权使用** — 始终确认目标在范围内。
|
||
- ⬜ **`unknown`**：遗留或未分类的内容。在使用前手动检查技能。
|
||
|
||
### 这些技能可以入侵我的计算机吗？
|
||
|
||
**不可以。**技能是文本文件。但是，它们_指示_ AI 运行命令。如果技能说"删除所有文件"，一个顺从的 AI 可能会尝试这样做。
|
||
_始终检查风险标签并审查代码。_
|
||
|
||
---
|
||
|
||
## 安装和设置
|
||
|
||
### 我应该在哪里安装技能？
|
||
|
||
这取决于你如何安装：
|
||
|
||
- **使用安装程序 CLI (`npx antigravity-awesome-skills`)**：
|
||
默认安装目标是 Antigravity 全局库的 `~/.agents/skills/`。
|
||
- **使用特定于工具的标志**：
|
||
使用 `--claude`、`--cursor`、`--gemini`、`--codex`、`--kiro` 或 `--antigravity` 自动定位匹配的工具路径。
|
||
- **使用手动克隆或自定义工作区路径**：
|
||
`.agent/skills/` 对于 Antigravity/自定义设置仍然是一个很好的通用工作区约定。
|
||
|
||
如果你从 npm 收到 404，请使用：`npx github:sickn33/antigravity-awesome-skills`
|
||
|
||
**使用 git clone：**
|
||
|
||
```bash
|
||
git clone https://github.com/sickn33/antigravity-awesome-skills.git .agent/skills
|
||
```
|
||
|
||
**特定于工具的路径：**
|
||
|
||
- Claude Code: `.claude/skills/`
|
||
- Gemini CLI: `.gemini/skills/`
|
||
- Codex CLI: `.codex/skills/`
|
||
- Cursor: `.cursor/skills/` 或项目根目录
|
||
|
||
**Claude Code 插件市场替代方案：**
|
||
|
||
```text
|
||
/plugin marketplace add sickn33/antigravity-awesome-skills
|
||
/plugin install antigravity-awesome-skills
|
||
```
|
||
|
||
此仓库现在包括 `.claude-plugin/marketplace.json` 和 `.claude-plugin/plugin.json`，因此 Claude Code 可以通过插件市场安装相同的技能树。
|
||
|
||
### 这可以在 Windows 上使用吗？
|
||
|
||
**可以。**使用与其他平台相同的标准安装流程：
|
||
|
||
```bash
|
||
npx antigravity-awesome-skills
|
||
```
|
||
|
||
如果你在已删除的符号链接解决方法周围创建了较旧的克隆，请重新安装到新目录或重新运行 `npx antigravity-awesome-skills`。
|
||
|
||
### 我在 Windows 上遇到截断或上下文崩溃循环。如何恢复？
|
||
|
||
如果 Antigravity 或基于 Jetski/Cortex 的主机不断重新打开到：
|
||
|
||
> `TrajectoryChatConverter: could not convert a single message before hitting truncation`
|
||
|
||
使用专用的 Windows 恢复指南：
|
||
|
||
- [`windows-truncation-recovery.md`](windows-truncation-recovery.md)
|
||
|
||
它包括：
|
||
|
||
- 针对损坏的本地存储/会话存储/IndexedDB 状态的手动清理步骤
|
||
- 首先要备份的默认 Antigravity Windows 路径
|
||
- 根据 [issue #274](https://github.com/sickn33/antigravity-awesome-skills/issues/274) 改编的可选批处理脚本
|
||
|
||
### 我在 Linux 或 macOS 上遇到上下文过载。我该怎么办？
|
||
|
||
如果 Antigravity 仅在激活完整技能库时变得不稳定，请切换到激活流程，而不是一次暴露每个技能：
|
||
|
||
- [agent-overload-recovery.md](agent-overload-recovery.md)
|
||
|
||
该指南展示了如何从此仓库的克隆副本运行 `scripts/activate-skills.sh`，以便只有你需要的捆绑包或技能 ID 在 `~/.agents/skills` 中保持活动状态。
|
||
|
||
### Gemini CLI 在几轮之后挂起或说"This is taking a bit longer, we're still on it"。我该怎么办？
|
||
|
||
首先进行快速隔离检查：
|
||
|
||
1. 开始一个全新的 Gemini CLI 对话。
|
||
2. 尝试一个完全没有技能的提示词。
|
||
3. 仅使用一个小技能（例如 `brainstorming`）再次尝试相同的任务。
|
||
4. 临时将你的活动技能集减少到 2-5 个技能并重试。
|
||
|
||
如何解释结果：
|
||
|
||
- 如果即使没有技能，普通 Gemini CLI 也挂起，则问题可能出在 Gemini CLI/运行时方面，而不是此仓库。
|
||
- 如果普通 Gemini 可以工作，但仅当存在技能时或在几轮之后挂起，则可能的原因是对话/上下文增长。
|
||
|
||
在这种情况下：
|
||
|
||
- 保持更小的活动集
|
||
- 更频繁地开始新对话
|
||
- 使用过载指南：[agent-overload-recovery.md](agent-overload-recovery.md)
|
||
|
||
### 如何更新技能？
|
||
|
||
导航到你的技能目录并拉取最新更改：
|
||
|
||
```bash
|
||
cd .agent/skills
|
||
git pull origin main
|
||
```
|
||
|
||
---
|
||
|
||
## 使用技能
|
||
|
||
> **💡 有关包含示例的完整指南，请参阅 [usage.md](usage.md)**
|
||
|
||
### 如何调用技能？
|
||
|
||
使用 `@` 符号后跟技能名称：
|
||
|
||
```bash
|
||
@brainstorming help me design a todo app
|
||
```
|
||
|
||
### 我可以调用整个捆绑包，如 `@Essentials` 或 `/web-wizard` 吗？
|
||
|
||
不可以。捆绑包是技能的精选列表，不是独立的可调用超级技能。
|
||
|
||
通过以下两种方式之一使用它们：
|
||
|
||
- 从捆绑包中选择单个技能并直接调用它们
|
||
- 如果你只想在 Antigravity 中激活该捆绑包的技能，请使用激活脚本
|
||
|
||
示例：
|
||
|
||
```bash
|
||
./scripts/activate-skills.sh --clear Essentials
|
||
./scripts/activate-skills.sh --clear "Web Wizard"
|
||
```
|
||
|
||
### 我可以一次使用多个技能吗？
|
||
|
||
**可以！**你可以调用多个技能：
|
||
|
||
```bash
|
||
@brainstorming help me design this, then use @writing-plans to create a task list.
|
||
```
|
||
|
||
### 我如何知道使用哪个技能？
|
||
|
||
1. **浏览目录**：查看[技能目录](../../CATALOG.md)。
|
||
2. **搜索**：`ls skills/ | grep "keyword"`
|
||
3. **询问你的 AI**："你有哪些关于测试的技能？"
|
||
|
||
---
|
||
|
||
## 故障排除
|
||
|
||
### 我的 AI 助手无法识别技能
|
||
|
||
**可能的原因：**
|
||
|
||
1. **错误的安装路径**：检查你的工具文档。尝试 `.agent/skills/`。
|
||
2. **需要重启**：安装后重启你的 AI/IDE。
|
||
3. **拼写错误**：你是输入了 `@brain-storming` 而不是 `@brainstorming` 吗？
|
||
|
||
### 技能给出了不正确或过时的建议
|
||
|
||
请[打开问题](https://github.com/sickn33/antigravity-awesome-skills/issues)！包括：
|
||
|
||
- 哪个技能
|
||
- 出了什么问题
|
||
- 应该发生什么
|
||
|
||
---
|
||
|
||
## 贡献
|
||
|
||
### 我是开源新手。我可以贡献吗？
|
||
|
||
**当然可以！**我们欢迎初学者。
|
||
|
||
- 修复拼写错误
|
||
- 添加示例
|
||
- 改进文档
|
||
查看有关说明的 [CONTRIBUTING.md](../../CONTRIBUTING.md)。
|
||
|
||
### 我的 PR 未通过"质量标准"检查。为什么？
|
||
|
||
仓库强制执行自动质量控制。你的技能可能缺少：
|
||
|
||
1. 有效的 `description`。
|
||
2. 清晰的使用指导或示例。
|
||
3. PR 主体中的预期 PR 模板检查清单。
|
||
|
||
在推送之前在本地运行 `npm run validate`，并确保你使用默认模板打开了 PR，以便存在质量标准检查清单。
|
||
|
||
### 我的 PR 未通过"安全文档"检查。我该怎么办？
|
||
|
||
在本地运行安全文档门并处理发现的问题：
|
||
|
||
```bash
|
||
npm run security:docs
|
||
```
|
||
|
||
常见修复：
|
||
|
||
- 用更安全的替代方案替换有风险的示例，如 `curl ... | bash`、`wget ... | sh`、`irm ... | iex`。
|
||
- 删除或编辑类似令牌的命令行示例。
|
||
- 对于故意的高风险指导，通过以下方式添加明确的理由：
|
||
|
||
```markdown
|
||
<!-- security-allowlist: reason and scope -->
|
||
```
|
||
|
||
### 我的 PR 触发了 `skill-review` 自动检查。它是什么？
|
||
|
||
从 v8.0.0 开始，GitHub 会自动在任何添加或修改 `SKILL.md` 文件的 PR 上运行 `skill-review` 工作流。它根据质量标准审查你的技能，并标记常见问题 — 缺少部分、触发器弱或有风险的命令模式。
|
||
|
||
**如果它报告发现：**
|
||
|
||
1. 在你的 PR 上打开**检查**选项卡并阅读 `skill-review` 作业输出。
|
||
2. 解决任何**可操作的**发现（缺少"何时使用"、触发器不清晰、被阻止的安全模式）。
|
||
3. 将新提交推送到同一分支 — 检查会自动重新运行。
|
||
|
||
你不需要关闭并重新打开 PR。信息性或仅风格的发现不会阻止合并。
|
||
|
||
### 社区 PR 需要生成的文件，如 `CATALOG.md` 或 `skills_index.json` 吗？
|
||
|
||
**不需要。**社区 PR 应该保持**仅源代码**。
|
||
|
||
**不要**包括生成的注册表工件，例如：
|
||
|
||
- `CATALOG.md`
|
||
- `skills_index.json`
|
||
- `data/*.json`
|
||
|
||
维护者在合并后在 `main` 上重新生成和规范化这些文件。如果你接触文档、工作流或基础设施，请在本地改为运行 `npm run validate:references` 和 `npm test`。
|
||
|
||
### 我可以更新"官方"技能吗？
|
||
|
||
**不可以。**官方技能（在 `skills/official/` 中）是从供应商镜像的。改为打开问题。
|
||
|
||
---
|
||
|
||
## 专业提示
|
||
|
||
- 在构建任何新内容之前使用 `@brainstorming`
|
||
- 在遇到错误时使用 `@systematic-debugging`
|
||
- 尝试 `@test-driven-development` 以获得更好的代码质量
|
||
- 探索 `@skill-creator` 制作你自己的技能
|
||
|
||
**仍然困惑？**[打开讨论](https://github.com/sickn33/antigravity-awesome-skills/discussions)，我们会帮助你！🙌
|