Sharkly의 Skills: 한 개발자의 프롬프트 노하우를 팀 인프라로 전환하기

AI 코딩 에이전트를 도입한 팀이라면, 프롬프트만 넣으면 척척 결과가 나오는 개발자가 한 명씩 있기 마련이다. 그 사람의 리뷰 요청은 팀이 원하는 형식으로 돌아온다. 테스트 작성 지시는 첫 시도부터 팀 스타일에 맞는 테스트를 만들어낸다. 비결이 뭐냐고 물으면 돌아오는 답은 대개 임시 파일 하나, dotfiles 저장소 하나, 아니면 매일 아침 새 세션에 붙여 넣는 문단 하나다. 노하우는 실재한다. 문제는 그 노하우가 어디에 있느냐다.

한 사람 머릿속에만 존재하는 프롬프트 노하우는 확장되지 않고, 휴가 때 사라지며, 다른 사람의 에이전트 실행에는 나타나지 않는다. 그 개발자가 자리를 비우면 품질이 떨어진다. 팀이 에이전트 한 개에서 다섯 개로 늘어나면, 다섯 개가 일하는 방식에 대해 서로 다른 답을 내놓는다.

Skills는 이런 간극에 대한 Sharkly의 해답이다. Skill은 에이전트 작업을 위한 재사용 가능한 지침과 지원 파일을 소유자, 범위, 명시적 권한과 함께 하나로 묶은 패키지다. 일반적인 개념부터 먼저 알고 싶다면 코딩 에이전트 Skill이란 무엇인가에서 정의와 더 넓은 생태계를 다룬다. 이 글은 Sharkly 내부의 워크플로에 관한 이야기다.

TL;DR

Sharkly의 Skill은 에이전트 작업을 위한 재사용 가능한 지침과 지원 파일을 하나로 묶은 것이다. 리뷰 규칙, 배포 체크리스트, 작성 표준, 팀 프로세스 등이 여기에 해당한다. 처음부터 직접 만들 수도 있고, 지원되는 공개 소스에서 게시된 Skill을 설치하거나, 로컬 런타임이 발견한 Skill을 가져오거나, SKILL.md, .skill 파일 또는 zip 패키지를 업로드할 수도 있다. 모든 Skill은 정확히 하나의 범위(Organization, Space, Agent)를 가지며, 생성할 때 선택되고 이후에는 바뀌지 않는다. 에이전트는 Skills 설정을 통해 사용 가능한 Skill을 바인딩하고, 변경 사항은 이후 실행에 적용되며, 편집 권한은 생성자와 Organization Owner, Admin에게 남는다. 그 결과 프롬프트 노하우는 한 개발자의 dotfiles에 머무르지 않고, 공유되고 권한으로 통제되는 팀 인프라가 된다.

프롬프트 노하우에 '집'이 생기면 무엇이 달라지는가

좋은 프롬프트와 Skill의 차이는 텍스트 자체가 아니다. 텍스트를 둘러싼 모든 것이다.

임시 파일에 담긴 프롬프트에는 소유자도, 대상도, 수명 주기도 없다. 그것이 존재한다는 걸 아무도 모르고, Slack에서 발견한 사본이 최신인지 아무도 판단할 수 없으며, 프로세스가 바뀌었을 때 갱신할 책임을 질 사람도 없다. Skill은 이 세 가지를 모두 갖는다. Skill은 Organization에 속한다. 범위는 어떤 에이전트가 사용할 수 있는지 정확히 밝혀준다. 편집 권한은 누가 변경할 수 있는지 정확히 밝혀준다. 프로세스가 바뀌면 Skill을 한 번 업데이트하면 되고, 바인딩된 모든 에이전트의 이후 실행이 그 변경을 반영한다.

이것이 레버리지 논지를 축소해 놓은 모습이다. 팀의 레버리지는 AI 채팅 창을 더 많이 여는 데서 나오지 않는다. 역할, 규칙, 컨텍스트, 워크플로를 공유하는 데서 나온다. 그리고 에이전트는 결과를 Task에 반환하므로, Skill이 이끈 실행의 산출물은 팀이 검토할 수 있는 공유 기록에 남는다.

워크플로로 들어가기 전에 한 가지 경계를 짚고 가자. Skill은 Task 요구사항이 아니다. 일회성 요구사항은 Task 설명이나 댓글에 남겨두자. 이 Task에만 필요하다면 그것은 컨텍스트다. 다음 달 실행에도 필요하다면 그것은 인프라다.

