Communitygithub.com

aetox-skills/create-agent

Scope-first agent design skill — 범위를 명확히 정한 후 에이전트를 생성합니다.

create-agent란 무엇인가요?

이 스킬은 AI 에이전트를 설계할 때 범위 검증(Scope Validation)을 최우선으로 하는 방법론을 제공합니다. 프롬프트나 코드 작성을 시작하기 전에 에이전트의 목적, 아키타입, 기능, 경계 등을 체계적으로 인터뷰하여 검증된 'Agent Spec'을 생성합니다. 이 스펙은 이후 다른 AI나 개발자가 올바르게 에이전트를 구현할 수 있는 청사진 역할을 하며, 8가지 차원(아키타입, 성격, 기능, 입출력, 생태계, 메모리, 생명주기, 위험/지표)을 정의합니다. 이 스킬은 Claude Code, Cursor, Codex 등 다양한 AI 코딩 에이전트 플랫폼에서 사용할 수 있으며, 시스템, 개발자, 크리에이티브 등 8가지 아키타입과 4단계 깊이 레이어(Quick, Standard, Deep, Critical)를 지원하여 상황에 따라 적절한 수준의 인터뷰를 수행합니다.

지원 대상✓Claude Code~Codex CLI~Cursor✓OpenCode
npx skills add aetox-skills/create-agent

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

Create Agent

목적

범위 우선(scope-first) 규율을 준수하는 AI 에이전트를 설계합니다. 프롬프트, 설정, 도구 바인딩을 작성하기 전에 반드시 구조화된 범위 인터뷰를 거쳐야 합니다. 인터뷰의 깊이는 설계 중인 에이전트의 복잡성에 따라 달라집니다.

이것은 프롬프트 작성 스킬이 아닙니다. 범위 검증 스킬입니다. 출력물은 검증된 Agent Spec으로, 다른 AI나 사람이 에이전트를 올바르게 구축하는 데 사용할 수 있는 청사진입니다.

모든 에이전트 스펙은 8가지 차원을 정의합니다.

아키타입 → 성격 → 기능 → 입출력 → 생태계 → 메모리 → 생명주기 → 위험/지표

철칙

  1. 범위 선 빌드 후 — 범위가 검증될 때까지 코드, 프롬프트, 도구 설정은 금지됩니다. 예외는 없습니다.

    수정 권한: 초안/스펙 가정에만 적용 — 사용자가 놓친 가정(누락된 종속성, 모순, 안전 위험)은 스펙에서 바로 수정하십시오. 사전 질문 없이, 단지 무엇을 조정했고 그 이유를 알리십시오. 실제 파일, 설정, 도구, 또는 워크플로우는 승인 없이 수정하지 마십시오. 올바른 해결책에 새 도구나 기존 워크플로우 변경이 필요한 경우 승인을 요청하십시오. 하지만 상식적인 수준의 스펙 수정은 바로 처리하십시오.

  2. 충분한 최소 깊이 — 기본값은 Quick입니다. 명시적인 신호가 있을 때만 Standard/Deep/Critical로 승격하십시오. Standard부터 시작하지 마십시오.

  3. 먼저 추론하고, 나중에 질문하십시오 — 질문하기 전에 문맥, 코드베이스, 기존 에이전트, 사용자가 이미 말한 내용에서 답을 추론하려고 시도하십시오. 진정으로 불확실한 것에 대해서만 질문하십시오.

  4. 코드베이스 우선 — 질문에 대한 답이 설정, 문서 또는 기존 에이전트에 존재한다면 — 찾아서 확인하십시오. 질문하지 마십시오. 그린필드 예외: 코드베이스(index.md, AGENTS.md, opencode.jsonc 또는 기존 에이전트)가 없으면 코드베이스 검색을 건너뛰고 곧바로 인터뷰로 진행하십시오.

  5. 왕복 최소화 — 스펙 추론 → 초안 제시 → 사용자 표시 허용. 초안이 해결할 수 없는 진정한 격차에 대해서만 하나씩 질문하십시오. 한 번에 10개의 질문을 던지지 마십시오.

  6. 개방형이 아닌 추천형 — 모든 질문에는 추천 답변이 포함되어야 합니다. 반응할 대상을 제공하십시오.

  7. 스펙은 승인되어야 함 — Agent Spec이 명시적으로 승인될 때까지 절대 빌드하지 마십시오. Quick 레이어의 경우, 추론된 스펙에 대한 사용자 확인이 승인으로 간주됩니다. 상태: Quick을 통해 승인됨으로 문서화하십시오.

  8. 신호에 중단 — 사용자가 "충분하다" 또는 "그만"이라고 말하면 중단하십시오. 논쟁하거나 더 많은 것을 요구하지 마십시오.

  9. Agent Spec 출력 — 모든 세션은 Quick 레이어에서도 검증된 스펙을 생성합니다.


