Skill Authoring

AgentDock 퍼스트파티 Skill을 생성하거나 유지보수하기 위한 도구입니다. Skill의 본체는 모델이 읽을 수 있는 설명 문서이며, 도구는 실제 검사, 편집, 명령 실행, 패키징, 설치 및 검증을 담당합니다.

대상 Skill은 다음 두 부분으로 구성되어야 합니다:

이식 가능한 핵심 계약
+
선택적 호스트 어댑터 설명

AgentDock 전용 어댑터 설명을 제거한 후에도 Skill의 비즈니스 로직, 패키지 내 참조, 환경 변수 계약 및 보조 스크립트는 완전히 사용 가능해야 합니다.

언제 사용하는가

이 Skill을 사용하여 다음을 처리합니다:

새로운 퍼스트파티 Skill 생성
기존 Skill 수정, 리팩토링 또는 업그레이드
트리거 설명, 본문 프로세스, 참조 자료 또는 보조 스크립트 조정
테스트, 예제, 보안 제약 조건 및 이식성 검사 보충
버전 증가 및 소스 측과 현재 활성화된 버전 검증 완료

이 Skill을 사용하여 서드파티 Skill의 공식 보안 검토, 실제 자격 증명 구성 또는 설치된 버전 롤백을 처리하지 마십시오. 이러한 작업은 skill-installation에 속합니다.

핵심 원칙

모델이 언제 이 Skill을 선택해야 하는지 먼저 정의한 후 본문을 작성합니다.
Skill은 방법, 경계 및 도구 선택만 설명하며, 통합 실행 책임을 지지 않습니다.
Skill 핵심 계약은 호스트와 무관해야 하며, 패키지 내 파일은 상대 경로를 사용하고 환경은 실행 호스트에 의해 주입됩니다.
간단한 Skill은 우선 SKILL.md 하나만으로 충분하며, 정말 필요할 때만 참조, 스크립트 또는 테스트를 추가합니다.
본문, 참조, 스크립트 또는 동작을 수정한 후에는 반드시 시맨틱 버전을 증가시켜야 합니다.
동일 이름 및 동일 버전의 콘텐츠는 불변성을 유지해야 합니다.
환경 값, 장치 상태 및 실행 데이터는 Skill 패키지에 포함되어서는 안 됩니다.
모든 검증은 현재 설치되어 활성화된 버전에 대해 수행되어야 하며, 소스 디렉토리만 보지 않아야 합니다.
퍼스트파티 Skill은 이 Skill의 lint를 통과해야 하며, 패키지 설치 검증만으로는 충분하지 않습니다.

전체 사양은 패키지 내 references/skill-package-spec.md를 참조하십시오.

표준 프로세스

1. 요구사항 및 트리거 조건 이해

먼저 다음을 명확히 합니다:

사용자가 실제로 해결하려는 문제
모델이 어떤 요청에서 이 Skill을 선택해야 하는지
어떤 인접 작업이 이 Skill에 속하지 않는지
어떤 실제 도구를 호출해야 하는지
보조 스크립트, 참조 자료 또는 테스트가 필요한지
네트워크, 쓰기, 삭제, 자격 증명 또는 고위험 작업이 포함되는지

"특정 기능의 전체 수명 주기 관리"와 같은 광범위한 설명을 사용하지 마십시오. description은 모델이 언제 이 Skill을 선택해야 하는지 안정적으로 판단할 수 있게 해야 합니다.

2. 책임 경계 결정

본문은 최소한 다음을 설명해야 합니다:

적용 시나리오와 부적합 시나리오
읽거나 수정하는 대상
기본 읽기 전용 동작
쓰기 작업 및 파괴적 작업에 대한 확인 규칙
실패 시 반환해야 하는 증거

하나의 Skill은 안정적인 기능 경계를 중심으로 구성되어야 합니다. 요구사항이 독립적인 책임을 넘나드는 경우 여러 Skill로 분할해야 합니다.

3. 소스 디렉토리 생성

일반 퍼스트파티 및 커뮤니티 Skill은 기본적으로 별도의 agentdock-skills 저장소에 위치합니다:

skills/<skill-name>/

AgentDock 설치 패키지와 함께 부트스트랩되고 런타임 버전에 강하게 바인딩된 핵심 Skill만 AgentDock 메인 저장소에 위치합니다:

