스킬 생성하기

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

에이전트가 대부분을 자동으로 처리하지만, 다음 상황에서는 직접 만드는 것이 의미 있습니다.

같은 흐름을 정확히 반복: 동일한 절차를 매번 안정적으로 재현해야 할 때
팀 동료나 다른 사용자와 공유: 같은 도구를 여러 사람이 쓰도록 배포할 때
조직 노하우를 자산화: 온보딩 자료나 반복 업무를 스킬로 정리해 둘 때

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

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

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


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

이 방식의 장점:

실제로 잘 됐던 작업만 스킬이 됩니다 — 한 번 시켜보고 결과가 만족스러웠던 흐름만 담기 때문에, 만들어두고 막상 돌려보니 안 되는 일이 없습니다.
만드는 복잡한 부분은 에이전트가 처리합니다 — 내부에서 어떤 파일이 만들어지는지 몰라도 됩니다.
채팅으로 계속 다듬을 수 있습니다 — “결과를 표 형태로 바꿔줘”, “이름을 더 짧게 해줘” 같이 평소 대화하듯 보완하면 됩니다.
나중에 언제든 수정할 수 있습니다 — 한 번 만들어두면 끝이 아니라, 필요한 부분만 골라 수정·확장을 부탁할 수 있습니다.

에이전트에게 부탁하는 예시 문장

상황	부탁 문장
방금 한 작업을 그대로 생성하고 싶을 때	”방금 흐름을 스킬로 만들어줘”
특정 단계만 따로 생성하고 싶을 때	”사이트에서 가격 추출하는 부분만 스킬로 만들어줘”
트리거 조건을 명시하고 싶을 때	”사용자가 ‘A사 가격 알려줘’라고 할 때 호출되는 스킬로 만들어줘”
이름을 직접 정하고 싶을 때	”이름은 `competitor-price-tracker`로 하고 스킬화해줘”
다른 사람과 공유할 준비까지 하고 싶을 때	”스킬로 만들고 마켓플레이스에 올릴 준비도 해줘”

검토 후 게시

스킬 생성은 검토가 필요한 도구입니다. 에이전트가 초안을 만든 뒤 리뷰 화면을 띄우고 사용자 확인을 기다립니다. 리뷰 화면에서 스킬 이름·설명·카테고리·파일 목록·스크립트 내용을 직접 수정할 수도 있고, 확인한 뒤 다음 중 하나로 게시합니다.

비공개로 게시 (기본) — 내 에이전트만 이 스킬을 설치·실행할 수 있습니다. 마켓플레이스에 노출되지 않으며, 다른 사용자는 검색해도 찾을 수 없습니다. 내부 노하우·민감한 연동·실험 중인 스킬은 비공개를 권장합니다.
마켓플레이스 공개 — 모든 UpServe 사용자가 검색해 가져갈 수 있습니다. 스킬 이름·설명·아이콘이 그대로 노출되며, 설치 수를 통계로 확인할 수 있습니다. 다른 사용자가 가져가도 내 원본에는 영향이 없습니다.

게시 후에도 비공개 ↔ 공개 전환은 언제든 가능합니다. 비공개로 되돌리면 새로 설치하는 사용자가 더 이상 검색하지 못하지만, 이미 가져간 사본은 그대로 유지됩니다.

리뷰 화면을 닫거나 취소하면 초안이 삭제됩니다. 화면을 띄워 둔 채 1시간 내에 응답하지 않으면 초안이 보관됩니다.

마켓에 공개한 뒤 — 개선 제안 검토

스킬을 마켓플레이스에 공개하면 다른 사용자의 에이전트가 실행 중 결함을 발견했을 때 자동으로 **개선 제안(proposal)**을 보냅니다. 여러 사람이 비슷한 결함을 보고해도 같은 결함으로 분류해 하나의 제안으로 묶어줍니다.

진입점: 마켓플레이스에서 내 스킬을 열면 개선 제안 탭을 볼 수 있습니다. 이 탭은 스킬 작성자 본인만 볼 수 있으며, 마켓플레이스 스킬 상세 페이지에서 진입할 수 있습니다.

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

액션	의미
채택 (Accept)	제안을 “검토 완료”로 표시. 이후 스킬 편집 화면에서 직접 수정해 새 버전으로 배포.
기각 (Reject)	제안이 유효하지 않다고 판단할 때. 메모를 남길 수 있습니다.
검토 보류	아무 행동도 취하지 않으면 해당 제안은 보류 상태로 유지됩니다.

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

마켓플레이스에서 가져오기

직접 만들지 않고 마켓플레이스 에서 다른 사람이 만든 스킬을 설치할 수도 있습니다. 스킬 상세 페이지에서 가져오기(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만 차지합니다. 실제 사용하는 스킬만 본문이 펼쳐집니다. 에이전트의 행동 지침에는 항상 frontmatter 요약만 포함되고, 본문 전체는 스킬을 처음 실행하는 시점에만 전달됩니다.


                 [매 턴 항상 로드]            ~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=...`
`apikey: <provider>`	`${SKILL_DIR}/.env`에 `<PROVIDER>_API_KEY=...` (플랫폼 관리)
`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 옵션 추가해줘”, “에러 메시지에 시도 가능한 다음 행동을 포함해줘”.

자동 정규화 (Lenient 정책)

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

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

다른 클라이언트와 zip으로 주고받기

UpServe 스킬은 표준 zip으로 export/import되므로 Claude Code·Cursor·Goose 등 호환 클라이언트와 양방향으로 이동시킬 수 있습니다.

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


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

보호 한도: zip당 200파일, 파일당 500KB, 패키지 총 2MB.

UpServe 스킬을 외부로 내보내기


curl -O -J https://api.upserve.app/api/skills/<skill-id>/export \
  -H "Authorization: Bearer $UPSERVE_TOKEN"
# → my-skill.zip 다운로드

zip 안에는 <slug>/SKILL.md + scripts/ + references/ + assets/가 표준 레이아웃으로 들어 있습니다. 압축을 풀어 다른 클라이언트의 스킬 디렉토리에 넣으면 끝입니다.

더 알아보기

마켓플레이스에서 설치하기 — 다른 사람이 만든 스킬 사용법
도구 부여하기 — 스킬과 함께 사용할 도구 선택
AgentSkills 공식 명세 — 표준 원본
스킬 description 최적화 — 트리거 정확도 개선
스킬 평가하기 — 출력 품질 검증
스크립트 작성 가이드 — 스킬 스크립트 설계 상세 지침