패키지 스킬(Package skills)

Cursor, Gemini, Claude Code, Cline, Copilot 같은 AI 코딩 에이전트가 Dart 코드를 작성·테스트·리팩터링할 때 도움을 줘요. 그런데 정확하고 관용적인 코드를 생성하려면 에이전트가 여러분 프로젝트가 쓰는 라이브러리와 패키지에 대한 컨텍스트가 필요해요. 패키지 스킬(package skills)은 바로 그 컨텍스트를 pub 패키지와 함께 배포하는 표준화된 방법이에요.

출처: Package skills

본문

Cursor, Gemini, Claude Code, Cline, Copilot 같은 AI 코딩 에이전트는 Dart 코드를 작성·테스트·리팩터링할 때 도움이 돼요. 정확하고 관용적인 코드를 생성하려면 이런 에이전트가 프로젝트가 사용하는 라이브러리와 패키지에 대한 컨텍스트에 의존해요.

**패키지 스킬(Package skills)**을 사용하면 패키지 작성자가 표준화되고 컨텍스트가 풍부한 AI 에이전트 지침을 자신의 pub 패키지와 함께 직접 배포할 수 있어요. package:skills 커맨드라인 도구(dart run skills@ <command>로 실행)를 사용하면 프로젝트 의존성에 대한 스킬을 발견·설치·업데이트할 수 있어요. 그래서 AI 에이전트가 할루시네이션(환각)을 줄이고 더 나은 코드를 작성하도록 만들 수 있어요. 자신의 패키지용 스킬을 작성·배포하는 방법을 배우려면 패키지와 함께 스킬 배포하기(Ship skills with packages)를 참고하세요.

에이전트 스킬이란 무엇인가요? (What are agent skills?)

에이전트 스킬(agent skill)은 라이브러리와 함께 패키징된 구조화된 지침·코드 예시·모범 사례의 집합이에요. 스킬은 개방형 에이전트 스킬 사양(Agent Skills specification)을 따르는데, 이 사양은 AI 코딩 에이전트가 지침을 발견하고 읽는 방식을 표준화해요.

스킬은 보통 다음을 포함해요:

컨텍스트 규칙(Contextual rules): 라이브러리 패턴, 아키텍처, 피해야 할 안티패턴에 대한 지침
코드 패턴(Code patterns): 일반적인 작업에 대한 구체적이고 복사해서 바로 쓸 수 있는 예시
도구 및 워크플로 스크립트(Tooling & workflow scripts): 에이전트가 작업을 수행하거나 코드를 검증하기 위해 실행할 수 있는 선택적 도우미 스크립트와 명령

스킬은 프로젝트의 에이전트 디렉터리(예: .agents/skills/)에 저장돼요. AI 코딩 도구와 에이전트는 이 위치에서 자동으로 스킬을 발견하고 사용해요.

왜 패키지 스킬을 써야 하나요? (Why use package skills?)

범용 AI 모델은 다양한 언어의 공개 코드로 학습되기 때문에 다음과 같은 문제가 있을 수 있어요:

더 이상 사용되지 않는(deprecated) API나 낡은 문법 제안
패키지별 아키텍처 관례를 놓침
사용 중인 특정 버전에 존재하지 않는 API를 할루시네이션

패키지 스킬을 설치하면 AI 에이전트가 패키지 작성자 자신이 작성하고 유지 관리하는 권위 있는 지식을 즉시 얻을 수 있어요.

의존성용 스킬 설치하기 (Install skills for dependencies)

프로젝트의 의존성이 제공하는 스킬을 설치·업데이트하려면 dart run skills@ get을 사용해요:

$ dart run skills@ get

프로젝트 디렉터리에서 실행하면, 도구는 pubspec.yaml의 직접 의존성(dependencies)을 스캔해서 skills/ 디렉터리를 배포하는 패키지가 있는지 찾고, 설치할 스킬을 선택하도록 안내해요:

Scanning dependencies for available skills...
? Select skills to install:
  [x] shelf: routing - Define and handle HTTP routes
  [ ] shelf: middleware - Add logging and CORS middleware
  [x] dio: error-handling - Configure retry interceptors

방향키와 스페이스바로 개별 스킬을 선택하거나, Ctrl+A를 눌러 모든 스킬을 선택·해제한 다음 Enter를 눌러요.

특정 패키지에서 스킬 설치하기 (Install skills from a specific package)

