스킬 생성하기

언제 직접 스킬을 만드나요?

업무 스킬(이하 스킬)은 AI 직원이 대부분 자동으로 찾아 쓰지만, 다음 상황에서는 직접 만드는 것이 의미 있습니다.

같은 흐름을 정확히 반복: 동일한 절차를 매번 안정적으로 재현해야 할 때
노하우를 자산화: 신입 교육 자료나 반복 업무를 스킬로 정리해 둘 때

그 외에는 직접 만들 필요가 없습니다. 직원이 자율적으로 적합한 스킬을 찾아 씁니다.

내가 만든 스킬은 나만 쓸 수 있습니다. 다른 사용자에게 공개하거나 링크로 공유하는 기능은 없고(조직에 속해 있다면 조직에 공유는 할 수 있습니다), 모두가 쓰는 스킬은 UpServe가 지원하는 공식 스킬뿐입니다. 공식 스킬은 스킬·템플릿 설치하기에서 찾습니다.

“먼저 시켜보고, 잘 되면 생성하기”

UpServe에서 스킬을 만드는 권장 흐름입니다.


   [1] 직원에게 업무 지시
        "이 사이트의 가격 데이터를 매일 수집해서 정리해줘"
              │
              ▼
   [2] 직원이 도구를 조합해 작업 완료
        (브라우저·파일 쓰기·코드 실행 등 자유 조합)
              │
              ▼
   [3] 결과가 만족스러우면 스킬화 요청
        "방금 흐름을 스킬로 만들어줘"
              │
              ▼
   [4] 직원이 자동으로:
        · 실행 코드·파일 수집
        · 표준 규격 SKILL.md 작성 (요약·사용 시점 등 필수 정보 포함)
        · 규격 위반(공백·대문자 등) 자동 정규화
        · 초안 스킬 생성 + 채팅에 카드 표시
              │
              ▼
   [5] 카드를 열어 검토 후 저장 → 완료

이 방식의 장점:

실제로 잘 됐던 작업만 스킬이 됩니다: 실제로 성공한 흐름만 담기 때문에, 만들어는 놨는데 정작 실행하면 동작하지 않는 스킬이 생기지 않습니다.
만드는 복잡한 부분은 직원이 처리합니다: 내부에서 어떤 파일이 만들어지는지 몰라도 됩니다.
채팅으로 계속 다듬을 수 있습니다: “결과를 표 형태로 바꿔줘”, “이름을 더 짧게 해줘” 같이 평소 대화하듯 보완하면 됩니다.
나중에 언제든 수정할 수 있습니다: 한 번 만들어두면 끝이 아니라, 필요한 부분만 골라 수정·확장을 부탁할 수 있습니다.

직원이 요약이나 “언제 이 스킬을 쓰는지” 같은 필수 정보를 채우지 못하면 초안 자체가 만들어지지 않고, 무엇이 빠졌는지 안내를 받아 다시 채운 뒤 시도합니다. 즉 채팅에 카드가 뜬 시점에는 이미 검토에 필요한 정보가 갖춰져 있습니다.

직원에게 부탁하는 예시 문장

상황	부탁 문장
방금 한 작업을 그대로 생성하고 싶을 때	“방금 흐름을 스킬로 만들어줘”
특정 단계만 따로 생성하고 싶을 때	“사이트에서 가격 추출하는 부분만 스킬로 만들어줘”
스킬을 부를 조건을 명시하고 싶을 때	“사용자가 ‘A사 가격 알려줘’라고 할 때 호출되는 스킬로 만들어줘”
이름을 직접 정하고 싶을 때	“이름은 `competitor-price-tracker`로 하고 스킬화해줘”

검토 후 저장

스킬 생성 요청을 받아도 직원은 작업을 멈추지 않습니다. 초안 스킬을 만들자마자 채팅에 카드가 나타나고, 직원은 곧바로 다음 작업을 이어갑니다. 카드는 원하는 때 클릭해서 열면 되며(웹·iOS·Android 모두 검토 화면을 제공합니다), 스킬 이름·설명·카테고리·본문(SKILL.md)·파일 목록을 확인·수정할 수 있습니다. 웹에서는 기본 정보 → 내용 → 파일 세 단계로 나뉘어 표시됩니다.

