Cortex Code CLI 확장성¶

스킬이란 무엇인가요?¶

스킬은 다음을 포함하는 마크다운 파일입니다.

• 도메인별 지침 및 모범 사례

• 스킬을 사용해야 하는 경우

• 워크플로 예제

• 선택적 도구 구성

스킬을 호출하면 해당 지침이 대화 컨텍스트에 삽입됩니다.

스킬 사용¶

``/skill list``를 실행하여 사용 가능한 스킬을 나열하고 이름별로 호출하여 대화에 스킬을 로드합니다.

스킬 위치¶

스킬은 여러 위치에서 로드되며, 우선 순위가 가장 높은 스킬부터 순서대로 나열됩니다.

사용자 지정 스킬 생성¶

스킬은 스킬 지침, 선택적 예제, 템플릿이 있는 SKILL.md 파일이 포함된 디렉터리입니다. 다음 위치 중 하나에서 스킬을 생성할 수 있습니다.

사용자 지정 스킬 구축을 시작하려면 다음을 수행합니다.

1. 스킬 디렉터리를 생성합니다. 이 예제에서는 프로젝트 위치에 “my-skill”이라는 스킬 디렉터리를 생성합니다.

   mkdir -p .cortex/skills/my-skill
   

   Copy

2. 이 디렉터리에서 :file:`SKILL.md`를 생성하고 스킬 지침을 추가합니다. 이 예제에서는 기본 구조를 보여줍니다.

   ---
   name: my-skill
   description: Brief description of what this skill does
   tools:
   - optional_tool_name
   ---
   
   # When to Use
   
   - Describe when this skill should be invoked
   - List specific user intents or scenarios
   
   # What This Skill Provides
   
   Explain the capabilities and knowledge this skill adds.
   
   # Instructions
   
   Step-by-step guidance for the AI when this skill is active.
   
   ## Best Practices
   
   - Best practice 1
   - Best practice 2
   
   ## Common Patterns
   
   ### Pattern 1
   Description and example.
   
   ### Pattern 2
   Description and example.
   
   # Examples
   
   ## Example 1: Basic Usage
   User: $my-skill Do something Assistant: [Expected behavior]
   
   
   ## Example 2: Advanced Usage
   User: $my-skill Complex task with @file.txt Assistant: [Expected behavior]
   

   Copy

3. $$ 명령을 사용하여 자신의 스킬이 목록에 표시되는지 확인합니다.

   > $$
   

   Copy

   스킬이 나열되면 올바르게 로드되어 사용할 수 있는 것입니다.

4. 대화에서 스킬을 사용합니다.

   > $my-skill Test it out
   

   Copy

---
name: database-admin
description: Database administration tasks
tools:
- snowflake_sql_execute
- snowflake_object_search
---

스킬 관리하기¶

작성 스킬¶

사용자 지정 스킬은 다른 스킬을 참조하거나 스킬을 파일 컨텍스트와 결합할 수 있습니다.

> $code-review Review @src/auth.py following $security-guidelines

원격 스킬¶

Git 리포지토리에서 원격 스킬을 추가할 수 있습니다. 리포지토리에는 원하는 수의 스킬이 포함될 수 있습니다. 원격 스킬의 레이아웃은 로컬 스킬 구조와 일치해야 합니다.

/skill add https://github.com/org/my-skills.git

원격 스킬은 로컬에 캐시됩니다. 업데이트하려면 ``/skill sync``를 사용합니다.

스킬 명령 참조¶

CLI 명령:

cortex skill list
cortex skill add <path>
cortex skill remove <path>

슬래시 명령:

/skill list
/skill add <path>

스킬 문제 해결¶

스킬이 활성화되지 않음

• 스킬의 목적과 관련된 특정 언어 사용

• 스킬을 명시적으로 언급: “의미체계-뷰-최적화 사용”

• 가용성 확인: /skill list

예상 동작

• 목표에 대한 더 많은 컨텍스트 제공

• 더 구체적인 요청 시도하기

