Skills, MCP, Custom Agents

확장 체계

지식·도구·전문가 — CLI 능력을 넓히는 3축

3축 확장 체계

Skills는 JIT 로딩, MCP는 표준 연결, Agents는 역할 위임 — 축마다 다른 확장 방식

1. 1
   Skills

   • description 매칭으로 도메인 지식 JIT 로딩
   • AWS 서비스 가이드, 사내 규칙 등
   • 필요할 때만 활성화 — 토큰 절약
2. 2
   MCP

   • 외부 도구를 프로토콜 표준으로 연결
   • GitHub, AWS, Figma 등 API를 에이전트가 직접 호출
   • OAuth MCP로 인증 서비스도 연동
3. 3
   Custom Agents

   • 전문 역할 하위 에이전트 정의
   • 보안 리뷰어, 테스트 작성자 등에 위임
   • 역할별 도구 제한으로 안전한 분업

.kiro/ 공유 아키텍처

IDE와 CLI가 동일한 설정을 읽는 구조

Skills

필요한 지식만 그때그때 불러오는 JIT 로딩 구조

Skills JIT 로딩 흐름

프롬프트 입력부터 전문 응답까지 — description 매칭이 결정하는 4단계

1. 1
   프롬프트 입력

   • "DynamoDB 싱글 테이블 설계해줘"
   • 사용자가 질문이나 요청을 입력
   • Skills description 매칭 시작
2. 2
   description 매칭

   • Skills 메타데이터(description)와 요청 매칭
   • "DynamoDB", "싱글 테이블" → 해당 Skill 발견
   • 매칭 안 되면 로딩하지 않음
3. 3
   JIT 로딩

   • 매칭된 Skills 마크다운만 컨텍스트 추가
   • 나머지 수십 개 Skills는 토큰 소비 없음
   • Steering(항상)과 달리 선택적
4. 4
   전문 응답

   • Skills 지식을 참조하여 정확한 가이드
   • 최신 API, 모범 사례, 주의사항 포함
   • 할루시네이션 감소

Skills 마크다운 구조

.kiro/skills/ 디렉토리에 마크다운으로 작성

---
name: dynamodb-patterns
description: DynamoDB 설계 패턴 가이드 — 싱글 테이블 설계,
  GSI, 파티션 키 작업 시 활성화
---
# keywords 필드는 없음 — 매칭 단서는 description에 녹여 쓴다

# DynamoDB 설계 패턴

## 싱글 테이블 디자인
- PK/SK 복합 키로 다중 엔티티 저장
- GSI는 최대 20개 — 액세스 패턴별 설계

## 파티션 키 설계
- 높은 카디널리티 선택 (UUID, 복합 키)
- 핫 파티션 방지 — write sharding 활용

## 비용 최적화
- On-Demand는 예측 불가 워크로드에
- Provisioned + Auto Scaling이 안정 워크로드에 적합

MCP

외부 도구를 표준 프로토콜로 잇는 연결 계층

MCP 설정 파일

.kiro/settings/mcp.json으로 서버 등록

{
  "mcpServers": {
    "aws-docs": {
      "command": "uvx",
      "args": ["awslabs.aws-documentation-mcp-server@latest"],
      "env": { "AWS_REGION": "us-east-1" }
    },
    "github": {
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${GITHUB_TOKEN}"
      }
    },
    "figma": {
      "url": "https://mcp.figma.com/mcp",
      "oauth": {
        "redirectUri": "http://127.0.0.1:8080/oauth/callback",
        "oauthScopes": ["read"]
      }
    }
  }
}

stdio vs streamable-http

로컬 프로세스와 원격 서버의 선택

OAuth MCP 연결

서드파티 서비스 인증 설정

Custom Agents

역할·도구·권한을 파일로 정의하는 전문가 분업

Custom Agent 정의

.kiro/agents/*.md로 전문 에이전트 작성

---
description: 단위 테스트를 자동 생성하는 전문 에이전트
tools:
  - read
  - write
  - shell
permissions:
  rules:
    - capability: fs_write
      effect: allow
      match: "**/*.test.{ts,tsx}"
    - capability: shell
      effect: allow
      match: "npx jest*"
---
# 테스트 작성 에이전트

## 역할
소스 코드를 분석하여 단위 테스트를 생성합니다.
## 지시사항
- describe/it 구조로 작성
- 경계값, 에러 케이스 포함
- mock보다 실제 구현 우선
- 기존 테스트 패턴을 참조하여 일관성 유지
- 생성 후 npx jest로 실행하여 통과 확인

에이전트 역할 분업

최소 권한 원칙으로 안전한 위임

공유 구조

개인 설정과 팀 설정이 병합되는 2계층 구조

Global ↔ Workspace 계층

개인 설정과 팀 설정의 분리

IDE vs CLI 동작 차이

동일한 설정, 약간 다른 인터페이스

.kiro/ 디렉토리 전체 구조

Git으로 관리되는 프로젝트 규칙의 단일 소스