1단계 · 기본 정보: 이름·설명·카테고리·유형을 고치는 칸과 함께, 직원이 SKILL.md에 채워 둔 요약·사용 시점·필요한 연결·(실행형 스킬의) 진입 스크립트가 읽기 전용으로 표시됩니다. 이 값들을 바꾸려면 2단계에서 SKILL.md 맨 위 설정 블록을 직접 고치면 됩니다.
2단계 · 내용: SKILL.md 본문을 직접 편집합니다.
3단계 · 파일: 스킬에 담긴 파일을 확인하고 제외할 파일을 고릅니다.

저장은 항상 사용자가 직접 하는 동작이라 직원이 대신 저장할 수는 없습니다. 검토를 마치고 저장을 누르면 스킬이 비공개로 저장되어 내 서재에 들어갑니다. 내 직원만 이 스킬을 설치·실행할 수 있고, 다른 사용자는 찾을 수 없습니다.

번들에 담긴 파일에 개인정보나 민감한 데이터가 들어 있는 것으로 보이면 검토 화면에 경고 표시가 붙습니다. 경고가 붙은 파일은 체크를 해제해 저장 대상에서 제외할 수 있고, 제외한 파일은 저장할 때 실제로 삭제됩니다.

저장 대화창을 취소하거나 닫으면 초안이 폐기됩니다. 그 외에는 저장하거나 폐기할 때까지 초안이 그대로 유지됩니다.

들어온 개선 제안 검토

내 직원이 내 스킬을 실행하다 결함을 발견하면 개선 제안(proposal)을 보낼 수 있습니다. 비슷한 결함을 여러 번 보고해도 같은 결함으로 분류해 하나의 제안으로 묶어줍니다.

진입점: 스킬 탭에서 내 스킬을 열면 스킬 상세 페이지 하단에 개선 제안 섹션이 보입니다. 이 섹션은 스킬 작성자 본인에게만 표시됩니다. 공식 스킬의 결함 보고는 이 목록이 아니라 UpServe 운영팀 검토로 갑니다.

각 제안에는 다음 네 가지 선택이 있습니다.

액션	의미
검토 완료로 표시 (Mark as reviewed)	제안을 “검토 완료”로 표시만 합니다. 스킬 본문은 바뀌지 않으며, 이후 별도의 편집 화면으로 이어지지도 않습니다. 반영 없이 제안을 닫고 싶을 때 씁니다.
수정 후 게시 (Edit & publish)	제안 카드 안에서 스킬 본문을 바로 고쳐 새 버전으로 게시합니다. 결함을 실제로 고쳐서 반영하고 싶다면 검토 완료로 표시가 아니라 이 버튼을 눌러야 합니다.
기각 (Reject)	제안이 유효하지 않다고 판단할 때. 메모를 남길 수 있습니다.
검토 보류	아무 행동도 취하지 않으면 해당 제안은 보류 상태로 유지됩니다.

내가 가져와서 쓰는 스킬에서 발생한 직원의 자동 패치는 이 제안 페이지에 표시되지 않습니다. 그건 별도 흐름(직원 자가 패치)으로 처리됩니다.

zip 파일로 새 버전 올리기

내 스킬을 컴퓨터에서 직접 고쳤다면, 수정본 zip을 올려 같은 스킬의 새 버전으로 만들 수 있습니다. 새 스킬이 하나 더 생기지 않고, 이 스킬의 기록과 이름이 그대로 이어집니다.

스킬 탭에서 고칠 스킬을 열어 상세 페이지로 들어갑니다.
제목 오른쪽의 업로드 아이콘(zip으로 업데이트)을 누릅니다.
수정한 zip 파일을 골라 올립니다.

올린 뒤에는 결과가 이렇게 표시됩니다.

