에이전트 스킬 작성하기

Source: Dev.to

번역할 텍스트를 제공해 주시면 한국어로 번역해 드리겠습니다.

Source: …

DRY 원칙

DRY(Do not Repeat Yourself) 원칙은 오래전부터 존재해 왔습니다.
코드를 여러 곳에 복사‑붙여넣기하고 버그가 발생하면, 모든 곳에서 그 버그를 수정해야 합니다. 중복이 많을수록 수정할 때 하나를 놓칠 가능성이 높아집니다.

코딩 어시스턴트 맥락에서의 DRY

코딩 어시스턴트를 사용할 때 DRY는 다른 의미를 가집니다:

• 매 세션마다 어시스턴트에게 프로젝트 분석을 요청할 필요가 없습니다.
• 매번 언어의 코딩 규칙을 반복해서 알려줄 필요가 없습니다.
• 프로젝트가 불변성을 선호한다는 것을 어시스턴트에게 계속 상기시킬 필요가 없습니다.

새로운 개발자가 좋은 프로젝트에 합류하면, 그 프로젝트의 기능, 아키텍처, 그리고 규칙을 안내받습니다. 훌륭한 프로젝트에서는 이러한 규칙이 문서화된 형태로 공식화되어 있으며, 때때로 최신 상태로 유지됩니다. 코딩 어시스턴트는 다른 팀원과 마찬가지로 문서화된 정보를 필요로 합니다.

제가 사용하는 두 코딩 어시스턴트 모두 이러한 지시문을 사용할 수 있게 해줍니다(모두 지원한다고 가정합니다). 예를 들어, GitHub Copilot은 자동으로 .github/instructions.md 파일을 읽습니다.

지시 파일을 작게 유지하기

어시스턴트가 지시를 자동으로 읽고 그 범위가 너무 넓으면, 관련 없는 데이터가 컨텍스트에 섞이게 됩니다.
결론: 파일을 비교적 작게 유지하고 일반적인 정보에 집중하세요.

크기 조정 조언

제 조언: 작게 시작하고 필요에 따라 늘리며, 결과를 분석하고 파일이 너무 커지면 리팩터링하세요.

토큰이 진정한 자원입니다

오늘날 중요한 자원은 CPU, RAM, 저장소가 아니라 토큰입니다. 토큰은 한정되어 있고 비용이 많이 듭니다. 나는 개발자들이 곧 토큰 사용량으로 평가받게 될 것이라고 예측합니다: 비슷한 결과를 얻으면서 가장 적은 토큰을 사용하는 개발자가 더 뛰어난 개발자가 될 것입니다.

대부분의 에이전트는 기본 지시 파일을 로드합니다:

• GitHub Copilot → AGENTS.md
• Claude → CLAUDE.md

파일이 작을수록 컨텍스트에서 사용되는 토큰이 적어집니다.

좋은 컨텍스트는 필요한 모든 토큰을 포함하지만 그 이상은 포함하지 않습니다—여기서 스킬이 중요한 역할을 합니다.

Source: …

에이전트 스킬

에이전트 스킬은 에이전트가 발견하고 사용할 수 있는 명령, 스크립트, 리소스 폴더이며, 이를 통해 작업을 보다 정확하고 효율적으로 수행할 수 있습니다.

AGENTS.md와는 달리 스킬은 자동으로 로드되지 않으므로 컨텍스트를 부풀리지 않습니다. 코딩 어시스턴트에 따라 스킬이 자동으로 발견·로드될 수도 있고, 그렇지 않을 수도 있습니다.

스킬 호출 방법

• 기본적으로 당신과 Claude 모두 어떤 스킬이든 호출할 수 있습니다.
• /skill-name 형태로 입력하면 직접 호출할 수 있습니다.
• Claude는 대화와 관련이 있을 때 스킬을 자동으로 로드할 수 있습니다.

Claude가 스킬을 언제 호출해야 하는지 아는 방법

