기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# Skills
[에이전트 스킬](https://strandsagents.com/docs/user-guide/concepts/plugins/skills/)은 에이전트 도메인에 온디맨드 지식을 제공하는 마크다운 및 스크립트 번들입니다. 각 스킬은 열린 [AgentSkills.io](https://agentskills.io/specification) 표준, 즉 YAML 프론트미터(이름, 설명) 및 마크다운 지침이 포함된 `SKILL.md` 파일과 선택적 `scripts/`, `references/`및 `assets/` 디렉터리를 따릅니다.
스킬은 점진적 공개를 사용합니다. 메타데이터는 시스템 프롬프트에 미리 주입되고(약 100개의 토큰), 전체 지침은 도구 호출을 통해 온디맨드로 로드됩니다. 이렇게 하면 컨텍스트 창에 에이전트가 필요하지 않을 수 있는 지침이 넘치지 않습니다.
이 하네스는 네 가지 스킬 소스를 지원합니다.
| 출처 | 설명 | 사용해야 하는 경우 |
| --- | --- | --- |
| ** AWS 기술** | [AWS 에이전트 도구](https://github.com/aws/agent-toolkit-for-aws/tree/main/skills) 키트의 AWS 서비스에 대한 사전 구축된 기술입니다. glob 패턴으로를 활성화합니다. | 제로 설정으로 미리 만들어진 AWS 전문 지식을 원합니다. |
| **Git(HTTPS)** | 퍼블릭 또는 프라이빗 Git 리포지토리에서 스킬을 복제합니다. 하위 디렉터리를 지원합니다. | S3에 업로드하지 않고 GitHub, GitLab 또는 모든 git 호스트에서 스킬을 참조하려고 합니다. |
| **Amazon S3** | 실행 역할을 사용하여 고객 소유 S3 버킷에서 스킬을 가져옵니다. | 버전 관리, 암호화 및 액세스 거버넌스를 완벽하게 제어해야 합니다. |
| **경로(파일 시스템)** | 하네스 파일 시스템에 이미 있는 스킬을 참조합니다(컨테이너 이미지에 베이킹되거나를 통해 설치됨`InvokeAgentRuntimeCommand`). | 스킬이 컨테이너 이미지의 일부이거나 세션 시작 시 설치되었습니다. |
스킬은 첫 번째 호출 시 세션당 한 번 가져옵니다. 세션 내에서 스킬은 여러 간접 호출에 걸쳐 디스크에 유지됩니다. VM이 만료되고 새 세션이 시작되면 기술을 다시 가져와 신선도를 보장합니다.
를 기본`skills`값으로 설정하거나( `CreateHarness` 또는를 통해`UpdateHarness`) 호출당 재정의할 수 있습니다. 호출 시간 스킬은 생성 시간 스킬 뒤에 추가됩니다. 둘 다 이름이 같은 스킬을 정의하면 호출 시간 버전이 성공합니다.
**참고**
대화형으로 하네스에 스킬을 추가하려면를 실행`agentcore`하여 TUI를 열고, **추가**를 선택하고, **하네스**를 선택하고, **고급 설정**으로 이동하고, **스킬**을 활성화합니다. 그러면 마법사가 스킬 소스를 묻는 메시지를 표시합니다. 소스별 단계는 아래 [Git](#harness-skills-git) 및 [Amazon S3](#harness-skills-s3) 아래의 **대화형** 탭을 참조하세요.
## AWS 기술
AWS 스킬은 에이전트가 AWS 서비스와 상호 작용할 수 있도록 사전 구축된 스킬입니다. 계층적으로 구성되고 glob 패턴을 통해 선택됩니다. [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, 백업 작업. |
### 모든 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."}]}],
)
```
### 범주별 기술 활성화
glob 패턴을 사용하여 특정 스킬 범주를 활성화합니다.
**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 리포지토리에서 스킬을 복제합니다. 희소 체크아웃을 사용하여 모노리포지토리 내의 하위 디렉터리를 지원합니다.
**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."}]}],
)
```
프라이빗 리포지토리( [AgentCore 자격 증명](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
```
프라이빗 리포지토리의 경우 개인 액세스 토큰을 보유한 프로젝트의 API 키 자격 증명 이름과 `--credential` 함께를 전달합니다(`--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://` URIs 또는 `https://` Git URLs 사용합니다. 간접 호출 재정의에서는 Git 인증이 지원되지 않습니다.
TUI에서 Add → Harness 마법사를 통해 Git 스킬을 **하네스**에 **추가합니다**.
1. **고급 설정**으로 진행하고 **기술** 로 이동한 다음 **스페이스**를 눌러 활성화한 다음 **Enter** 키를 누릅니다.
1. **Git**을 스킬 소스로 선택합니다.
1. HTTPS 리포지토리 URL을 입력합니다. 그러면 마법사가 선택적 하위 디렉터리 경로, 프라이빗 리포지토리에 대한 선택적 자격 증명 및 선택적 사용자 이름을 묻는 메시지를 표시합니다.
마법사를 확인한 다음를 실행`agentcore deploy`하여 적용합니다.
+ `url` (필수) - Git 리포지토리의 HTTPS URL입니다.
+ `path` (선택 사항) - 스킬이 포함된 리포지토리 내의 하위 디렉터리입니다. 생략하면 리포지토리 루트가 사용됩니다.
+ `auth.credentialArn` (선택 사항) - 프라이빗 리포지토리용 개인 액세스 토큰을 보유한 API 키 자격 증명 공급자의 ARN입니다.
+ `auth.username` (선택 사항) - git username, 기본값은 입니다`oauth2`.
Git 가져오기는 60초 이내에 완료해야 합니다. 리포지토리에 인터넷 송신이 필요한 경우 VPC에 NAT 게이트웨이가 있는지 확인합니다(원격 MCP 서버 및 사용자 지정 컨테이너 풀과 동일한 요구 사항).
## Amazon 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 스킬을 **추가합니다**. **고급 설정**으로 이동하여 **스페이스**가 있는 **스킬**을 활성화하고 소스로 **S3**를 선택합니다(이러한 공유 단계는 [Git](#harness-skills-git) 대화형 탭 참조).
1. 스킬 디렉터리의 S3 URI를 입력합니다.
마법사를 확인한 다음를 실행`agentcore deploy`하여 적용합니다.
+ `uri` (필수) - 스킬 디렉터리(예: `s3://bucket/prefix/`)를 가리키는 S3 URI입니다.
+ 실행 역할에는 버킷에 대한 `s3:GetObject` 및 `s3:ListBucket` 권한이 있어야 합니다. [보안 및 액세스 제어](harness-security.md)을(를) 참조하세요.
+ 각 S3 스킬은 1GB 이하여야 합니다.
+ 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."}]}],
)
```
## 오류 처리
모든 가져오기 실패는 설명 오류와 함께 호출에 실패합니다. 스킬은 자동으로 건너뛰지 않습니다.
| 실패 | 오류 메시지 |
| --- | --- |
| 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` |
| 스킬이 1GB 제한을 초과함 | `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) - 사용자 지정 컨테이너 이미지 및 환경 구성
+ [Memory](harness-memory.md) - 세션 간 대화 지속
+ [보안 및 액세스 제어](harness-security.md) - 스킬 소스에 대한 실행 역할 정책
+ [API 설명서](harness-get-started.md#api-documentation)