내용이 바뀐 경우: “새 버전으로 올렸어요”라는 안내와 함께 새 버전 번호와 파일 개수가 보입니다.
지금 버전과 내용이 같은 경우: “지금 버전과 같아서 그대로 두었어요”라고 알려주고 버전은 오르지 않습니다. 고친 파일을 올렸는데 이 안내가 뜬다면 다른 파일을 고르지 않았는지 확인해 보세요.
zip 안 SKILL.md에 적힌 이름(name)이 이 스킬과 다른 경우: 이 스킬을 가리키는 고유 이름은 바뀌지 않고 그대로 유지되며, 엉뚱한 스킬을 고르지 않았는지 확인해 달라는 경고가 함께 표시됩니다.
올린 파일에 API 키 같은 비밀 정보나 위험한 내용이 들어 있는 경우: 업로드가 거절되고 기존 버전이 그대로 남습니다.

이 버튼이 보이는 스킬: 내가 만들었거나 가져온 스킬 중 사용 중인(보관되지 않은) 스킬만 대상입니다. 다음 스킬에는 버튼이 나타나지 않습니다.

보관된 스킬: 먼저 보관 해제를 한 뒤 올려 주세요.
아직 저장하지 않은 초안과 UpServe 공식 스킬

새 스킬을 처음 zip으로 가져오려면 스킬 탭의 Zip으로 가져오기 버튼을 쓰세요. 지금은 새 버전 올리기가 웹에서만 제공됩니다.

스킬 삭제하기

내가 만든 스킬은 언제든 삭제할 수 있습니다(공식 스킬은 삭제 대상이 아닙니다). 스킬 카드를 열어 삭제를 누르고 확인하면 진행됩니다.

이때 결과는 두 가지 중 하나입니다.

한 번도 실행된 적 없는 스킬: 완전히 삭제됩니다. 되돌릴 수 없습니다.
한 번이라도 실행됐거나, 복사해서 수정한 적이 있거나, 팀에서 쓰인 적 있는 스킬: 완전히 지우지 않고 보관 처리됩니다. 이미 실행되면서 남은 흔적(직원이 그 스킬로 만든 작업 파일, 기억해 둔 내용, 대화 기록 등)이 갑자기 사라진 스킬을 참조하다 깨지는 것을 막기 위해서입니다.

보관되면 무엇이 달라지나요?

카드는 목록에 그대로 남고 보관됨 배지가 붙습니다. 웹·iOS·Android 모두 동일하게 표시됩니다.
삭제를 실행하면 뜨는 안내도 “삭제됨”이 아니라 “보관됨”으로 정확히 알려드립니다.
내 직원은 이 스킬을 더 이상 쓰지 않습니다. 다음 실행부터 목록에서 빠지고, 새 직원에게 장착할 수도 없습니다.
마음이 바뀌면 스킬 상세 페이지의 보관 해제 버튼으로 언제든 되돌릴 수 있습니다. 보관을 해제하면 내 직원에게도 다시 장착할 수 있습니다.

공식 스킬에서 가져오기

직접 만들지 않고 스킬 탭의 공식 스킬 에서 UpServe가 지원하는 스킬을 설치할 수도 있습니다. 스킬 상세 페이지에서 가져오기(Import) 버튼을 누르면 내 스킬 라이브러리에 원본을 참조하는 방식으로 추가되어 내 직원에게 장착할 수 있고, 채팅으로 수정하면 그때 내 버전이 따로 만들어집니다.

자세한 설치 흐름은 스킬·템플릿 설치하기를 참고하세요.

고급 (Advanced)

아래 내용은 일반 사용자에게 필요하지 않습니다. 스킬 내부 구조를 직접 들여다보거나, 외부에서 가져온 스킬을 분석·수정하거나, 다른 클라이언트와 스킬을 교환해야 하는 경우에만 참고하세요.

직원이 만드는 스킬의 구조

디렉토리 레이아웃


my-skill/
├── SKILL.md           # 필수: frontmatter + 본문
├── scripts/           # 선택: 실행 코드
│   ├── main.py
│   └── requirements.txt
├── references/        # 선택: 직원이 필요할 때만 읽는 참조 문서
│   └── api-spec.md
└── assets/            # 선택: 템플릿·스키마·룩업 테이블
    └── output-template.md

SKILL.md frontmatter

표준은 두 가지만 필수입니다.


---
name: my-skill                 # kebab-case, 1-64자, 디렉토리명과 일치
description: Use this skill when ... # ≤1024자, 명령형
---