Skill을 처음부터 만들기

Skill은 이름, 설명, 지침 세 가지에서 시작한다. 이 구분은 겉보기보다 중요하다.

설명은 에이전트가 언제 이 Skill을 사용해야 하는지를 밝힌다. 이것이 트리거 조건이며, 자신의 역량 목록을 훑는 에이전트에게 이 Skill이 지금 눈앞의 작업에 해당한다고 알려주는 문장이다. 지침은 반복 가능한 프로세스와 기대 산출물, 즉 단계와 검사 항목, 결과가 갖춰야 할 형식을 정의한다. 유용한 판단 기준은 '에이전트가 언제 이 Skill을 꺼내 들어야 하는가'를 한 문장으로 말할 수 있는지다. 그럴 수 없다면 아마 두 개의 Skill을 보고 있거나, 아니면 아무것도 아닌 것을 보고 있는 셈이다.

내부적으로 기본 지침은 SKILL.md 파일에 담긴다. 맨 위에 YAML name과 description 필드가 오고, 그 뒤에 지침이 이어진다. 템플릿이나 예시, 참조 데이터를 제공하기 위한 지원 파일을 함께 넣을 수도 있다. 배포 체크리스트 Skill은 체크리스트 템플릿을 함께 가질 수 있고, 마이그레이션 작성 Skill은 주석이 달린 예시 두 개를 포함할 수 있다. 파일은 목적에 집중시키자. 크기가 크거나 관련 없는 파일 모음은 에이전트의 판단을 개선하지도 않으면서 컨텍스트만 늘린다.

이미 가진 노하우 가져오기

대부분의 팀은 백지에서 시작하지 않는다. 프롬프트 노하우는 이미 존재한다. 다만 흩어져 있을 뿐이다. Sharkly는 세 가지 가져오기 경로를 제공한다.

지원되는 공개 소스에서 설치하기. Sharkly는 게시된 Skill을 가져와 선택한 범위에 관리형 복사본을 만들 수 있다. 관리형 복사본이라는 점이 중요하다. 다른 사람의 파일에 링크하는 것이 아니라, 우리 Organization이 통제하는 스냅샷을 확보하는 것이다. 어떤 에이전트에 바인딩하기 전에 소스와 가져온 내용을 검토하자. 외부 지침은 신뢰할 수 있는 조직 정책이 아니라 서드파티 코드로 취급해야 한다.

로컬 런타임에서 가져오기. 이 경로는 바로 dotfiles 문제를 위해 만들어진 것이다. 온라인 상태의 로컬 런타임은 자체 로컬 Skill 디렉터리에서 발견한 Skill을 보고할 수 있다. 즉 개발자가 조용히 쌓아온 노하우가 Organization에 가시화된다. 가져오기는 Skill을 Organization으로 복사하며, 원본 로컬 복사본은 별도로 남아 있으므로 그 개발자의 환경 설정이 깨지는 일은 없다. 한 가지 유의할 점은 분명히 하자. 에이전트의 런타임에서 직접 사용할 수 있는 로컬 Skill은 제품에서 바인딩할 필요가 전혀 없다. 관리되고 재사용 가능한, 명시적 범위를 가진 Skill이 되어야 할 때 가져오자. 단지 존재한다는 이유로 가져올 것은 아니다.

패키지 업로드하기. Skill이 저장소에 있거나 동료에게 받은 것이라면 SKILL.md, .skill 파일 또는 zip 패키지를 업로드하자. Sharkly는 들어오는 내용을 검증한다. 파일 경로는 상대 경로여야 하고 Skill 외부로 벗어날 수 없다. 또한 업로드와 가져오기는 숨김 경로나 민감한 경로, 지원되지 않는 바이너리 콘텐츠, 안전하지 않은 압축 항목, 중복 경로, 서비스 한도를 초과한 패키지를 거부한다. Skill은 에이전트가 따를 지침이다. 의존성과 같은 수준의 검증을 받을 자격이 있다.

범위: 누가 Skill을 사용할 수 있는지 정하기

모든 Skill은 하나의 Organization에 속하며, 생성할 때 선택한 정확히 하나의 범위를 갖는다. 범위는 어떤 에이전트가 바인딩할 수 있는지 결정하며, 나중에 변경할 수 없다.

