본문으로 건너뛰기
stepper

슬래시 커맨드, 스킬 & MCP

기본 제공 슬래시 커맨드, 권한으로 게이팅되는 치환을 지원하는 커스텀 커맨드, 점진적 공개 방식의 스킬, 그리고 MCP 서버 통합.

stepper의 기능은 세 가지 메커니즘으로 확장합니다. 인프로세스로 실행되는 기본 제공 및 커스텀 슬래시 커맨드, 컨텍스트를 가볍게 유지하기 위해 필요할 때 로드되는 스킬, 그리고 샌드박스화된 도구 접근을 제공하는 MCP 서버입니다. 모든 커스텀 콘텐츠는 fail-closed 시맨틱으로 권한 게이팅되며, 민감한 작업에는 명시적인 allow 규칙이 필요합니다.

기본 제공 슬래시 커맨드

다음 커맨드는 인프로세스로 처리되며 에이전트 턴을 실행하지 않습니다:

  • /help — 사용 가능한 모든 커맨드 나열
  • /clear — 대화/세션 초기화
  • /model [provider/model-id] — 활성 모델을 표시하거나 새 모델로 전환(모든 레이어에 적용하기 전에 검증됨)
  • /context — 활성 모델의 컨텍스트 윈도우 표시
  • /rename <name> — 현재 세션 이름 변경(세션 파일에 영속)
  • /export [path] — 세션 대화를 Markdown 전사로 저장(기본 .stepper/exports/<id>.md)
  • /rewind [code|conversation] — 이전 스냅샷 복원; 파일 트리/대화로 범위를 좁히거나 인자 없이 둘 다 복원

커스텀 슬래시 커맨드

커스텀 커맨드는 .stepper/commands/<name>.md 파일에 위치합니다. 각 파일은 YAML frontmatter(메타데이터)와 그 뒤에 치환을 지원하는 템플릿 본문으로 구성됩니다.

파일 형식과 호출

TUI에서 /를 입력하면 팔레트가 열리며, 여기서 항목을 선택하고 ↑↓로 이동하고 Tab으로 자동 완성하고 Enter로 실행할 수 있습니다. /name args 형태로 호출합니다. 기본 제공 커맨드는 같은 이름의 커스텀 커맨드 파일보다 우선합니다.

치환 구문

커맨드 템플릿은 다음 치환을 지원합니다:

  • !shell — 인라인 셸 코드 블록
  • $1, $2, … — 커맨드 호출 시 전달된 위치 인자
  • {file:path} 또는 @include path — 주어진 경로의 파일 읽기
  • {env:VAR} — 환경 변수 확장

권한 게이팅(fail-closed)

모든 치환은 fail-closed 시맨틱으로 권한 게이팅됩니다. 이는 심어진 커맨드 파일이 검증되지 않은 셸, 파일, 시크릿 접근을 프롬프트에 몰래 끼워 넣는 것을 방지합니다.
  • !shell 블록은 명시적인 allow 규칙이 일치할 때만 실행됩니다(예: "allow": ["Bash(git diff)"])
  • {file:…} 및 @include 읽기는 Read 규칙으로 게이팅됩니다
  • 시크릿 패턴(*_API_KEY, *_TOKEN, AWS_*, …)과 일치하는 환경 변수는 {env:…}로 절대 확장되지 않습니다
  • .stepper/ 아래로의 쓰기는 accept-edits 모드에서도 항상 명시적인 승인이 필요합니다 — 이 디렉터리가 에이전트 자체의 보안을 제어하기 때문입니다

스킬

스킬은 Claude-Code 방식의 점진적 공개 패턴을 따릅니다. 시스템 프롬프트는 스킬의 이름과 설명만 노출하고, 모델은 필요할 때 전체 본문을 로드합니다. 이를 통해 기본 컨텍스트 윈도우를 가볍게 유지합니다.

파일 형식

스킬은 .stepper/skills/<name>/SKILL.md에 저장되며, name과 description 키를 담은 YAML frontmatter와 그 뒤의 스킬 본문으로 구성됩니다.

스킬 선언 및 사용

레이어는 자신의 frontmatter skills: 목록에 사용할 수 있는 스킬을 선언합니다. 모델이 스킬이 필요할 때 {"name":"<skill>"}와 함께 skill 도구를 호출하여 전체 본문을 로드합니다. skill 도구는 레이어별로 범위가 지정되며 해당 레이어가 선언한 스킬만 제공합니다. 스킬은 팬아웃 워커에서도 사용할 수 있습니다.

MCP(Model Context Protocol) 서버

MCP 서버는 stepper 레이어에 도구와 리소스를 제공합니다. setting.json의 mcpServers 아래에서 전역으로 구성하며, stdio 또는 HTTP 서버로 실행할 수 있습니다.

구성

.stepper/setting.json에서 MCP 서버를 정의합니다:

jsonc
"mcpServers": {
  "context7": {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "@upstash/context7-mcp", "--api-key", "{env:CONTEXT7_KEY}"],
    "alwaysLoad": true                  // visible to every layer regardless of mcp.allow
  },
  "my-http": {
    "type": "http",
    "url": "https://example/mcp",
    "headers": { "Authorization": "Bearer {env:MY_TOKEN}" }
  }
}

도구 네임스페이스와 범위 지정

  • MCP 서버의 도구는 mcp__<server>__<tool> 형태로 네임스페이스가 지정됩니다
  • 모든 MCP 도구 사용은 권한 규칙으로 게이팅됩니다
  • 레이어별 범위 지정: 레이어는 자신의 레이어 구성에 있는 mcp.allow 목록을 통해 사용할 수 있는 MCP 서버를 선언합니다
  • alwaysLoad: true — 레이어별 범위 지정을 우회하여, mcp.allow와 관계없이 모든 레이어에서 서버를 볼 수 있게 합니다

HTTP 서버 헤더

HTTP 서버는 headers 객체를 지원합니다. Authorization 헤더는 특별하게 라우팅되며, 다른 헤더는 서버로 보내는 요청에 포함됩니다.