本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 技能
[代理技能](https://strandsagents.com/docs/user-guide/concepts/plugins/skills/)是降价和脚本的捆绑包，可根据需要为代理提供领域知识。每项技能都遵循开放[AgentSkills.io](https://agentskills.io/specification)标准：一个包含 YAML 前端内容（名称、描述）和降价说明的`SKILL.md`文件，以及可选的`scripts/``references/`、和目录。`assets/`
技能使用渐进式披露：元数据预先注入到系统提示符中（约 100 个代币），并通过工具调用按需加载完整指令。这样可以避免在上下文窗口中充斥代理可能不需要的指令。
安全带支持四种技能来源：
| 来源 | 说明 | 何时使用 |
| --- | --- | --- |
| ** Amazon 技能 ** | Pre-built 使用[Amazon 代理工具包获取 Amazon 服务的技能](https://github.com/aws/agent-toolkit-for-aws/tree/main/skills)。使用全局模式启用。 | 您需要零设置的现成 Amazon 专业知识。 |
| **Git (HTTPS) ** | 从任何公共或私有 Git 存储库克隆技能。支持子目录。 | 您想在不上传到 S3 的情况下参考来自 GitHub或任何 Git 主机的技能。 GitLab |
| **Amazon S3** | 使用执行角色从客户拥有的 S3 存储桶中获取技能。 | 您需要完全控制版本控制、加密和访问管理。 |
| **路径（文件系统）** | 参考工具文件系统中已经存在的技能（嵌入到容器镜像中或通过安装`InvokeAgentRuntimeCommand`）。 | 该技能是您的容器映像的一部分，或者是在会话开始时安装的。 |
每次会话在第一次调用时获取一次技能。在一个会话中，技能会在多次调用后保留在磁盘上。当虚拟机到期并开始新的会话时，将重新获取技能以保证新鲜度。
您可以将安全带（通过`CreateHarness`或`UpdateHarness`）设置`skills`为默认值，也可以将每次调用设置为覆盖。 Invoke-time 技能附加在创建时技能之后；如果两者都定义了同名的技能，则调用时版本获胜。
**注意**
要以交互方式向安全带添加技能，请运行`agentcore`打开 TUI，选择 “**添加**”，选择 “**安全带”**，进入**高级设置**，然后启用 ** “技能”。**然后，向导会提示您输入技能来源。有关每个源的步骤，请参阅以下 [ Git ](#harness-skills-git) 和 [ Amazon S3 ](#harness-skills-s3) 下的 ** “**交互” 选项卡。
## Amazon 技能
Amazon 技能是预先建立的技能，使您的代理能够与 Amazon 服务进行交互。它们是按层次结构组织的，并通过全局模式进行选择。在上查看他们的来源 [ GitHub](https://github.com/aws/agent-toolkit-for-aws/tree/main/skills).
| 类别 | 模式 | 典型技能 |
| --- | --- | --- |
| 核心技能 | `core-skills/*` | EC2、S3、Lambda、DynamoDB CloudWatch、IAM 操作。 |
| 分析技能 | `specialized-skills/analytics-skills/*` | Athena、Glue QuickSight、数据湖运营。 |
| 操作技能 | `specialized-skills/operations-skills/*` | 故障排除、诊断、日志分析。 |
| 存储技能 | `specialized-skills/storage-skills/*` | S3、EFS、FSx、备份操作。 |
### 全部启用 Amazon 技能
**Example**
```
aws bedrock-agentcore-control create-harness \
--harness-name "MyHarness" \
--execution-role-arn "${ROLE_ARN}" \
--skills '[{"awsSkills": {}}]'
```
或者在调用时：
```
response = client.invoke_harness(
harnessArn=HARNESS_ARN,
runtimeSessionId=SESSION_ID,
skills=[{"awsSkills": {}}],
messages=[{"role": "user", "content": [{"text": "List my EC2 instances and their status."}]}],
)
```
### 按类别启用技能
使用全局模式启用特定的技能类别：
**Example**
```
aws bedrock-agentcore-control create-harness \
--harness-name "MyHarness" \
--execution-role-arn "${ROLE_ARN}" \
--skills '[{"awsSkills": {"paths": ["core-skills/*", "specialized-skills/operations-skills/*"]}}]'
```
### 启用一项特定技能
```
response = client.invoke_harness(
harnessArn=HARNESS_ARN,
runtimeSessionId=SESSION_ID,
skills=[{"awsSkills": {"paths": ["core-skills/aws-cdk"]}}],
messages=[{"role": "user", "content": [{"text": "Create a CDK stack for a Lambda function."}]}],
)
```
### 组合多个图案
```
skills=[{"awsSkills": {"paths": ["core-skills/aws-cdk", "core-skills/aws-serverless", "specialized-skills/storage-skills/*"]}}]
```
**注意**
路径必须是相对的（没有前导`/`或`..`）。绝对路径和路径遍历被拒绝。
如果 glob 模式不匹配任何技能，则调用失败并出现描述性错误。
同一有效载荷中的多个`awsSkills`条目被合并。
## Git (HTTPS) 技能
从任何公共或私有 Git 存储库克隆技能。使用稀疏签出支持 monorepos 中的子目录。
**Example**
公共存储库：
```
response = client.invoke_harness(
harnessArn=HARNESS_ARN,
runtimeSessionId=SESSION_ID,
skills=[
{"git": {"url": "https://github.com/anthropics/skills", "path": "skills/docx"}},
],
messages=[{"role": "user", "content": [{"text": "Summarize the attached DOCX file."}]}],
)
```
私有存储库（需要存储在 I [ AgentCore dentity 中的个人访问令牌](https://docs.amazonaws.cn/bedrock-agentcore/latest/devguide/identity.html)）：
```
skills=[
{
"git": {
"url": "https://github.com/my-org/internal-skills",
"path": "excel",
"auth": {
"credentialArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:token-vault/default/apikeycredentialprovider/my-github-pat"
},
}
}
]
```
使用附加 Git 公共 Git 存储库中的技能`agentcore add skill`。`--git-path`用于从子目录中提取一项技能：
```
agentcore add skill --harness my-harness \
--git https://github.com/anthropics/skills \
--git-path skills/docx
agentcore deploy
```
对于私有仓库，在您的项目中传递`--credential`包含个人访问令牌的 API 密钥凭证的名称（`--username`可选，默认`oauth2`）：
```
agentcore add skill --harness my-harness \
--git https://github.com/my-org/internal-skills \
--git-path excel \
--credential my-github-pat
agentcore deploy
```
`agentcore remove skill`使用相同的来源标志移除技能。要在不更改工具的情况下覆盖单次调用的技能，请使用`agentcore invoke --skills `（逗号分隔的路径、`s3://` URI 或 `https://` Git URL）；调用覆盖不支持 Git 身份验证。
在 TUI 中，通过添加 ** → 工具**向导将 Git 技能**添加到**工具中。
1. 前进到**高级设置**，移至 “**技能”**，按**空格键**将其启用，然后**按 Enter **。
1. 选择 ** Git ** 作为技能来源。
1. 输入 HTTPS 存储库 URL。然后，向导会提示输入可选的子目录路径、私有仓库的可选凭据和可选的用户名。
确认向导，然后运行`agentcore deploy`进行申请。
+ `url`（必填）-Git 存储库的 HTTPS 网址。
+ `path`（可选）-包含技能的存储库中的子目录。如果省略，则使用存储库根目录。
+ `auth.credentialArn`（可选）-持有私人存储库个人访问令牌的 API 密钥凭证提供商的 ARN。
+ `auth.username`（可选）-git 用户名，默认为`oauth2`。
Git 提取必须在 60 秒内完成。如果存储库需要互联网出口，请确保您的 VPC 具有 NAT 网关（与远程 MCP 服务器和自定义容器提取的要求相同）。
## 亚马逊 S3 技能
从客户拥有的 S3 存储桶中获取技能。使用工具执行角色证书。
**Example**
```
response = client.invoke_harness(
harnessArn=HARNESS_ARN,
runtimeSessionId=SESSION_ID,
skills=[
{"s3": {"uri": "s3://my-skills-bucket/skills/company-style/"}},
],
messages=[{"role": "user", "content": [{"text": "Draft a summary following our style guide."}]}],
)
```
使用以下命令附加 S3 中的技能`agentcore add skill --s3`：
```
agentcore add skill --harness my-harness \
--s3 s3://my-skills-bucket/skills/company-style/
agentcore deploy
```
存储桶`s3:ListBucket`上的执行角色需要`s3:GetObject`和。请参阅[安全性和访问控制](harness-security.md)。
在 TUI 中，通过添加 ** → 安全带**向导将 S3 技能**添加到**安全带。进入**高级设置**，启用 Skills ** wit ** h ** Space**，然后选择 ** S3 ** 作为源代码（有关这些共享步骤，请参阅 [ Git ](#harness-skills-git) Interactive 选项卡）。
1. 输入技能目录的 S3 URI。
确认向导，然后运行`agentcore deploy`进行申请。
+ `uri`（必填）-指向技能目录的 S3 URI（例如，`s3://bucket/prefix/`）。
+ 执行角色必须对存储桶拥有`s3:GetObject`和`s3:ListBucket`权限。请参阅[安全性和访问控制](harness-security.md)。
+ 每个 S3 技能必须为 1 GB 或更小。
+ S3 源与 S3 VPC 终端节点配合使用（不需要 NAT 网关）。
## 文件系统路径技巧
参考工具文件系统中已经存在的技能-已嵌入到容器镜像中或在会话启动时安装`InvokeAgentRuntimeCommand`。
**Example**
```
response = client.invoke_harness(
harnessArn=HARNESS_ARN,
runtimeSessionId=SESSION_ID,
skills=[{"path": ".agents/skills/xlsx"}],
messages=[{"role": "user", "content": [{"text": "Find errors in the Excel files."}]}],
)
```
### 烘焙到容器镜像中
在您的自定义镜像中包含技能目录：
```
COPY skills/xlsx .agents/skills/xlsx
```
### 在会话启动时安装
在第一次代理调用`InvokeAgentRuntimeCommand`之前使用：
```
agentcore invoke --exec --harness my-agent --session-id "$SESSION" \
"git clone --depth 1 https://github.com/anthropics/skills /tmp/skills && cp -r /tmp/skills/skills/xlsx .agents/skills/xlsx"
```
## 合并多个技能来源
所有四种源类型可以共存于单个有效载荷中：
```
response = client.invoke_harness(
harnessArn=HARNESS_ARN,
runtimeSessionId=SESSION_ID,
skills=[
{"awsSkills": {"paths": ["core-skills/aws-cdk"]}},
{"git": {"url": "https://github.com/anthropics/skills", "path": "skills/docx"}},
{"s3": {"uri": "s3://my-bucket/skills/company-style/"}},
{"path": ".agents/skills/xlsx"},
],
messages=[{"role": "user", "content": [{"text": "Help me with this project."}]}],
)
```
## 错误处理
所有提取失败都会导致调用失败，并出现描述性错误。技能永远不会被默默跳过。
| Failure | 错误消息 |
| --- | --- |
| S3 访问被拒 | `Failed to fetch skill: AccessDeniedException. Ensure execution role has s3:GetObject permission.` |
| 未找到 S3 对象 | `Skill source not found: s3://…` |
| Git 克隆失败（网络） | `Failed to clone skill: could not resolve host` |
| Git 身份验证被拒绝 | `Failed to clone skill: authentication failed` |
| 在 repo 中找不到 Git 路径 | `Skill path 'x' not found in repository` |
| Git 超时 (60s) | `Failed to clone skill: operation timed out after 60s` |
| 技能超过 1 GB 限制 | `Skill exceeds 1GB size limit` |
| Amazon 技能路径什么都不匹配 | `AWS skill path 'x' matched no skills` |
| 路径遍历 () `..` | `Invalid AWS skill path: must be a relative path without '..'` |
| Amazon 技能包不见了 | `AWS Skills are not available in this runtime (missing directory: /opt/amazon/skills)` |
### 相关主题
+ [工具](harness-tools.md)-连接 MCP 服务器、网关、浏览器和代码解释器
+ [环境和文件系统](harness-environment.md)-自定义容器镜像和环境配置
+ [内存](harness-memory.md)-在会话之间持续对话
+ [安全性和访问控制](harness-security.md)-技能来源的执行角色政策
+ [API 文档](harness-get-started.md#api-documentation)