• 피드백 제출: /feedback

기본 제공 하위 에이전트 유형¶

하위 에이전트 실행¶

Cortex Code는 적절한 경우 자동으로 하위 에이전트에 위임합니다. 예를 들어, 이 쿼리는 탐색 에이전트에 위임합니다.

> Find all files that import the authentication module

이름으로 특정 하위 에이전트 유형을 명시적으로 요청할 수도 있습니다.

> Use an Explore agent to find all database query definitions
> Use the Explore agent to find all API endpoint definitions
> Launch a Plan agent to design the authentication refactor

여러 하위 에이전트를 병렬로 실행하여 태스크의 다양한 측면을 처리하도록 요청할 수도 있습니다.

> In parallel, search for all test files and all config files

작업을 계속하는 동안 에이전트는 백그라운드에서 실행할 수 있습니다.

> Run a background agent to refactor all the test files

에이전트가 즉시 시작되고 추적을 위한 에이전트 ID를 반환합니다. 에이전트가 완료되면 해당 ID를 사용하여 출력을 검색할 수 있습니다.

> Get the output from agent abc1234

실행 중인 모든 하위 에이전트의 상태를 모니터링하려면 /agents 명령(또는 Ctrl-B 누르기)을 사용하여 백그라운드 프로세스 뷰어를 엽니다. 해당 ID 또는 /agents 인터페이스를 사용하여 실행 중인 에이전트를 중지할 수 있습니다.

> kill agent abc1234

종료된 에이전트는 실행을 중지하지만 컨텍스트는 무기한 유지합니다. 해당 ID를 사용하여 종료된 에이전트를 재개할 수 있습니다.

> Resume agent abc1234 and continue from where it left off

에이전트 유형¶

자율

자율 에이전트는 사용자 상호 작용 없이 실행됩니다. 에이전트의 특징은 다음과 같습니다.

• 독립적으로 완료함

• 질문을 위해 차단되지 않음

• 잘 정의된 작업에 적합

비자율

비자율 에이전트는 실행을 일시 중지하여 사용자에게 질문할 수 있습니다. 에이전트의 특징은 다음과 같습니다.

• 명확한 질문을 할 수 있음

• 대화형으로 권한을 요청할 수 있음

• 지침이 필요한 작업에 적합

Custom

사용자 지정 에이전트는 전문적인 프롬프트 및 구성을 갖춘 사용자 정의 하위 에이전트입니다. 사용자 지정 스킬과 유사하게 마크다운 파일에서 특정 도메인 또는 워크플로에 맞게 조정된 에이전트를 생성합니다.

사용자 지정 하위 에이전트 생성¶

사용자 지정 하위 에이전트는 YAML 전문을 사용하여 마크다운 파일에 정의됩니다. 전문에는 에이전트의 이름, 설명, 도구 액세스, 모델이 지정됩니다. 본문에는 에이전트의 동작을 안내하는 시스템 프롬프트가 포함되어 있습니다.

사용자 지정 에이전트 마크다운 파일은 다음 세 위치 중 하나에 저장할 수 있습니다.

에이전트 정의의 형식은 다음과 같습니다.

---
name: my-agent
description: What this agent specializes in
tools:

- Bash
- Read
- Write

model: claude-sonnet-4-5
---

# System Prompt

You are a specialized agent for [domain].

## Your Responsibilities

1. Task 1
2. Task 2

## Guidelines

- Guideline 1
- Guideline 2

## Output Format

Describe expected output format.

---
name: test-runner
description: Runs tests and reports results
tools:
- Bash
- Read
- Grep
---

# Test Runner Agent

You run tests and provide clear reports of the results.

## Process

1. Identify the test framework (pytest, jest, go test, etc.)
2. Run appropriate test command
3. Parse and summarize results
4. Highlight failures with relevant code context

## Output Format

## Test Results Summary
- Total: X
- Passed: Y
- Failed: Z

## Failures
### Test Name
- File: path/to/file.py
- Error: Description
- Relevant code snippet

작업 격리¶

