패키지와 함께 스킬(skill) 배포하기

요즘 개발자들은 Cursor, Gemini, Claude Code, Cline, Copilot 같은 AI 코딩 에이전트를 써서 코드를 작성해요. 여러분의 패키지에 **에이전트 스킬(agent skills)**을 함께 배포하면, AI 에이전트가 여러분 라이브러리의 API에 딱 맞는 정확하고 관용적인(idiomatic) 코드를 쓰도록 도와줄 수 있어요.

출처: Ship skills with packages

본문

개발자가 여러분의 Dart나 Flutter 패키지를 사용할 때, Cursor, Gemini, Claude Code, Cline, Copilot 같은 AI 코딩 에이전트는 정확하고 관용적인 코드를 작성하기 위해 컨텍스트에 의존해요.

에이전트 스킬을 패키지와 함께 배포하면, AI 에이전트에게 여러분 라이브러리의 API에 특화된 권위 있는 지침, 코드 예시, 모범 사례를 제공할 수 있어요. 개발자가 프로젝트에서 스킬을 어떻게 설치하고 사용하는지 알아보려면 패키지 스킬 문서를 참고하세요.

왜 패키지에 스킬을 함께 배포하나요?

스킬이 없으면 AI 코딩 에이전트는 API를 추측하거나, 지원 중단된 메서드를 제안하거나, 여러분 라이브러리에 특화된 아키텍처 패턴을 놓치기 쉬워요. 스킬을 패키지와 함께 게시하면 이런 혜택이 생겨요.

개발자 오류 감소: 에이전트가 처음부터 동작하는 관용적인 코드를 생성해요.
지원 부담 감소: 흔한 설정 실수와 안티 패턴을 사전에 예방해 줘요.
손쉬운 설치: 패키지 사용자가 한 줄의 명령 dart run skills@ get으로 스킬을 설치할 수 있어요.

패키지 스킬 계획하기

패키지 스킬은 AI 에이전트에게 라이브러리의 특정 부분을 어떻게 사용하는지 가르치는 지침과 예시의 집합이에요. 패키지 스킬을 계획할 때는 이렇게 해 보세요.

일반적인 작업 흐름에 집중: 초기 설정, 라우팅, 인증, 오류 처리, 성능 최적화 같은 핵심 작업에 대한 스킬을 만들어요.
스킬을 모듈화해서 유지: 기능 영역마다 분리되고 집중된 스킬을 만들어요(예: my_package-routing, my_package-auth). 모든 걸 하나의 큰 스킬로 묶지 마세요.
지시형으로 작성: 열린 설명 대신 "X를 호출하기 전에 항상 Y를 초기화하세요" 같은 직접적이고 모호함 없는 규칙을 써요.

디렉터리 구조 설정하기

패키지에 스킬을 제공하려면 패키지 루트에 lib/와 pubspec.yaml과 나란히 최상위 skills/ 디렉터리를 만들어요.

my_package/
├── lib/
├── skills/
│ ├── my_package-routing/
│ │ ├── SKILL.md
│ │ ├── scripts/ # 선택: 헬퍼 스크립트
│ │ ├── references/ # 선택: 참고 문서
│ │ └── assets/ # 선택: 정적 리소스
│ └── my_package-testing/
│   └── SKILL.md
└── pubspec.yaml

skills/ 안의 각 하위 디렉터리는 하나의 스킬을 나타내며, 공개된 Agent Skills 사양을 따르는 SKILL.md 파일을 반드시 포함해야 해요.

스킬 이름 짓기 규칙

사용자가 여러 의존 패키지에서 스킬을 설치할 때 이름 충돌을 막으려면, 모든 스킬 디렉터리 이름은 패키지 이름(또는 밑줄을 하이픈으로 바꾼 패키지 이름)으로 시작하고 하이픈을 붙여야 해요.

패키지 이름	디렉터리 이름	유효한가?
`shelf`	`shelf-routing`	네
`my_package`	`my_package-routing`	네
`my_package`	`my-package-routing`	네
`my_package`	`routing`	아니요 (패키지 접두사 없음)
`my_package`	`other_pkg-routing`	아니요 (잘못된 패키지 접두사)

참고

package:skills 설치 도구가 이 접두사를 검증해서, 패키지 이름과 일치하지 않는 스킬은 건너뛰어요.

스킬 작성하기

각 스킬은 YAML frontmatter와 Markdown 지침이 있는 SKILL.md 파일로 정의돼요.