core-skills/<skill-name>/

필요에 따라 구조를 선택합니다:

skills/<skill-name>/
└── SKILL.md

skills/<skill-name>/
├── SKILL.md
├── references/
├── scripts/
└── tests/

skills/<skill-name>/
├── SKILL.md
├── run.py
└── tests/

형식을 위해 빈 디렉토리를 만들지 말고, 일반 통합을 AgentDock 메인 저장소에 다시 넣지 마십시오.

4. Frontmatter 작성

현재 AgentDock에서 공식적으로 파싱하는 형식:

---
name: example-skill
description: 언제 사용하는지, 어떤 문제를 해결하는지 명확히 설명
version: 1.0.0
---

요구사항:

name은 안정적이고 짧으며, 소문자와 하이픈으로 구성된 이름을 사용합니다.
description은 트리거 시나리오와 기능 경계를 모두 다룹니다.
version은 시맨틱 버전을 사용합니다.
Frontmatter 뒤에는 비어 있지 않은 Markdown 본문이 있어야 합니다.
현재 파서가 지원하지 않는 환경 변수 또는 실행 필드를 추가하지 마십시오.

5. 이식 가능한 핵심 작성

대상 Skill의 본문과 스크립트는 기본적으로 다음만 가정합니다:

현재 작업 디렉토리는 Skill 패키지 루트 디렉토리입니다.
패키지 내 리소스는 상대 경로로 접근할 수 있습니다.
환경 변수는 현재 프로세스 환경에서 가져옵니다.
실행 호스트가 도구 선택, 디렉토리 전환 및 환경 주입을 담당합니다.
AgentDock의 설치 디렉토리, 상태 디렉토리 또는 전용 변수에 의존하지 않습니다.

루트 디렉토리에 스크립트가 있는 경우 일반적인 실행 예는 다음과 같이 작성합니다:

printf '%s' '{"skill_action":"status"}' | python3 run.py

다음은 핵심 실행 전제 조건으로 사용해서는 안 됩니다:

~/.agentdock/skill-store/installed/...
고정 설치 버전 번호
AGENTDOCK_DIR, AGENTDOCK_HOME 또는 AGENTDOCK_SKILL_DIR을 패키지 내 스크립트나 개인 데이터 위치 지정에 사용
skill_env, exec_command 또는 skill://
고정 사용자 절대 경로
AgentDock 개인 환경 파일을 적극적으로 읽거나 source

AgentDock 도구 호출은 별도의 "AgentDock 어댑터/검증" 설명에 나타날 수 있지만, 해당 부분을 삭제한 후에도 Skill은 여전히 사용 가능해야 합니다.

6. 환경 변수 선언

구성이 필요한 각 대상 Skill은 본문에 변수를 명시적으로 선언해야 합니다:

## 환경 변수

| 변수 | 유형 | 필수 | 설명 |
|---|---:|---:|---|
| EXAMPLE_BASE_URL | config | 예 | 서비스 주소 |
| EXAMPLE_API_KEY | secret | 예 | API 키 |

유형은 최소한 config와 secret으로 구분하고, 변수가 누락된 경우 어떤 기능을 사용할 수 없는지 설명하십시오.

대상 Skill은 변수 이름과 용도만 선언하며, AgentDock 개인 저장 경로는 선언하지 않고 실제 값을 저장하지 않습니다. 보조 스크립트는 현재 프로세스 환경에서만 변수를 읽습니다.

AgentDock 로컬 검증 시 환경 값은 skill_package env_set/env_unset/env_list로 관리되며, exec_command의 skill 컨텍스트에 의해 이번 하위 프로세스에 주입됩니다. 환경은 AgentDock 메인 프로세스나 시스템 환경에 기록되지 않습니다.

7. 참조 자료 작성

references/에 넣기에 적합한 내용:

안정적인 프로토콜 설명
긴 체크리스트
API 필드 또는 오류 코드 표
매번 전체 로드할 필요가 없는 배경 자료

대상 SKILL.md는 패키지 내 상대 경로를 사용합니다. 예:

references/api.md

skill://<name>/...를 핵심 참조 계약으로 작성하지 말고, 다른 Skill의 설치 디렉토리에 의존하지 마십시오. AgentDock은 현재 활성화된 패키지를 검증할 때 read_file skill://<name>/...로 리소스를 읽을 수 있습니다.