단일 패키지 의존성에서 스킬을 설치·업데이트하려면 -p(또는 --package) 옵션을 사용해요:

$ dart run skills@ get -p <package_name>

특정 스킬 설치하기 (Install a specific skill)

이름으로 특정 스킬을 설치하려면 -s(또는 --skill) 옵션을 사용해요:

$ dart run skills@ get -p <package_name> -s <skill_name>

모든 스킬 비대화형으로 설치하기 (Install all skills non-interactively)

대화형 프롬프트 없이 모든 의존성 소스에서 사용 가능한 모든 스킬을 설치하려면 -a(또는 --all) 플래그를 전달해요:

$ dart run skills@ get --all

Git 저장소에서 스킬 설치하기 (Install skills from a Git repository)

dart run skills@ add를 사용하면 어떤 Git 저장소에서든 직접 스킬을 설치할 수 있어요:

$ dart run skills@ add <git_repository_url>

프롬프트 없이 Git 저장소의 모든 스킬을 설치하려면 --all 플래그를 추가해요:

$ dart run skills@ add <git_repository_url> --all

소스로 추가되면, dart run skills@ get을 실행해 언제든지 설정된 Git 저장소에서 스킬을 업데이트할 수 있어요.

스킬 디렉터리 구조 (Skill directory structure)

스킬을 설치하면 AI 코딩 에이전트에 적합한 디렉터리(예: .agents/skills/)로 복사돼요:

my_project/
├── .agents/
│   └── skills/
│       ├── shelf-routing/
│       │   └── SKILL.md
│       └── dio-error-handling/
│           ├── SKILL.md
│           └── examples/
├── lib/
├── test/
└── pubspec.yaml

일단 설치되면, 스킬은 코드 생성·리팩터링·채팅 중에 에이전트가 즉시 사용할 수 있어요.

버전 관리와 .gitignore (Version control and .gitignore)

설치된 스킬을 커밋할지 여부는 팀의 워크플로에 따라 달라요:

스킬 디렉터리(예: .agents/skills/)를 커밋한다면, 모든 팀원이 같은 스킬 정의와 업데이트 추적을 공유하도록 .config/dart_skills/ 디렉터리도 함께 커밋해요.
스킬 디렉터리를 무시한다면, .config/dart_skills/도 .gitignore에 추가해요. 그러면 각 개발자가 로컬 작업 공간에서 dart run skills@ get을 실행할 수 있어요.

설치된 스킬 업데이트하기 (Update installed skills)

패키지가 발전하면서 작성자는 새로운 모범 사례와 API 변경으로 스킬을 업데이트해요. 설치된 모든 스킬을 의존성의 최신 버전에 맞게 업데이트하려면 다음을 실행해요:

$ dart run skills@ get

로컬 수정 처리하기 (Handle local modifications)

에이전트 스킬의 주요 장점 중 하나는 팀의 아키텍처나 스타일에 맞게 지침을 커스터마이즈하기 위해 로컬에서 직접 편집할 수 있다는 점이에요.

dart run skills@ get을 실행하면 package:skills가 이전에 설치된 스킬을 추적하고, 업데이트 전에 로컬 파일의 변경을 감지해요.

로컬 수정이 감지되면:

package:skills가 스킬이 로컬에서 수정되었다고 알려 줘요.
로컬 변경을 상위(업스트림) 버전으로 덮어쓸지(overwrite), 아니면 로컬 커스터마이징을 유지할지(keep) 선택하라는 프롬프트가 표시돼요.

스킬 관리 및 제거하기 (Manage and remove skills)

설치된 스킬 나열하기 (List installed skills)

현재 작업 공간에 설치된 관리 스킬을 모두 보려면 dart run skills@ list을 실행해요:

$ dart run skills@ list

제거된 의존성의 스킬 정리하기 (Prune skills from removed dependencies)

pubspec.yaml에서 의존성을 제거하면, 그 스킬이 여전히 에이전트의 스킬 디렉터리에 남아 있을 수 있어요. 더 이상 의존성이 아닌 패키지의 스킬을 자동으로 제거하려면 dart run skills@ prune을 실행해요:

$ dart run skills@ prune

특정 스킬 제거하기 (Remove specific skills)

작업 공간에서 관리 스킬을 명시적으로 제거하려면 dart run skills@ remove를 사용해요:

$ dart run skills@ remove -p <package_name>

패키지 스킬(Package skills)