# 技能
[特工技能是按需向代理](https://strandsagents.com/docs/user-guide/concepts/plugins/skills/)提供领域知识的降价和脚本捆绑包。每种技能都遵循开放[AgentSkills.io](https://agentskills.io/specification)标准：一个包含 YAML frontmatter（名称、描述）和 markdown 指令的`SKILL.md`文件，以及可选的`scripts/``references/`、和目录。`assets/`
技能使用渐进式披露：元数据预先注入系统提示符（约100个令牌），并通过工具调用按需加载完整的指令。这样可以避免在上下文窗口中充斥代理可能不需要的指令。
安全带支持四种技能来源：
| 来源 | 说明 | 何时使用 |
| --- | --- | --- |
| ** AWS 技能** | Pre-built [AWS 代理工具包](https://github.com/aws/agent-toolkit-for-aws/tree/main/skills)中的 AWS 服务技能。使用全局模式启用。 | 您需要无需设置即可获得现成的 AWS 专业知识。 |
| **Git (HTTPS)** | 从任何公共或私有 Git 仓库中克隆技能。支持子目录。 | 你想在不上传到 S3 的情况下引用 GitHub GitLab、或任何 git 主机的技能。 |
| **Amazon S3** | 使用执行角色从客户拥有的 S3 存储桶中获取技能。 | 您需要完全控制版本控制、加密和访问管理。 |
| **路径（文件系统）** | 引用已存在于线束文件系统中的技能（嵌入到容器镜像中或通过安装在容器镜像中`InvokeAgentRuntimeCommand`）。 | 该技能是您的容器镜像的一部分，或者是在会话开始时安装的。 |
第一次调用时，每次会话会获得一次技能。在一个会话中，技能会在多次调用后保留在磁盘上。当虚拟机过期并且新会话开始时，会重新获取技能以保证新鲜度。
您可以将安全带设置`skills`为默认值（通过`CreateHarness`或`UpdateHarness`），也可以根据每次调用进行覆盖。 Invoke-time 技能附加在创建时间技能之后；如果两者都定义了同名的技能，则调用时版本获胜。
**注意**
****要以交互方式向安全带添加技能，请运行`agentcore`打开 TUI，选择 “**添加**”，选择 “Harness”，进入**高级设置**，然后启用 “技能”。****然后，向导会提示输入技能来源。有关每个来源的步骤，请参阅下方 [Git](#harness-skills-git) 和 [Amazon S3](#harness-skills-s3) 下的 “**互动**” 选项卡。
## AWS 技能
AWS 技能是预先构建的技能，可让您的代理与 AWS 服务进行交互。它们按层次组织并通过全局模式进行选择。在上查看他们的来源 [GitHub](https://github.com/aws/agent-toolkit-for-aws/tree/main/skills).
| 类别 | 模式 | 典型技能 |
| --- | --- | --- |
| 核心技能 | `core-skills/*` | EC2、S3、Lambda、DynamoDB、IAM 操作。 CloudWatch |
| 分析技能 | `specialized-skills/analytics-skills/*` | Athena、Glue、 QuickSight、数据湖操作。 |
| 操作技巧 | `specialized-skills/operations-skills/*` | 故障排除、诊断、日志分析。 |
| 存储技能 | `specialized-skills/storage-skills/*` | S3、EFS、FSx、Backup 操作。 |
### 全部启用 AWS 技能
**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."}]}],
)
```
私有存储库（需要存储在 Ident [AgentCore ity](https://docs.aws.amazon.com/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 存储库的技能`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 或 Gi `https://` t URL）；调用覆盖不支持 Git 身份验证。
在 TUI 中，通过添加 → Harness 向导将 Git 技能**添加到****安全带**。
1. 前进到**高级设置**，移至**技能**，然后按**空格**键将其启用，然后**按 Enter**。
1. 选择 **Git** 作为技能来源。
1. 输入 HTTPS 存储库网址。然后，向导会提示输入可选的子目录路径、私有存储库的可选凭据和可选的用户名。
确认向导，然后运行`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:GetObject`存储桶`s3:ListBucket`上的 and。请参阅[安全性和访问控制](harness-security.md)。
在 TUI 中，通过添加 → Harness 向导将 S3 技能**添加到****安全带**。进入**高级设置**，启用 “带**空间**的**技能**”，然后选择 **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` |
| 在存储库中找不到 Git 路径 | `Skill path 'x' not found in repository` |
| Git 超时 (60 秒) | `Failed to clone skill: operation timed out after 60s` |
| 技能超过 1 GB 上限 | `Skill exceeds 1GB size limit` |
| AWS 技能路径不匹配 | `AWS skill path 'x' matched no skills` |
| 路径遍历 () `..` | `Invalid AWS skill path: must be a relative path without '..'` |
| AWS 技能包丢失 | `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)