에이전트 아키타입 시스템

에이전트는 아키타입에 따라 패턴을 따릅니다. 이 표를 사용하여 올바른 아키타입을 선택하고 집중하거나 건너뛸 인터뷰 도메인을 이해하십시오.

아키타입 카탈로그

#아키타입핵심 목적기본 성격일반적인 도구권장 레이어
🛠️시스템자동화, 설정, 유지보수실용적, 간결, 직설적CLI, 파일시스템, Docker, gitQuick → Standard
🎨크리에이티브디자인, 시각, 모션표현적, 세부 지향Tailwind, GSAP, 이미지 APIQuick → Standard
💻개발자코드, 아키텍처, 디버그기술적, 정확함, 철저함MCP, 린터, 테스트 러너Quick → Deep
📝서기문서화, 작성, 정리명확함, 구조적, 인내심Obsidian, 마크다운, 검색Quick
🔬전문가단일 심층 도메인권위적, 꼼꼼함도메인 특화 CLI/MCPQuick → Deep
🎯오케스트레이터조정, 위임, 관리체계적, 프로세스 중심에이전트 목록, 핸드오프 프로토콜Quick → Critical
🔍연구자검색, 분석, 종합호기심, 분석적, 철저함Exa, Firecrawl, 웹 도구Quick
🎮게임게임 특화 동작장난기, 적응형게임 API, 봇 프레임워크Quick → Deep

아키타입 최소화 목록

"건너뛰기"가 아니라, 어떤 도메인을 짧게 또는 명백하면 건너뛸 수 있음을 나타냅니다.

3가지 레벨이 있습니다:

  • 심층 — 모든 것을 질문
  • 간략 — 1-2개의 질문만 하고 요약
  • 명백하면 건너뛰기 — 상식으로 알 수 있으면 질문하지 않음 (예: 서기 → 메모리 = 세션 전용)
아키타입간략명백하면 건너뛰기심층
시스템신원, 입출력메모리기능, 생태계
크리에이티브위험/지표, 생명주기메모리신원, 입출력, 성격
개발자생명주기신원기능, 생태계, 입출력
서기생태계위험/지표, 메모리신원, 입출력
전문가입출력, 생명주기—기능, 위험/지표
오케스트레이터——모든 도메인
연구자생명주기, 성격메모리기능, 입출력, 신원
게임생태계위험/지표기능, 입출력, 성격

개발자 + 신원: 간략은 건너뛰기가 아닙니다. 신원(frontmatter)은 여전히 필요합니다. 에이전트가 언제 호출되는지 결정하기 때문입니다. 간단히 (1-2문장) 만들면 됩니다.

아키타입 선택

인터뷰할 때 에이전트의 목적에 따라 아키타입을 추천하십시오. 여러 아키타입이 적합하면 지배적인 것을 선택하고 보조를 기록하십시오.

