mgechev/skills-best-practices

해결하는 문제

이 프로젝트는 AI 에이전트가 과도한 토큰을 소비하거나 단계를 잘못 생성하지 않고, 복잡하고 결정론적인 작업을 수행할 수 있도록 해주는 "에이전트 스킬"을 생성하기 위한 전문 수준의 최적 실천 방법을 제공합니다.

작동 방식

표준화된 디렉터리 구조와 스킬 설계 패턴을 정의하며, "진행적 공개"를 통해 LLM의 컨텍스트 창 크기 부담을 줄이는 데 중점을 둡니다.

• 구조: 스킬은 SKILL.md (뇌), 결정론적 코드를 위한 scripts/ 폴더, 보조 컨텍스트를 위한 references/, 템플릿을 위한 assets/로 구성됩니다.
• 발견성: 에이전트가 정확히 올바른 스킬을 트리거할 수 있도록 YAML 프론트마터(이름 및 설명)를 최적화합니다.
• 지시 스타일: 설명문 대신 3인칭 명령형과 단계별 번호를 사용하여 에이전트가 엄격한 순서로 수행하도록 보장합니다.
• 결정론적 오프로딩: 취약하거나 반복적인 작업은 LLM의 프롬프트에서 검증된 스크립트(Python, Bash, Node)로 이동시켜 오류를 방지합니다.
• 검증: 배포 전에 발견성, 논리, 에지 케이스를 LLM을 사용해 검증할 수 있는 프레임워크를 제공합니다.

대상 사용자

AI 에이전트 및 도구 사용 기능을 개발하고, 기능 정의를 표준화하며 신뢰성과 토큰 효율성을 최적화하고자 하는 개발자들입니다.

주요 특징

• 진행적 공개: 주요 지침 파일을 가볍게 유지(500줄 미만)하고, 필요할 때만 외부 파일을 로드하도록 안내합니다.
• 세부 검증 가이드: 에이전트가 올바른 스킬을 트리거하는지 테스트하고, 논리적 결함을 발견하기 위해 실행 시뮬레이션을 포함한 구체적인 프롬프트를 제공합니다.
• 결정론적 스크립트: 복잡한 파싱이나 보일러플레이트 코드를 처리하기 위해 작은 CLI를 묶는 것을 장려합니다.
• 라우터 스킬: 스킬 조합을 지원하여 하나의 스킬이 다른 하위 스킬로의 라우팅 역할을 할 수 있도록 합니다.