에이전트는 격리된 git 작업 트리 또는 분기에서 실행할 수 있습니다. 작업 트리 격리를 요청하는 경우 Cortex Code CLI는 에이전트가 작동할 별도의 git 작업 트리를 생성합니다. 이를 통해 변경 사항 충돌 없이 여러 에이전트를 병렬로 실행할 수 있으며 나중에 쉽게 정리할 수 있습니다. 격리된 작업 트리는 탐색과 실험에 특히 유용합니다. 에이전트가 생성한 git 분기의 이름은 ``agent/<agentId>``입니다

작업 트리 격리를 사용하려면 프롬프트에 포함하기만 하면 됩니다.

> Run a background agent with worktree isolation to implement feature X

스웜 패턴¶

에이전트 스웜을 시작하여 복잡한 태스크의 다양한 측면을 병렬로 처리할 수 있습니다. 각 에이전트는 독립적으로 작동하며 모든 에이전트가 완료되면 결과가 집계됩니다. 모든 유형의 에이전트가 스웜에 참여할 수 있습니다.

스웜의 사용 사례는 다음과 같습니다.

• 코드 분석: 여러 에이전트가 다양한 측면 분석

• 리팩터링: 병렬 에이전트가 다른 파일 처리

• 테스트: 에이전트가 다양한 테스트 모음 실행

• 설명서: 에이전트가 다양한 구성 요소 문서화

스웜을 생성하려면 실행할 다양한 에이전트를 설명하면 됩니다.

> Launch a swarm of agents:
> 1. Explore agent to find all database queries
> 2. Explore agent to find all API endpoints
> 3. Explore agent to find all test files

하위 에이전트 모범 사례¶

다음을 위해 하위 에이전트를 사용합니다.

• 복잡한 태스크: 병렬 실행을 위해 하위 태스크로 나누기

• 탐색: 코드베이스 검색을 위해 탐색 에이전트 사용

• 계획: 주요 변경 전에 계획 에이전트 사용

• 백그라운드 작업: 주의가 필요하지 않은 장기 실행 태스크

하위 에이전트는 다음과 같은 경우에는 적합하지 않을 수 있습니다.

• 간단한 쿼리: 직접 도구가 더 빠름

• 단일 파일 편집: 기본 에이전트가 더 효율적임

• 대화형 작업: 즉각적인 피드백이 필요한 경우

일반적으로 자세한 프롬프트가 더 효과적입니다.

활성 하위 에이전트 보기¶

/agents 명령

Cortex Code 세션에서 /agents 명령을 실행하여 대화형 에이전트 뷰어를 엽니다. 이 인터페이스에는 실행 중인 모든 에이전트, 해당 유형, 상태, 출력 미리 보기가 표시됩니다.

백그라운드 프로세스 뷰어

Cortex Code CLI 세션에서 Ctrl-B를 눌러 다음을 확인합니다.

• 모든 백그라운드 프로세스

• 에이전트 세션

• Bash 프로세스

에이전트 제한¶

Cortex Code CLI의 하위 에이전트에는 다음 제한 사항이 적용됩니다.

• 최대 50개의 동시 백그라운드 에이전트

• 에이전트가 세션 권한을 상속함

• 백그라운드 에이전트는 다른 백그라운드 에이전트를 생성할 수 없음

후크 이벤트¶

다음 이벤트는 후크를 트리거할 수 있습니다.

후크 구성하기¶

후크는 모든 구성 디렉터리에 있을 수 있는 설정 파일에 구성됩니다(아래에 가장 높은 우선순위부터 가장 낮은 우선순위까지 나열됨).

후크는 JSON 형식으로 정의되며, 이벤트, 도구 매처 및 후크 작업을 지정합니다. 도구 사용 전 후크의 간단한 예제는 아래와 같습니다.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/validate-bash.sh",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

명령 후크와 프롬프트 후크의 두 가지 후크 유형이 지원됩니다.