SKILL.md 파일의 구조를 보여 주는 다음 템플릿을 여러분 패키지에 맞게 수정해 보세요.

---
name: <package_name>-<skill_name>
description: >-
  Use when the user is working with <package_name> APIs to ensure correct
  patterns and error handling.
---

# <Skill Title>

## Guidelines

* Always call `initialize` before invoking other methods.
* Prefer using `<SpecificException>` over generic `Exception` types.
* Dispose of controllers and streams when they are no longer needed.

## Examples

### Basic setup example

```dart
import 'package:<package_name>/<package_name>.dart';

void main {
  // Provide clear, idiomatic Dart code snippets for the agent to follow.
}


#### 스킬 파일의 핵심 구성 요소

`SKILL.md` 파일은 보통 세 부분으로 이루어져요.

- **YAML frontmatter(`name`, `description`)**: 스킬을 식별하고, 사용자 프롬프트를 보고 AI 코딩 에이전트가 언제 스킬을 활성화할지 알려줘요.
- **Guidelines**: 라이브러리 관례, 권장 패턴, 피해야 할 흔한 안티 패턴을 설명하는 직접적이고 지시적인 규칙 목록이에요.
- **Examples**: 라이브러리의 API를 사용해 일반적인 작업을 구현하는 방법을 보여 주는 복사-붙여넣기 가능한 Dart 코드 조각이에요.

### CLI로 스킬 스캐폴딩하기

`package:skills` CLI를 사용하면 현재 패키지에 새 스킬을 빠르게 스캐폴딩할 수 있어요.

```bash
$ dart run skills@ create -n <skill_name> -d "<skill_description>"

이 명령은 접두사가 붙은 디렉터리와 시작용 SKILL.md 템플릿을 자동으로 생성해 줘요.

개발용 스킬과 게시용 스킬

패키지를 개발할 때는 패키지 개발에 내부적으로 쓰는 스킬과 패키지 사용자에게 게시하는 스킬을 구분하세요.

디렉터리	대상	설명
`skills/`	패키지 사용자	패키지와 함께 번들되어 `dart run skills@ get`으로 설치되는 공개 스킬.
`.agents/skills/`	패키지 관리자	저장소를 개발하는 동안 쓰는 내부 스킬. 사용자에게 배포되지 않아요.

게시 전에 스킬을 로컬에서 테스트하기

패키지를 pub.dev에 게시하기 전에, 스킬이 제대로 발견되고 설치되는지 확인해 보세요.

소비자 역할을 할 샘플 Dart 또는 Flutter 프로젝트를 만드세요.
샘플 프로젝트의 pubspec.yaml에 여러분 로컬 패키지를 가리키는 path 의존성을 추가하세요.
```
dependencies:
  my_package:
    path: ../path/to/my_package
```
샘플 프로젝트에서 dart run skills@ get을 실행하세요.
스킬이 대화형 선택 프롬프트에 나타나고, 샘플 프로젝트의 .agents/skills/ 디렉터리에 깔끔하게 설치되는지 확인하세요.

pub.dev에 게시하기

dart pub publish로 패키지를 게시하면 skills/ 디렉터리가 패키지 아카이브에 자동으로 번들돼요. 게시된 뒤에는 패키지에 의존하는 사용자가 dart run skills@ get을 실행해 스킬을 설치할 수 있어요.

모범 사례

스킬을 집중적으로 유지: 하나의 거대한 스킬보다 주요 기능 영역마다 스킬을 하나씩 만들어요.
AI 에이전트를 위해 작성: 명확하고 지시적인 지침을 써요. "Y를 호출하기 전에 항상 X를 사용하세요" 같은 직접적인 규칙이 열린 서술형 텍스트보다 효과적이에요.
구체적인 코드 예시 포함: 관용적인 Dart API 사용법을 보여 주는 완전하고 동작하는 코드 조각을 넣어요.
SKILL.md를 간결하게: SKILL.md를 500줄 미만으로 유지해요. 방대한 참고 자료나 스키마, 큰 문서 표는 references/나 assets/ 같은 하위 디렉터리에 넣어요.
패키지와 함께 스킬 버전 관리: 새 버전에서 패키지 API를 갱신할 때, 스킬도 최신 권장 사항을 반영하도록 갱신해요.

더 알아보기

package:skills on pub.dev — 스킬 설치·작성 도구.
Agent Skills specification — 스킬 파일의 공개 사양.
패키지 스킬 — 개발자가 스킬을 설치·사용하는 방법.