예시: "이것은 개발자 아키타입처럼 들리며 전문가와 일부 겹칩니다.
         최소화 목록 기준: 생명주기 = 간략, 신원 = 간략 (frontmatter만),
         기능 + 생태계 심층 집중."

깊이 레이어 시스템

모든 에이전트가 같은 깊이를 필요로 하지는 않습니다. 이 스킬은 4가지 레이어를 정의합니다. 기본값은 Quick입니다. 가볍게 시작하고, 신호가 필요할 때만 승격하십시오.

레이어 1 — Quick       (추론 → 확인 → 빌드, 불확실하면 추가 질문)
                       │                          ← 기본값
레이어 2 — Standard    (초안 제시 → 사용자 표시 → 승인)
                       │
레이어 3 — Deep        (Standard + 생태계 맵 + 종속성 추적)
                       │
레이어 4 — Critical    (Deep + 위험 모델 + 비용 모델 + 안전 게이트)

레이어 선택

신호QuickStandardDeepCritical
에이전트가 새롭거나 수정됨 (1-2 기능), 범위 명확✅———
기존 에이전트, 작은 변경✅———
새 에이전트, 단일 목적, 종속성 없음—✅——
새 에이전트, 1-2개의 외부 통합—✅✅—
다중 에이전트 생태계 내 에이전트——✅✅
결제/인증/PII 처리———✅
프로덕션에 배포———✅
호출당 높은 토큰 비용———✅
안전 또는 규정 준수 영향———✅
아키타입 = 오케스트레이터———✅
아키타입 = 전문가——✅—

기본값은 Quick입니다. 명시적인 신호가 있을 때만 승격하십시오.

승격 규칙: 낮은 레이어 인터뷰 중에 더 높은 레이어가 필요한 신호를 발견하면 명시적으로 승격하십시오.

승격 노트:
  트리거: [발견한 내용]
  증거: [발견한 위치]
  유지 위험: [낮은 레이어가 안전하지 않은 이유]

레이어 1 — Quick

간단한 에이전트와 작은 변경을 위한 레이어입니다. 문맥에서 스펙을 추론하고 사용자와 확인한 후 빌드합니다. 전체 인터뷰나 별도의 승인 게이트는 없습니다.

이 레이어를 지나치게 복잡하게 생각하지 마십시오. 불확실하더라도 여기서 시작하십시오. 복잡성은 추론 중에 드러날 것입니다. 신호가 나타나면 승격하십시오.

진입 기준

  • 에이전트가 새롭거나(1-2 기능) 기존 에이전트에 작은 수정이 있는 경우.
  • 이미 존재하는 것 이상의 외부 통합이 없는 경우.
  • 다중 에이전트 조정이 없는 경우.
  • 안전, 비용 또는 규정 준수 위험이 없는 경우.
  • 요구 사항이 8개 도메인 인터뷰가 과잉 엔지니어링처럼 느껴질 정도로 명확한 경우.

프로세스

1. 문맥에서 스펙 추론    ← 사용자가 말한 것 + 코드베이스 + 기존 에이전트에서 읽음
2. 미니 스펙 제시          ← 아래 고정 형식 사용
3. 사용자 표시             ← "수정할 부분을 알려주세요"
   표시가 사소한 경우 (1-2단어, 형식 이름 약간 수정)
     → 바로 빌드 가능
   표시가 구조적인 경우 (기능 추가, 도구 변경, 경계 수정)
     → 수정된 미니 스펙 먼저 제시 → 사용자 확인 → 빌드
4. 빌드

미니 스펙 형식 (고정)

## Quick Spec: [이름]

직무: [한 문장 — "누구를 위해 무엇을 하여 무엇을 얻는가"]
기능:
  - [동작 1]
  - [동작 2]
경계:
  - [하지 말아야 할 것]
권한: [읽기 전용 / 제안 / 범위 내 수정 / 실행 / 자율]
도구: [도구 / MCP / 필요 없음]
승인: [Quick을 통해 확인됨 / 수정 및 확인됨]