• 명령 후크는 셸 명령 또는 스크립트를 실행합니다.

  {
    "type": "command",
    "command": "bash /path/to/script.sh",
    "timeout": 60,
    "enabled": true
  }
  

  Copy

• 프롬프트 후크는 언어 모델에 대한 자연어 프롬프트로 평가됩니다.

  {
    "type": "prompt",
    "prompt": "Is this command safe? $ARGUMENTS",
    "timeout": 30
  }
  

  Copy

특정 도구에서만 후크를 실행하려면 matcher 필드에 도구 이름이나 패턴을 배치합니다. 예를 들어, 모든 SQL 도구와 일치시키려면 ``”matcher”: “SQL*”``을 사용합니다. 정규식을 사용하여 여러 도구를 일치시킬 수 있습니다.

후크 스크립트 작성¶

후크 스크립트는 표준 입력을 통해 JSON 입력을 수락하고 표준 출력을 통해 JSON 출력을 반환합니다. 출력에는 작업의 허용 또는 거부 여부를 나타내는 필드가 포함됩니다. 선택적으로, 후크 스크립트는 도구 입력의 수정된 버전을 다시 전달할 수 있습니다.

샘플 입력:

{
  "session_id": "abc123",
  "transcript_path": "/path/to/transcript.json",
  "cwd": "/working/directory",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "ls -la"
  }
}

샘플 출력:

{
  "decision": "allow",
  "systemMessage": "Note: This operation was validated.",
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "updatedInput": {
      "command": "ls -la --color=never"
    }
  }
}

반환 코드는 작업을 차단할지 여부를 나타냅니다.

• 0: 차단 안 함

• 2: 블록

이 정보는 아래와 같이 JSON 출력의 일부로 반환될 수도 있습니다.

{
  "decision": "block",
  "reason": "Operation not allowed"
}

후크 스크립트에서 사용할 수 있는 환경 변수는 다음과 같습니다.

후크 예제¶

다음 예제에서는 일반적인 후크 사용 사례에 대한 가능한 출력을 보여줍니다.

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "updatedInput": {
      "command": "modified command"
    }
  }
}

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "Note: File was recently modified."
  }
}

{
  "systemMessage": "Warning: This operation may take a while."
}

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "permissionDecisionReason": "Auto-approved by policy"
  }
}

{
  "type": "command",
  "command": "bash",
  "source": {
    "source": "github:org/hooks-repo/scripts/validate.sh",
    "ref": "main"
  }
}

Hook 모범 사례¶

• 후크를 빠르게 유지: 시간 제한 기본값은 60초입니다.

• 오류를 정상적으로 처리: 불확실한 경우 종료 0 반환

• 디버깅을 위한 로그: 문제 해결을 위해 파일에 쓰기

• 매처 사용: 모든 도구가 아닌 특정 도구를 대상으로 함

• 철저한 테스트: 후크 관리자를 사용하여 동작 확인

전송 유형¶

Cortex Code는 3가지 MCP 전송 유형을 지원합니다.

OAuth를 사용하여 HTTP MCP 서버에 인증할 수 있습니다. OAuth용으로 구성된 서버에 처음 연결하는 경우, Cortex Code CLI는 사용자가 인증하는 브라우저 윈도우를 엽니다. 결과 토큰은 :file:`~/.snowflake/cortex/mcp_oauth/`에 저장되며 필요에 따라 자동으로 새로 고침됩니다. 다음은 샘플 OAuth 구성입니다.

{
   "oauth": {
      "client_id": "pre-registered-client-id",
      "client_name": "My Client",
      "redirect_port": 8585,
      "scope": "openid mcp read write",
      "authorization_server_url": "https://auth.example.com"
   }
}

MCP 서버 관리하기¶

대화형 Cortex Code CLI 세션에서 /mcp 명령을 실행하여 대화형 MCP 상태 뷰어를 열 수 있습니다. ``cortex mcp``를 사용하여 명령줄에서 MCP 서버 구성을 관리합니다.

cortex mcp add <name> <command> [args...]