8. 보조 스크립트 작성

보조 스크립트는 선택적 리소스일 뿐, Skill 본체가 아닙니다. 스크립트가 필요한 경우:

입력은 stdin JSON 객체를 사용합니다.
최상위 동작 필드는 일관되게 skill_action을 사용합니다.
비밀은 현재 프로세스 환경에서만 읽습니다.
명령줄 인수로 비밀을 전달하지 마십시오.
구조화된 JSON을 출력합니다.
오류는 안정적인 code와 읽기 쉬운 message를 반환합니다.
상태 확인은 우선 읽기 전용으로 수행합니다.
쓰기 작업은 사용자 확인 규칙을 따릅니다.
로그와 오류에 비밀이 노출되지 않아야 합니다.
패키지 내 파일은 상대 경로를 사용하거나 스크립트 자체 디렉토리를 기준으로 위치를 찾습니다.

권장 입력:

{
  "skill_action": "status"
}

일반 실행은 Skill 패키지 루트 디렉토리에서 수행됩니다:

python3 run.py

AgentDock 검증 시 exec_command의 skill: "<skill-name>"을 사용하여 현재 활성화된 디렉토리와 독립적인 환경을 바인딩하며, 버전 디렉토리를 수동으로 구문 분석하지 않습니다.

9. 이식성 린트 실행

이 Skill의 run.py는 다음을 제공합니다:

status: 린트 버전과 규칙 수를 보고합니다.
lint: 대상 Skill의 이식 가능한 핵심 및 호스트 바인딩 문제를 검사합니다.

입력 예:

{
  "skill_action": "lint",
  "source": "/path/to/agentdock-skills/skills/example-skill"
}

결과에는 다음이 포함됩니다:

portable
error_count
warning_count
각 이슈의 code, severity, 파일, 줄 번호, 설명 및 수정 제안

하드코딩된 설치 버전 디렉토리, AgentDock 전용 디렉토리 변수에 대한 의존성, AgentDock 환경 파일을 적극적으로 읽는 것, 고정 사용자 절대 경로는 error입니다. AgentDock 전용 도구 또는 URI가 대상 SKILL.md에 나타나는 것은 warning이며, 선택적 어댑터 설명에만 존재하는지 확인해야 합니다.

설치된 디렉토리에 대해 린트를 실행할 때, 패키지 루트 디렉토리 아래에 AgentDock 설치 프로그램이 생성한 .agentdock-install.json 파일은 무시됩니다. 이 파일은 호스트 설치 확인서일 뿐 Skill 패키지 콘텐츠가 아닙니다. 동일한 이름의 파일이 패키지 내 다른 디렉토리에 있으면 정상적으로 스캔됩니다.

AgentDock에서 새 버전의 skill-authoring을 설치한 후 다음과 같이 실행할 수 있습니다:

exec_command
  skill: skill-authoring
  cmd: python3 run.py
  stdin: {"skill_action":"lint","source":"/path/to/source"}

퍼스트파티 Skill을 생성하거나 수정할 때 portable은 true여야 합니다. warning은 하나씩 수정하거나 선택적 호스트 어댑터에 속하는 이유를 설명해야 합니다.

10. 테스트 작성

테스트는 실제 위험을 다루며, 최소한 다음을 고려합니다:

Frontmatter와 본문이 파싱 가능해야 합니다.
입력이 JSON 객체가 아닌 경우 명확하게 실패해야 합니다.
알 수 없는 skill_action에 대해 명확하게 실패해야 합니다.
환경 변수가 누락된 경우 변수 이름만 보고 값을 노출하지 않아야 합니다.
읽기 전용 상태 검사는 쓰기를 생성하지 않아야 합니다.
파괴적 작업이 확인 없이 수행되는 경우 거부해야 합니다.
로그와 오류에 비밀이 포함되지 않아야 합니다.
플랫폼 또는 종속성이 누락된 경우 진단 가능한 정보를 반환해야 합니다.
패키지는 루트 디렉토리에서 상대 명령을 사용하여 실행되어야 합니다.
스크립트는 AgentDock 개인 디렉토리에 의존하지 않아야 합니다.

11. 보안 및 품질 검사