파일 templates/quick-spec.md를 실제 템플릿으로 사용하십시오. 이 필드를 축약하거나 건너뛰지 마십시오. 필드가 명백하면 "—"를 쓰십시오(사용자에게 묻지 않음). 기존 에이전트를 수정하는 경우 동일한 형식을 사용하지만 변경된 필드만 표시하십시오.

예시

사용자: "메일 요약해주는 에이전트가 필요해요"

추론:
  아키타입: 서기
  기능: 이메일 읽기 → 글머리 기호 요약
  도구: Gmail MCP (이미 있음)
  생태계: steward와 함께 있음

미니 스펙 제시:
  ## Quick Spec: mail-summarizer

  직무: Mike를 위해 매일 아침 Gmail을 읽고 글머리 기호 요약 제공
  기능:
    - Gmail MCP에서 메일 읽기 → 글머리 기호로 요약
    - 발신자/제목별 분류
  경계:
    - 메일 답장 금지, 메일 삭제 금지
  권한: 읽기 전용
  도구: Gmail MCP (이미 있음)
  승인: —

  "한국어/영어? 모든 메일 아니면 특정 주제만?"

사용자: "한국어, 모든 메일, 로그는 필요 없음"
  (사소한 표시 — 빌드로 전송)

빌드.
  ## Quick Spec: mail-summarizer
  ...
  권한: 읽기 전용
  승인: Quick을 통해 확인됨

레이어 2 — Standard

새로운 에이전트와 중요한 변경을 위한 레이어입니다. Quick이 불충분할 때(복잡한 통합, 생태계 영향 또는 불명확한 범위) Standard로 승격하십시오.

프로세스

1. 의도 게이트       → 재진술, 아키타입 식별, 사용자 + 목표 + 제약 조건
2. 코드베이스 스캔     → index.md, opencode.jsonc, AGENTS.md, 기존 에이전트 읽기
                       (없으면 → 그린필드: 건너뛰고 초안 제시로 바로 이동)
3. 아키타입 매칭   → 아키타입 선택, 최소화 목록 적용
4. 초안 제시     → 알려진 문맥에서 전체 스펙 추론 → 1페이지 초안 제시
                       불확실한 점만 질문 (하나씩 질문하지 않음)
5. 사용자 표시      → 사용자가 초안 편집/추가/제거
6. 반복 (필요시)   → 격차가 있으면 수정된 초안 제시
7. 스펙 제안      → 전체 Agent Spec (templates/agent-spec.md 참조)
8. 승인 게이트     → 빌드 전 사용자 승인

범위 인터뷰 (8개 도메인)

Quick 레이어: 모두 건너뜁니다. 처음부터 추론 + 확인합니다.

Standard+:

  1. 가지고 있는 문맥에서 초안 스펙 추론 → 단일 페이지 초안을 사용자에게 제시
  2. 사용자가 읽고 표시 (수정/추가/삭제)
  3. 아래 체크리스트를 사용하여 누락된 것이 없는지 확인 — 초안이 다루지 않는 것만 질문
  4. 아키타입 최소화 목록 적용 — 아키타입에 따라 간략 / 명백하면 건너뛰기 / 심층

체크리스트에서 하나씩 순서대로 질문하지 마십시오. 초안을 먼저 제시하고 격차에 대해서만 질문하십시오.

도메인 1: 신원 & 목적

  • 이름 — 에이전트의 이름은 무엇입니까? (이름이 없으면 제안)

  • 아키타입 — 카탈로그 기준 어떤 아키타입입니까?

  • 역할 — 명확한 한 문장: "이 에이전트는 [사용자 Y]를 위해 [X를 수행]하여 [Z]를 얻습니다."

  • 페르소나 —

    필드내용예시
    어조공식적 / 캐주얼 / 기술적 / 장난기 / 권위적 / 따뜻함"기술적이지만 접근하기 쉬운"
    예시 문구에이전트가 실제로 말하는 말"설정을 확인해보겠습니다... 찾았습니다. 42번 줄에 문제가 있습니다."

    항상 페르소나를 추천하십시오.

    "기술적이지만 접근하기 쉬운 어조를 추천합니다.
     사실에 대해 정확하고 대화에서는 편안하게."
    
  • 알아야 할 문맥 — 작업 전에 무엇을 알아야 합니까?

  • 가장 좁은 직무 — 역할의 가장 작고 유용한 정의는 무엇입니까?