--transport, -t    Transport type (stdio, http, sse)
--type             Alias for --transport
--env, -e          Environment variable (KEY=value)
--header, -H       HTTP header
--timeout          Connection timeout in ms

mcp__{server-name}__{tool-name}

MCP 구성¶

MCP 서버 구성은 키 mcpServers 아래의 ``~/.snowflake/cortex/mcp.json``에 저장됩니다. 다음 예제에서는 단일 MCP 서버가 있는 구성 파일의 구조를 보여줍니다.

{
   "mcpServers": {
      "server-name": {
         "type": "stdio",
         "command": "command-to-run",
         "args": ["arg1", "arg2"]
      }
   }
}

{
"mcpServers": {
   "my-server": {
      "type": "http",
      "url": "https://api.example.com",
      "headers": {
      "Authorization": "Bearer ${MY_API_TOKEN}"
      }
   }
}

export GITHUB_TOKEN="your_token_here"

MCP 도구 사용¶

구성된 후 MCP 도구는 Cortex Code CLI 세션에서 자동으로 사용할 수 있습니다. 자연어 명령을 통해 호출합니다.

Show me recent GitHub pull requests
Create a Jira ticket for this bug
Query the PostgreSQL database for user activity

권한은 처음 사용할 때 요청됩니다. ``~/.snowflake/cortex/permissions.json``에서 기본값을 구성합니다.

{
  "allow": ["mcp__github__read_file", "mcp__github__list_repos"],
  "deny": ["mcp__github__delete_repo"]
}

MCP 구성 샘플¶

다음 예제에서는 일반적인 사용 사례를 위한 MCP 서버 구성을 보여줍니다.

{
  "mcpServers": {
    "git": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-server-git", "--repository", "/path/to/repo"]
    }
  }
}

{
  "mcpServers": {
    "my-api": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "oauth": {
        "client_id": "my-client-id",
        "redirect_port": 8585,
        "scope": "openid mcp"
      }
    }
  }
}

{
  "mcpServers": {
    "realtime": {
      "type": "sse",
      "url": "https://realtime.example.com/events",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}",
        "X-Custom-Header": "value"
      },
      "timeout": 30000
    }
  }
}

{
  "mcpServers": {
    "sourcegraph": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@sourcegraph/mcp-server"],
      "env": {
        "SRC_ACCESS_TOKEN": "${SOURCEGRAPH_TOKEN}",
        "SRC_ENDPOINT": "https://sourcegraph.company.com"
      }
    }
  }
}

MCP 문제 해결하기¶

서버가 연결되지 않음

• 세션 중에 ``/mcp``를 검사하여 목록에 있는지 확인

• ``cortex mcp start <server>``를 사용하여 연결 테스트

• 환경 변수에 자격 증명이 올바르게 설정되었는지 확인

• ``cat ~/.snowflake/cortex/logs/mcp.log``에서 로그를 검토하여 단서 확인

도구가 표시되지 않음

• ``cortex mcp list``를 실행하여 구성 확인

• 도구 이름이 유효한지 확인(영숫자 문자, 밑줄, 하이픈만 포함)

• 도구 이름이 64자 미만인지 확인

OAuth 문제

• 캐시된 토큰 지우기: rm ~/.snowflake/cortex/mcp_oauth/{server}*

• 다시 연결하여 새 OAuth 흐름 트리거

• 리디렉션 포트를 사용할 수 있는지 확인(기본값 8585)

환경 변수가 확장되지 않음

• $VAR 대신 ${VAR} 구문(중괄호 포함) 사용

• 셸에 변수가 설정되어 있는지 확인(echo $VAR)

• 변수 이름에 오타가 있는지 확인

MCP 모범 사례¶

• 설명이 포함된 서버 이름 사용: 도구 네임스페이스를 명확하게 생성

• 적절한 시간 제한 설정: 도구 목록의 기본값은 10분임

• 보안 자격 증명: 하드코딩된 시크릿이 아닌 환경 변수 사용

• 연결 테스트: 서버를 사용하기 전에 cortex mcp start 사용