스킬 생성하기

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

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

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

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

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

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

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

이 방식의 장점:

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

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

검토 후 게시

스킬 생성 요청을 받아도 에이전트는 작업을 멈추지 않습니다. 초안 스킬을 만들자마자 채팅에 카드가 나타나고, 에이전트는 곧바로 다음 작업을 이어갑니다. 카드는 원하는 때 클릭해서 열면 되며(웹·iOS·Android 모두 동일한 검토 화면을 제공합니다), 열린 화면에서 스킬 이름·설명·카테고리·본문(SKILL.md)·파일 목록을 확인·수정할 수 있습니다. 게시는 항상 사용자가 직접 하는 동작이라 에이전트가 대신 게시할 수는 없습니다. 검토를 마치면 다음 중 하나로 게시합니다.

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

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

번들에 담긴 파일에 개인정보나 민감한 데이터가 들어 있는 것으로 보이면 검토 화면에 경고 표시가 붙습니다. 경고가 붙은 파일은 체크를 해제해 게시 대상에서 제외할 수 있고, 제외한 파일은 게시할 때 실제로 삭제됩니다. 게시 버튼을 누르기 전에 검증 실행으로 공개 가능 여부를 미리 확인해볼 수도 있습니다.

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

공개는 자동 검사를 통과해야 합니다. 공개를 시도하면 시스템이 스킬 파일에 API 키·토큰 같은 시크릿이 남아 있는지, 이름·설명·본문이 비어 있지 않은지 자동으로 검사합니다. 시크릿이 발견되거나 필수 정보가 비어 있으면 공개가 거부되고 오류 메시지가 표시됩니다. 또한 UpServe 공식(official) 스킬을 기반으로 만든 스킬이나, 아직 비공개 상태인 다른 사용자의 스킬을 포크한 스킬은 공개할 수 없습니다.

공개한 뒤 — 개선 제안 검토

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

진입점: 스킬 탭에서 내 스킬을 열면 스킬 상세 페이지 하단에 개선 제안 섹션이 보입니다. 이 섹션은 스킬 작성자 본인에게만 표시됩니다.

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

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

스킬 삭제하기

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

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

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

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

• 카드는 목록에 그대로 남고 보관됨 배지가 붙습니다. 웹·iOS·Android 모두 동일하게 표시됩니다.
• 삭제를 실행하면 뜨는 안내도 “삭제됨”이 아니라 “보관됨”으로 정확히 알려드립니다.
• 내 에이전트는 이 스킬을 더 이상 쓰지 않습니다. 다음 실행부터 목록에서 빠지고, 새 에이전트에 장착할 수도 없습니다.
• 반대로 다른 사용자가 이미 가져가서 쓰던 사본은 영향받지 않고 그대로 동작합니다. 원작자가 보관 처리해도 이미 설치한 사람의 스킬까지 함께 멈추지는 않습니다.
• 마음이 바뀌면 스킬 상세 페이지의 보관 해제 버튼으로 언제든 비공개 스킬로 되돌릴 수 있습니다. 보관을 해제하면 내 에이전트에도 다시 장착할 수 있습니다.

스킬 탐색에서 가져오기

직접 만들지 않고 스킬 탭의 탐색  에서 다른 사람이 만든 스킬을 설치할 수도 있습니다. 스킬 상세 페이지에서 가져오기(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자, 명령형
---

선택 필드 (표준):

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단계로 점진적으로 로드됩니다.

의미: 에이전트에 스킬 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로 자동 주입됩니다. 에이전트가 스킬을 패키징할 때 필요한 인증 정보를 자동으로 인식해 이 항목을 채웁니다.

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

에이전트가 따르는 스크립트 설계 원칙

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

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

자동 정규화 (Lenient 정책)

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

다른 클라이언트와 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파일, 파일당 5MB, 패키지 총 20MB. 이미지·오디오·폰트 같은 바이너리 파일도 원본 그대로 보존됩니다.

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 최적화  — 트리거 정확도 개선
• 스킬 평가하기  — 출력 품질 검증
• 스크립트 작성 가이드  — 스킬 스크립트 설계 상세 지침