커밋 전에 확인:

패키지 내에 실제 비밀번호, 토큰, 쿠키, 인증 캐시 또는 세션 파일이 없어야 합니다.
.env, 캐시, 데이터베이스, 스크린샷, 다운로드 파일 및 실행 결과가 없어야 합니다.
__pycache__, *.pyc, node_modules 또는 컴파일 산물이 없어야 합니다.
고정 사용자 절대 경로, 심볼릭 링크 또는 경로 탈출이 없어야 합니다.
구형 통합 실행 프로토콜, 구형 환경 도구 예제 또는 구형 매니페스트가 없어야 합니다.
네트워크 대상, 파일 쓰기, 삭제, 업로드 및 권한 변경이 명확하게 설명되어야 합니다.
종속성 설치가 숨겨진 방식으로 실행되지 않아야 합니다.

다음의 생성 또는 복원이 명시적으로 금지됩니다:

agentdock.yaml
skill_run
skill_env_manage
AGENTDOCK_OPERATION
PLUGIN_* 구형 프로토콜
구식 operation 또는 entrypoint 매니페스트
통합 Skill 실행기 또는 구형 Skill 런타임

장치 개인 상태 및 AgentDock 환경 값은 호스트에만 속하며 패키지에 포함되지 않아야 합니다.

12. 버전 증가

본문의 오타만 수정하고 동작 판단에 영향을 주지 않는 경우 패치 버전을 증가시킬 수 있습니다.
호환 가능한 기능, 변수, 동작 또는 참조를 추가하는 경우 마이너 버전을 증가시킵니다.
책임 경계를 변경하거나, 기존 기능을 제거하거나, 호환되지 않는 프로세스를 도입하는 경우 메이저 버전을 증가시킵니다.

설치 전에 현재 설치된 버전과 새 소스를 비교하십시오. 동일한 버전으로 다른 콘텐츠를 덮어쓰지 마십시오.

13. 검증 및 로컬 설치

최소한 다음을 완료합니다:

디렉토리와 Frontmatter 확인
버전이 올바르게 증가했는지 확인
금지된 파일, 심볼릭 링크 및 실제 비밀 확인
보조 스크립트에 대해 구문 검사 및 자체 테스트 수행
skill-authoring lint 실행하여 portable=true 확인 및 warning 검토
skill_package validate를 사용하여 패키지 수준 적법성 검증
skill_package install을 사용하여 설치 및 활성화
agentdock_context를 통해 이름과 설명이 경량 인덱스에 포함되었는지 확인
read_file skill://<name>/SKILL.md를 통해 현재 활성화된 본문 확인
참조가 있는 경우 최소 하나의 참조 읽기
보조 스크립트가 있는 경우 exec_command skill=<name>을 사용하여 현재 활성화된 버전에 대해 읽기 전용 status 실행
대표적인 저위험 동작을 하나 실행하고, 실행 불가능한 경우 실제 이유 기록

skill_package validate는 패키지가 합법적으로 설치될 수 있는지 담당합니다. 이 Skill의 lint는 퍼스트파티 작성 품질과 이식성을 담당하며, 둘은 서로 대체할 수 없습니다.

환경 변수

이 Skill 자체는 환경 변수가 필요하지 않습니다. 작성되는 대상 Skill이 비즈니스 변수를 선언하고, 실행 호스트가 현재 하위 프로세스에 주입하도록 요구합니다.

완료 기준

다음 조건이 모두 충족되어야 완료로 간주합니다:

설명이 안정적으로 트리거 가능하고 경계가 명확함
이식 가능한 핵심이 AgentDock 개인 디렉토리 또는 도구 매개변수에 의존하지 않음
패키지 내 스크립트가 Skill 루트 디렉토리에서 상대 경로로 실행 가능함
skill-authoring lint가 portable=true를 반환하고 warning이 하나씩 처리됨
보안 검사, 테스트 및 skill_package validate 통과
새 버전이 설치 및 활성화됨
agentdock_context 및 skill://가 새 버전을 읽음
현재 활성화된 버전의 실제 읽기 전용 검증 통과
비밀, 장치 개인 상태 또는 구형 아키텍처가 유입되지 않음

uvwt/agentdock

agentdock란 무엇인가요?

즐겨 사용하는 AI에게 물어보기

문서