Custom Agents

Markdown 형식과 태그 기반 도구, 인라인 권한으로 목적에 맞는 커스텀 에이전트 프로필을 만드는 방법을 소개합니다.

개요

목적에 특화된 에이전트를 몇 분 만에 만들 수 있습니다. Markdown 파일 하나를 작성하고, read, write, shell 같은 간단한 태그로 에이전트가 접근할 도구 범주를 선언하고, MCP 서버와 권한 규칙을 인라인으로 포함시킨 다음, 버전 관리로 팀과 그 파일을 공유하면 됩니다. 파일을 저장하는 순간 에이전트가 에이전트 선택기에 나타납니다.

Markdown 형식

설정은 YAML 프런트매터에 두고, 시스템 프롬프트는 문서 본문에 작성합니다.

---
description: Backend development agent
model: claude-sonnet-4
tools: [read, write, shell, web]
mcpServers:
  postgres:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-postgres"]
    env:
      DATABASE_URL: "${DATABASE_URL}"
permissions:
  rules:
    - capability: shell
      effect: allow
      match:
        - "npm *"
        - "node *"
---

You are a backend developer focused on Node.js and TypeScript.
Always use async/await. All database queries must be parameterized.

태그

tools 필드는 범주 태그를 받으며, 해당 범주에 속한 모든 도구를 자동으로 포함합니다.

태그포함 대상
read파일 읽기, 디렉터리 목록, 검색
write파일 쓰기, 편집, 삭제
shell명령 실행 및 프로세스 관리
web웹 페치
subagent서브에이전트 위임
context컨텍스트 및 Steering 도구
@mcpmcp.json에 정의된 모든 MCP 도구
@builtin모든 내장 도구
*전체

새 도구가 특정 범주에 추가되면 에이전트가 이를 자동으로 인식합니다.

파일 위치

중첩 디렉터리도 지원합니다. 에이전트 이름은 agents 디렉터리를 기준으로 한 상대 경로에서 확장자를 뺀 값입니다. 예를 들어 ~/.kiro/agents/team/planner.md는 team/planner가 됩니다.

워크스페이스 에이전트는 해당 워크스페이스가 신뢰된 경우에만 로드됩니다. .kiro/agents/가 있는 워크스페이스를 처음 열면 Kiro가 신뢰 여부를 묻습니다.

에이전트 프로필의 권한

권한 규칙을 에이전트 프로필에 직접 포함시킬 수 있습니다.

permissions:
  rules:
    - capability: builtin
      effect: allow
    - capability: shell
      effect: deny
      match:
        - "rm *"
        - "sudo *"
    - capability: filesystem
      effect: deny
      match:
        - ".env"
        - "secrets/**"

어떤 규칙도 도구 호출과 일치하지 않으면 기본값은 ask입니다. 효과는 deny > ask > allow 순으로 우선 적용됩니다.

MCP 서버 인라인 정의

MCP 서버를 정의해 두면 에이전트 프로필이 완전히 자기 완결적으로 동작합니다.

mcpServers:
  local-server:
    command: npx
    args: ["-y", "@org/mcp-server"]
    env:
      API_KEY: "${API_KEY}"
    requestTimeout: 180000
  remote-server:
    url: https://api.example.com/mcp
    headers:
      Authorization: "Bearer ${TOKEN}"

환경 변수는 $ 구문을 사용하며 런타임에 확장됩니다. Stdio 서버는 timeout(연결 핸드셰이크, 기본 60초)과 requestTimeout(호출당, 기본 120초)을 지원합니다. HTTP 서버는 인증이 필요한 엔드포인트를 위해 headers를 지원합니다.

다음 단계