도메인 2: 기능 & 경계

  • 기능 — 핵심 동작, 우선순위별로 정렬. 각 기능에는 다음이 포함됩니다:

    • 설명 (1문장)
    • 트리거 (이 기능은 어떻게 호출됩니까?)
    • 예상 출력 (성공은 어떻게 생겼습니까?)
    • 실패 모드 (작동하지 않으면 어떻게 됩니까?)
  • 경계 — 절대 해서는 안 되는 것들의 명시적 목록. 각각을 중요 규칙으로 시나리오와 함께 형식화하십시오.

    규칙: 프로젝트 디렉토리 외부의 파일을 절대 수정하지 않음.
    시나리오: 사용자가 "내 데스크톱 설정을 고쳐줘"라고 요청 — 에이전트가 파일시스템에 접근 가능.
    결과: 정중히 거절하고 범위 제한을 설명.
    
  • 도구 매핑 — 각 기능에 대해 필요한 도구를 결정하십시오. 기능과 경계가 명확해진 후에 수행하십시오.

    기능: "문서 검색"
    ↓
    기존 도구에 대해 코드베이스 검색 → Exa MCP 발견 (웹 검색)
    ↓
    제안: "Exa MCP(이미 구성됨)를 통한 지식 검색.
              Exa를 사용할 수 없으면 Firecrawl을 통한 웹 검색으로 대체."
    

    규칙: 코드베이스에 이미 특정 도구가 존재하면 특정 도구를 제안하십시오. 기존 도구가 맞지 않는 경우에만 범주를 제안하십시오. 하지만: 기존 도구가 요구 사항과 일치하지 않으면 (예: 로컬 문서 검색이 필요한데 Exa 웹 검색만 있음) — 강제로 맞추지 마십시오. 부분 일치 또는 격차로 표시하고 더 적합한 범주를 제안하십시오.

    ✅ "Exa MCP 사용 (웹 검색) — 이미 구성됨"
    ✅ "Exa MCP는 웹 검색용으로 있지만 작업 로그 검색은
        Obsidian + grep을 사용해야 함 — 외부 검색에는 부분 일치"
    ✅ "기존 벡터 DB 없음. Chroma 또는 Qdrant와 같은 의미 검색 도구 필요."
    ❌ "지식 검색 도구 필요" (모호함 — Exa가 있으니 사용)
    ❌ "모든 것에 Exa MCP 사용" (강제 맞춤 — Exa는 로컬 검색에 부적합)
    

    도구 범주 (격차 참조용):

    지식 검색    → 검색, 벡터 DB, 문서 저장소, 웹 스크래핑
    코드 실행     → 샌드박스, 인터프리터, 컴파일러, 린터
    커뮤니케이션   → 이메일, 메시징, 알림, 웹훅
    시스템 작업   → 파일 I/O, 프로세스 관리, 네트워크, 레지스트리
    데이터 처리   → ETL, 변환, 검증, 저장
    시각/크리에이티브 → 이미지 생성, 레이아웃 엔진, 애니메이션
    모니터링     → 로그, 메트릭, 추적, 알림
    AI/LLM       → 모델 API, 임베딩, RAG 파이프라인, 벡터 DB
    테스트       → 테스트 러너, 커버리지, 모킹, E2E 브라우저
    
  • 스킬 — 이 에이전트가 사용해야 하는 스킬은 무엇입니까?

…

[번역을 위해 잘림]

관련 스킬