문서에 나오는 경험칙이 정답이다. 의도한 대상에 맞는 가장 좁은 범위를 선택하라. 범위는 영향 반경이기도 하다. Space 범위의 Skill이 낡으면 한 팀의 에이전트가 혼란스러워지지만, Organization 범위의 Skill이 낡으면 모든 에이전트가 혼란스러워진다. dotfiles 프롬프트의 대상은 영원히 한 사람이다. Skill의 대상은 시스템에 기록된, 의도적인 결정이다.

에이전트에 Skill 바인딩하기

Skill은 에이전트가 그것을 지니기 전까지 아무 일도 하지 않는다. Sharkly에서 에이전트는 저장된 작업 구성이며, Skill을 바인딩하면 여기에 역량이 하나 추가된다.

방법은 간단하다. 에이전트의 Skills 설정에서 사용 가능한 Skill을 추가하거나 제거하고, 에이전트를 생성할 때 Skill을 선택하면 된다. 사용 가능 여부는 범위 규칙을 따른다. 변경은 이후 에이전트 실행에 적용되므로, 오늘 추가한 바인딩은 진행 중인 작업을 방해하지 않으면서 내일의 작업을 형성한다.

판단이 필요한 부분은 에이전트 하나가 몇 개의 Skill을 지녀야 하는가다. 문서는 단호하다. 겹치는 Skill을 많이 바인딩하지 말라. 상충하거나 중복되는 지침은 실행을 덜 예측 가능하게 만든다. 날카로운 Skill 두 개가 서로 티격태격하는 여섯 개보다 낫다. 에이전트의 Skill 목록이 잡동사니 서랍처럼 보인다면, 그 실행 결과도 그렇게 될 것이다.

에이전트 자체 지침과 Skill 사이에도 역할 분담이 있다. 에이전트 지침은 그 하나의 역할에 대한 안정적인 동작, 즉 담당 범위와 언제 사람의 입력을 요청할지, 보고 형식을 담는다. 여러 에이전트가 공유할 수 있는 재사용 가능한 절차는 Skill에 속한다. 세 번째 에이전트의 지침에 같은 문단을 붙여 넣고 있는 자신을 발견한다면, 그 문단은 Skill이 되고 싶어 하는 것이다.

바인딩은 플랫폼의 나머지 기능이 복리 효과를 내게 하는 요소다. 리뷰 Skill을 지닌 바로 그 에이전트가 Automations가 일정이나 상태 변경에 따라 트리거하는 대상이다. 그래서 한 번 담아둔 표준이 아무도 수동으로 실행하지 않는 반복 실행에 나타난다. Skill은 스크립트로도 다룰 수 있다. CLI는 JSON 출력과 함께 sharkly skill list와 sharkly skill view를 제공한다.

거버넌스: 누가 편집하고, 누가 삭제하고, 누가 검토하는가

공유 역량에는 공유 통제가 필요하다. Skill이 프롬프트 파일과 가장 크게 갈리는 지점이 바로 여기다.

Skill은 생성자나 Organization Owner 또는 Admin이 편집하거나 삭제할 수 있다. Space 범위의 Skill은 해당 Space에 대한 쓰기 권한도 필요하다. Agent 범위의 Skill을 생성하거나 가져오고, 에이전트의 Skill 바인딩을 변경하려면 대상 에이전트를 관리할 권한이 필요하다. 금요일 오후에 몰래 리뷰 표준을 다시 쓰는 사람은 없다.

유지보수도 같은 '한 곳' 원칙을 따른다. 프로세스가 바뀌면 Skill의 지침과 지원 파일을 업데이트하면 되고, 이후 실행이 새 버전을 반영한다. 삭제는 서두르지 말아야 할 작업이다. 사용 중인 모든 에이전트에서 Skill이 제거되므로, 먼저 현재 바인딩을 확인하자.

보안 규칙은 짧고 타협할 수 없다. 비밀번호나 액세스 토큰, 개인 키, 기타 비밀 정보를 Skill 지침이나 지원 파일에 절대 저장하지 말자. 외부에서 가져왔거나 로컬에서 가져온 모든 Skill은 사용 전에 검토하자. 명령과 예시는 최소 권한 원칙을 따르게 하자. 그리고 에이전트의 Space 연결이나 Skill 내용을 변경한 뒤에는 바인딩을 다시 확인하자. 바인딩 아래에서 사용 가능 여부가 달라질 수 있기 때문이다.