선택 필드 (표준):

필드	용도
`license`	라이선스명 또는 번들된 LICENSE 파일 참조
`compatibility`	환경 요구사항 (≤500자). 예: “Requires Python 3.14+ and uv”
`allowed-tools`	사전 승인 도구 목록 (실험적)
`metadata`	클라이언트별 확장 키 격납소

UpServe 확장은 `metadata:` 아래에

UpServe만의 확장 필드(연결 정보 바인딩, 액션 메뉴, 호출 조건 힌트 등)는 표준 metadata: 네임스페이스에 둡니다. 이렇게 해야 다른 호환 클라이언트가 SKILL.md를 인식할 때 충돌하지 않습니다.


---
name: notion
description: Search, read, and write Notion pages and databases via OAuth. Use when the user asks to search Notion, read a page, query a database, or reference a Notion URL.
metadata:
  display_name: Notion Integration
  when_to_use:
    - User asks to search their Notion workspace.
    - User references a Notion URL or page id.
  requires:
    - oauth: notion          # → ${SKILL_DIR}/.env에 NOTION_TOKEN 자동 주입
  entry_script: scripts/main.py
  actions:
    - search: "Search pages and databases by title/content"
    - read: "Read a page's content"
  files:
    - scripts/main.py
  load_before_use: true
---
 
# Notion Integration
 
## When to use this skill
...

Progressive Disclosure: 토큰 절약 모델

스킬은 3단계로 점진적으로 로드됩니다.

단계	로드 시점	로드 내용	토큰 비용
1. 카탈로그	모든 턴	`name` + `description`만	스킬당 ~50-100 토큰
2. 본문	스킬을 처음 실행할 때 1회 (대화 이력이 정리·압축된 뒤 재실행 시에는 본문을 다시 전달)	전체 SKILL.md 본문	< 5,000 토큰 권장
3. 자원	본문이 참조한 파일을 읽을 때	scripts / references / assets 개별 파일	가변

의미: 직원에게 스킬 20개를 설치해도 행동 지침은 2-3KB만 차지합니다. 실제 사용하는 스킬만 본문이 펼쳐집니다.


                 [매 턴 항상 로드]            약 50~100 토큰/스킬
                ┌─────────────────────────┐
                │  Tier 1 · 카탈로그      │
                │  name + description     │
                └─────────────────────────┘
                            │
                            │ 직원이 "이 스킬 쓰자"라고 판단
                            ▼ (스킬 첫 실행 시 1회)
                ┌─────────────────────────┐
                │  Tier 2 · 본문          │  < 5,000 토큰 권장
                │  SKILL.md 전체          │
                └─────────────────────────┘
                            │
                            │ 본문이 "scripts/main.py 봐"라고 지시
                            ▼ (개별 파일 읽을 때만)
                ┌─────────────────────────┐
                │  Tier 3 · 자원          │     가변
                │  scripts / refs / assets│
                └─────────────────────────┘

연결 정보 주입

스킬 코드가 외부 서비스에 접근해야 할 때, frontmatter metadata.requires에 명시하면 스킬 실행 시점에 ${SKILL_DIR}/.env로 자동 주입됩니다. 직원이 스킬을 패키징할 때 필요한 연결 정보를 자동으로 인식해 이 항목을 채웁니다.

표기	주입 결과
`oauth: <provider>`	`${SKILL_DIR}/.env`에 `<PROVIDER>_TOKEN=...`
`vault: <NAME>`	`${SKILL_DIR}/.env`에 `<NAME>=...` (직원에게 저장한 연결 정보)
`scope: <scope>`	`UPSERVE_AGENT_TOKEN` + `UPSERVE_API_BASE` (UpServe 내부 API용)

스크립트는 . ./.env && python3 scripts/main.py ... 식으로 환경변수를 source한 뒤 실행합니다. .env는 매 턴(직원이 한 번 응답을 마칠 때)마다 자동으로 정리되며, 다음 턴에 같은 스킬을 다시 쓰면 자동으로 재생성되므로 신경 쓸 필요는 없습니다.

직원이 따르는 스크립트 설계 원칙