Claude는 각 SKILL.md 파일의 프런트‑머터를 도구 정의로 변환합니다. 아래는 제가 만든 Kotlin 스킬의 프런트‑머터 예시입니다:

---
name: kotlin
description: |
  Use this skill when working with Kotlin code in any capacity:
  - Reading, writing, editing, or reviewing Kotlin files (*.kt, *.kts)
  - Running Gradle tasks for Kotlin modules
  - Writing or debugging Kotlin/JS code that targets Node.js
  - Working with external JavaScript libraries from Kotlin
  - Writing tests for Kotlin code (@Test, @BeforeTest, @AfterTest)
  - Setting up dependency injection or mocking in Kotlin
  - Dealing with multiplatform Kotlin projects (common, jsMain, jsTest, jvmMain)
  - Troubleshooting Kotlin compilation or runtime errors
  - Any task involving Kotlin/JS modules targeting Node.js

  This skill provides Kotlin/JS technical knowledge (especially JS interop gotchas)
  and coding‑style preferences beyond the official conventions.
---

위 내용은 Claude가 언제 도구를 로드할지 판단하는 데 필요한 정보를 제공합니다. 명백히 이 스킬은 Kotlin 및 Kotlin/JS와 관련된 것입니다.

스킬의 내용

일반 AGENTS.md 파일과 동일한 규칙을 따릅니다:

• 스킬 폴더 내에 로컬로 존재하거나 온라인에서 접근 가능한 다른 문서(텍스트 등)를 참조할 수 있습니다.
• Kotlin 코딩 컨벤션 전체를 전용 파일에 복사해 두었습니다. SKILL.md는 주요 항목을 요약하고 컨벤션에 대한 링크를 제공합니다.
• 전체 컨벤션은 이 스킬 디렉터리의 kotlin-coding-conventions.md 파일에 로컬로 캐시되어 있습니다.

주요 알림 (Kotlin)

• var보다 val을 선호하세요 – 불변성을 우선합니다
• 불변 컬렉션 인터페이스(List, Set, Map, MutableList 등 사용 금지)를 사용하세요
• 짧은 람다에서는 it을 사용하고, 중첩/복잡한 경우에는 명명된 매개변수를 사용하세요
• if, when, try는 문 형태보다 표현식 형태를 선호하세요
• 명령형 루프보다 함수형 스타일(filter, map)을 선호하세요

1. 외부 인터페이스 vs. Kotlin 클래스

문제: Kotlin 클래스는 프로토타입에 메서드를 가지고 있습니다. 외부 인터페이스는 메서드가 객체 자체에 직접 존재하기를 기대합니다. unsafeCast를 사용해 변환할 수 없습니다.

// ❌ WRONG: This will fail at runtime
class MockSql {
    fun unsafe(query: String) = /* … */
}
val sql: Sql = mockSql.unsafeCast()  // Throws: sql.unsafe is not a function

// ✅ CORRECT: Use an extension function to build a plain JS object
fun MockSql.toExternal(): Sql {
    val obj = Any().asDynamic()
    val mock = this

    obj.unsafe = { query: String -> mock.unsafe(query) }
    obj.end = { mock.end() }

    return obj.unsafeCast()
}

// Then use it:
val sql: Sql = mockSql.toExternal()

Bottom line

스킬은 같은 지시를 반복해서 하는 것을 피하는 데 훌륭합니다. skills와 instructions의 주요 차이점은 필요하지 않을 때 skills가 컨텍스트를 부풀리지 않는다는 점입니다. 현명하게 사용하고, 지시 파일을 작게 유지하며, 토큰 사용량이 감소하는 것을 확인하세요.

더 나아가기

에이전트 스킬

• Claude에 스킬 확장
• 체계적 개발 스킬
• 멋진 스킬

AGENTS.md

원래는 A Java Geek에 2026년 3월 15일에 게시되었습니다.