이 모든 과정에서 인간과 에이전트의 계약은 유지된다. 에이전트는 Skill을 불러오고, 프로세스를 따르고, 결과를 Task에 반환한다. 어떤 Skill에 팀의 권위를 부여할지는 사람이 결정한다. Skill은 일관성의 하한선을 끌어올린다. 검토자를 없애주지는 않는다.

Skill을 만들지 말아야 할 때

Skill은 인프라이고, 인프라에는 유지 비용이 따른다. 정직한 판단 기준은 두 가지다. 일회성 요구사항은 Task 설명이나 댓글에 남기고, 같은 역량이 앞으로의 실행 전반에서 필요할 때 Skill을 만든다.

Skill을 만들지 않는 것이 정답인 경우가 몇 가지 더 있다. 절차가 로컬 런타임의 Skill 디렉터리에 있고 그 Computer의 실행에만 필요하다면 로컬에 그대로 두자. 두 후보 Skill이 같은 에이전트에서 크게 겹친다면, 둘 중 하나를 바인딩하기 전에 합치거나 더 날카롭게 다듬자. 그리고 설명 문장을 쓸 수 없다면, 그 프로세스는 아직 담아내기에는 충분히 안정적이지 않다.

절차 하나부터 시작하자

팀이 반복하면서도 조용히 한 사람에게 의존하고 있는 절차 하나를 골라보자. 그것을 하나의 좁은 Skill로 작성하자. 이름, 언제 적용되는지 밝히는 설명, 프로세스와 기대 산출물을 정의하는 지침이면 된다. Space 범위로 지정하자. 에이전트 하나에 바인딩하고, 그 에이전트에 실제 Task를 할당한 뒤, 돌아오는 결과를 읽어보자.

이것이 전체 순환 고리다. 한 개발자의 머릿속에 살던 노하우가 이제 이름과 범위, 소유자, 그리고 업데이트할 단 하나의 장소를 갖게 된다. 플랫폼이 처음이라면 Sharkly 개요에서 Skill이 Task, 에이전트, Computer와 어떻게 나란히 놓이는지 설명하고, Sharkly 시작하기에서 첫 연결 과정을 처음부터 끝까지 안내한다. Skills 문서에서는 위의 모든 규칙을 자세히 다룬다.

FAQ

Skill과 에이전트 지침의 차이는 무엇인가?

에이전트 지침은 하나의 역할에 대한 안정적인 동작, 즉 담당 범위와 언제 입력을 요청할지, 어떻게 보고할지를 정의한다. Skill은 여러 에이전트가 공유할 수 있는 재사용 가능한 절차로, 자체 지원 파일과 권한을 함께 묶은 것이다. 어떤 문단이 에이전트들 사이에서 복사되고 있다면, 그것은 Skill에 속한다.

Skill을 만든 뒤 범위를 변경할 수 있나?

아니다. Skill의 범위는 생성 시 고정된다. 대상이 바뀌어야 한다면 올바른 범위로 새 Skill을 만들고, 필요한 에이전트를 다시 바인딩하자. 그래서 문서에서는 처음부터 의도한 대상에 맞는 가장 좁은 범위를 선택하라고 권장한다.

가져온 Skill은 원본과 동기화되나?

아니다. 지원되는 공개 소스에서 설치하면 선택한 범위에 관리형 복사본이 만들어지고, 로컬 런타임에서 가져오면 Skill이 Organization으로 복사되며 원본 로컬 복사본은 별도로 남는다. 이후로는 우리 Organization이 그 복사본을 통제한다.

새 Skill을 바인딩하면 에이전트가 현재 실행 중인 Task에 영향을 주나?

아니다. 에이전트의 Skill 바인딩 변경은 이후 에이전트 실행에 적용된다. 이미 진행 중인 작업은 시작 당시의 구성으로 끝나고, 다음 실행이 업데이트된 Skill 세트를 반영한다.

공개 소스에서 설치한 Skill은 안전한가?

검토한다면 안전할 수 있다. 외부에서 가져왔거나 로컬에서 가져온 모든 Skill을 서드파티 코드나 구성으로 취급하자. 바인딩 전에 지침과 지원 파일을 읽고, 명령은 최소 권한으로 유지하고, Skill에 비밀 정보가 들어가도록 절대 허용하지 말자. Sharkly의 업로드 검증은 안전하지 않은 경로와 압축 항목을 거부하지만, 그 지침이 팀의 신뢰를 받을 만한지에 대한 판단은 사람의 몫이다.