직원이 스킬 스크립트를 작성할 때 기본적으로 다음 9가지 원칙을 따릅니다. 직접 작성할 필요는 없지만, 다른 사람이 만든 스킬을 검토할 때 이 체크리스트를 참고할 수 있습니다.

원칙	이유
비대화형	직원은 대화형 TTY 입력 요청에 응답할 수 없음. flag/env로 모든 입력 받기
`--help` 노출	직원이 사용법을 학습하는 1차 경로
구조화 stdout	JSON/CSV/TSV. 직원이 파싱하기 쉬움
stderr는 진단용	데이터와 로그 분리
명확한 에러 메시지	“무엇이 / 무엇을 기대했고 / 무엇을 시도하라”
멱등성	“create-if-not-exists” > “create-and-fail” (직원이 재시도하므로)
명시적 exit code	실패 유형별 구분 (404/auth/validation)
예측 가능한 출력 크기	기본 cap + `--offset`/`--limit`로 페이지네이션
PEP 723 인라인 의존성 (Python)	`uv run scripts/x.py` 한 줄로 실행 가능

수정이 필요하면 채팅으로 부탁하면 됩니다. 예: “스크립트에 --limit 옵션 추가해줘”, “에러 메시지에 시도 가능한 다음 행동을 포함해줘”. 전체 가이드는 AgentSkills 스크립트 가이드 를 참고하세요.

자동 정규화 (Lenient 정책)

표준은 strict하지만 UpServe는 로딩은 관대하게, 경고만 발생시킵니다. 외부 zip을 가져오거나 직원이 SKILL.md를 작성할 때 모두 동일하게 적용됩니다.

위반	처리
`name`이 대문자/공백/언더스코어 포함	자동 정규화 (`Notion Integration` → `notion-integration`), 원본은 `metadata.display_name`에 보존
`name`이 64자 초과	경고, 64자로 절단
따옴표 없는 콜론이 있는 YAML	자동 lenient 파싱 시도
`description` 누락	거부 (필수: 없으면 직원이 스킬을 부를 수 없음)
`description` 1024자 초과	거부

다른 클라이언트의 스킬을 zip으로 가져오기

Claude Code·Cursor·Goose 등 호환 클라이언트에서 만든 스킬을 표준 zip으로 가져올 수 있습니다.

다른 클라이언트의 스킬 가져오기


curl -X POST https://api.upserve.app/api/skills/import \
  -H "Authorization: Bearer $UPSERVE_TOKEN" \
  -F "file=@my-skill.zip"

보호 한도: zip당 200파일, 파일당 5MB, 패키지 총 20MB. 이미지·오디오·폰트 같은 바이너리 파일도 원본 그대로 보존됩니다.

기존 스킬을 새 버전으로 갱신하기

가져오기 요청에 갱신할 스킬의 id를 함께 보내면 새 스킬을 만들지 않고 그 스킬의 새 버전으로 올립니다. zip 업로드와 GitHub 가져오기 모두 같은 방식입니다. 대상은 본인 소유의 사용 중인 스킬만 가능하며, 보관·공식 스킬이면 요청이 거절됩니다.


# zip
curl -X POST https://api.upserve.app/api/skills/import \
  -H "Authorization: Bearer $UPSERVE_TOKEN" \
  -F "file=@my-skill.zip" \
  -F "target_skill_id=<skill-id>"
 
# GitHub
curl -X POST https://api.upserve.app/api/skills/import-github \
  -H "Authorization: Bearer $UPSERVE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "owner/repo", "target_skill_id": "<skill-id>"}'

응답의 updated_existing은 기존 스킬을 갱신했는지, content_changed는 내용이 실제로 바뀌었는지, content_version은 갱신 후 버전 번호입니다. 내용이 같으면 content_changed가 false이고 버전은 오르지 않습니다.

더 알아보기

스킬·템플릿 설치하기: 공식 스킬 사용법
도구 부여하기: 스킬과 함께 사용할 도구 선택
AgentSkills 공식 명세 : 표준 원본
스킬 description 최적화 : 스킬 호출 정확도 개선
스킬 평가하기 : 출력 품질 검증
스크립트 작성 가이드 : 스킬 스크립트 설계 상세 지침