using-superpowers

개요

using-superpowers 스킬이 하는 일

using-superpowers 스킬은 AI 에이전트를 위한 대화 부트스트래퍼입니다. 이 스킬은 에이전트가 다음을 어떻게 처리해야 하는지 정의합니다.

• 언제 스킬을 호출해야 하는지 결정하고, 필요할 때는 선택이 아닌 의무로 만들기
• 사용자 프롬프트, superpowers 스킬, 기본 시스템 동작 간의 지시 우선순위 정하기
• Claude Code, Gemini CLI 같은 서로 다른 플랫폼에서 스킬에 올바르게 접근하고 활성화하기
• 표준 "superpowers" 도구 이름을 플랫폼별 도구 이름으로 변환하기

이 스킬은 새로운 대화나 작업을 시작할 때마다 사용하는 것을 전제로 설계되었습니다. "해당 스킬이 적용될 여지가 조금이라도 있다면, 에이전트는 답변을 하기 전에, 심지어 추가 질문을 하기 전에라도 반드시 그 스킬을 먼저 호출해야 한다"는 공통 규약을 설정합니다.

using-superpowers 스킬의 대상 사용자

다음에 해당한다면 using-superpowers 스킬 사용을 추천합니다.

• Claude Code, Gemini CLI 또는 유사 환경을 설정하는 개발자인 경우
• 멀티 스킬·멀티 에이전트 워크스페이스를 운영하면서 일관된 동작을 원할 때
• obra/superpowers 리포지토리를 표준 스킬 라이브러리로 활용할 때
• 에이전트가 문서화된 절차를 반드시 따르고, 올바른 도구를 사용해야 하는 내부 워크플로우를 구축할 때

특히 코드 리뷰나 계획 수립 같은 관련 스킬을 놓치면 결과가 들쭉날쭉해지거나 안전성 체크가 생략되기 쉬운 규모가 큰 프로젝트에서 유용합니다.

이 스킬이 해결하는 문제

using-superpowers 스킬은 에이전트 기반 워크플로우에서 흔히 발생하는 다음 문제들을 완화합니다.

• 사용 가능한 스킬을 확인하지 않고 에이전트가 직관에 의존해 답변하는 경우
• 사용자 지시와 스킬 지시 중 무엇이 우선인지 모호한 상황
• Skill 도구 대신 스킬 파일을 직접 읽는 등 도구를 잘못 사용하는 문제
• Claude Code, Gemini CLI 및 기타 환경 간의 플랫폼 차이

using-superpowers를 설치하고 활성화하면 이러한 불일치를 줄이고, 스킬을 어떻게 찾아서 사용해야 하는지 명확하게 정리할 수 있습니다.

using-superpowers가 잘 맞는 경우와 아닌 경우

잘 맞는 경우:

• 여러 스킬을 사용하며, 이를 일관된 방식으로 반드시 따라야 하는 환경일 때
• 에이전트가 진행하기 전에 관련 스킬을 항상 먼저 확인하길 원할 때
• 여러 플랫폼을 동시에 사용하며 도구 이름 간 매핑이 필요한 경우
• superpowers 스타일의 스킬 라이브러리를 구축하거나 큐레이션 하는 중일 때

잘 맞지 않는 경우:

• 범위가 좁은 특정 작업을 위해 호출되는 단일 용도 서브에이전트인 경우 (이 스킬은 서브에이전트는 건너뛰라고 명시합니다)
• 추가 스킬이나 도구 연동 없이 극단적으로 단순한 설정만 사용하는 경우
• 스킬 호출 시점에 대한 엄격한 규칙 없이 자유로운 탐색형 행동을 원할 때

---

사용 방법

1. using-superpowers 스킬 설치

Skills CLI를 사용해 obra/superpowers 리포지토리에서 using-superpowers를 설치합니다:

npx skills add https://github.com/obra/superpowers --skill using-superpowers

이 명령은 using-superpowers 스킬 정의와 관련 레퍼런스 자료를 여러분의 스킬 환경으로 가져옵니다.

설치 후 이 스킬과 관련해 최소한 다음 파일들을 볼 수 있어야 합니다.

• SKILL.md — 핵심 동작 정의와 지시 우선순위 규칙
• references/codex-tools.md — Codex 스타일 환경용 도구 매핑
• references/gemini-tools.md — Gemini CLI용 도구 매핑

2. 서브에이전트 규칙 이해하기

이 스킬에는 서브에이전트 가드(subagent guard) 규칙이 포함되어 있습니다.

• 에이전트가 특정 작업을 수행하기 위해 서브에이전트로 디스패치된 경우, 이 스킬은 건너뛰어야 합니다.
• 이렇게 하면 서브에이전트는 자신이 맡은 작업에만 집중하고, 전역 스킬 동작을 다시 초기화하지 않게 됩니다.

워크플로우 설계자의 입장에서는 다음을 권장합니다.

• **주요 에이전트(primary agent)**가 대화를 시작할 때 using-superpowers를 호출하도록 보장하기
• 특정 작업을 위해 스폰되는 서브에이전트는 이 스킬을 다시 실행하지 않도록 구성하기

3. 지시 우선순위 모델 따르기

using-superpowers는 지시(Instructions)에 대한 명확한 계층 구조를 정의합니다.

1. 사용자 지시 — 최우선
   • 사용자의 직접 프롬프트
   • CLAUDE.md, GEMINI.md, AGENTS.md 같은 프로젝트 전용 파일
2. Superpowers 스킬 — using-superpowers 및 라이브러리의 다른 스킬들
3. 기본 시스템 프롬프트 / 모델 기본 동작 — 가장 낮은 우선순위

실제 의미는 다음과 같습니다.

• CLAUDE.md나 GEMINI.md의 내용이 스킬과 충돌하면 사용자 파일이 우선합니다.
• Superpowers 스킬은 사용자 지시와 모순되지 않는 범위에서만 기본 모델 동작을 덮어쓸 수 있습니다.
• 사용자 지시나 스킬이 적용되지 않는 부분은 기본 시스템 프롬프트가 보완합니다.

환경을 구성할 때, 이 모든 소스가 에이전트에 의해 확인 가능하며, 주요 에이전트가 이 우선순위를 인지하도록 설정해야 합니다.

4. 의무적인 스킬 호출 강제하기

using-superpowers의 핵심 규칙 중 하나는, 관련성이 있는 경우 스킬 호출이 **의무적(mandatory)**이라는 점입니다.

• 현재 작업에 스킬이 적용될 가능성이 1%라도 있다면, 에이전트는 반드시 그 스킬을 호출해야 합니다.
• 관련 스킬이 있을 수 있는 상황에서는 에이전트가 답변을 하거나 추가 질문을 하기 전에 해당 스킬을 호출해야 합니다.

이 규칙의 목적은 다음과 같습니다.

• 중요한 안전 규칙이나 워크플로우 로직을 담은 스킬을 에이전트가 건너뛰지 못하게 방지
• 에이전트가 즉흥적으로 처리하기 전에 스킬 우선(skills-first) 접근으로, 먼저 적절한 스킬을 찾고 활용하게 장려

개발자 입장에서는 이 규칙을 다음처럼 활용할 수 있습니다.

• 조직 차원의 에이전트 운영 정책 일부로 간주하기
• 대화 초반에는 에이전트가 답변 전에 스킬을 호출할 수 있다는 점을 사용자에게 미리 안내하기

5. 플랫폼별 올바른 스킬 접근 방식 사용하기

using-superpowers는 플랫폼마다 스킬에 접근하는 방법을 정의합니다.

Claude Code

• 스킬 호출에는 Skill 도구를 사용합니다.
• 스킬을 호출하면 해당 스킬의 내용이 로드되어 에이전트에게 제공되며, 에이전트는 이를 직접 따라야 합니다.
• 에이전트는 스킬 파일을 열기 위해 Read 도구를 사용해서는 안 되며, 이 목적에는 반드시 Skill 도구를 사용해야 합니다.

Gemini CLI

• 스킬은 activate_skill 도구를 통해 활성화됩니다.
• Gemini는 세션 시작 시 스킬 메타데이터를 로드하고, 필요할 때 전체 내용을 온디맨드로 활성화합니다.
• 스킬이 활성화되면 에이전트는 해당 스킬이 제공하는 지시를 따라야 합니다.

기타 환경

Claude Code와 Gemini CLI 이외의 환경에서는 다음을 참고하세요.

• 사용하는 플랫폼의 문서를 참고해 스킬 활성화나 도구 기반 워크플로우를 어떻게 처리하는지 확인합니다.
• 이 리포지토리의 레퍼런스를 활용해, 일반적인 "superpowers" 도구 이름을 여러분의 플랫폼 도구 이름으로 매핑하는 방법을 설계할 수 있습니다.

6. Codex 스타일 환경으로 도구 매핑하기

Codex CLI 또는 유사한 환경을 사용하는 경우 다음 문서를 읽으세요.

• references/codex-tools.md

이 레퍼런스에서 다루는 핵심 개념은 다음과 같습니다.

• 스킬은 기본적으로 Claude Code 도구 이름을 사용합니다.
• 파일에는 superpowers 도구와 Codex 도구 간 매핑 테이블이 포함되어 있으며, 예를 들면:
  • Task → spawn_agent
  • 여러 번의 Task 호출 → 여러 번의 spawn_agent 호출
  • Task 결과 → wait
  • Task 완료 → close_agent
  • TodoWrite → update_plan
  • Skill → 네이티브 스킬 처리
  • Read / Write / Edit / Bash → 해당하는 Codex 파일 및 쉘 도구

또한 다음 내용도 문서화합니다.

• ~/.codex/config.toml에 다음 설정을 추가해 Codex에서 멀티 에이전트 지원을 활성화하는 방법:

[features]
multi_agent = true

• Codex에 이름이 있는 에이전트 레지스트리가 없을 때 named agent dispatch를 처리하는 방법 — 예를 들어 agents/code-reviewer.md 같은 프롬프트 파일을 읽고, 플레이스홀더를 채운 뒤, 해당 프롬프트를 가진 worker 에이전트를 스폰하는 방식 등.

7. Gemini CLI로 도구 매핑하기

Gemini CLI를 사용하는 경우 다음 문서를 읽으세요.

• references/gemini-tools.md

이 문서에서는 표준 superpowers 도구가 Gemini CLI 도구로 어떻게 매핑되는지 설명합니다. 예를 들어:

• Read → read_file
• Write → write_file
• Edit → replace
• Bash → run_shell_command
• Grep → grep_search
• Glob → glob
• TodoWrite → write_todos
• Skill → activate_skill
• WebSearch → google_web_search
• WebFetch → web_fetch

또한 다음 사항을 함께 다룹니다.

• Gemini CLI는 서브에이전트를 지원하지 않습니다 — Task 도구에 해당하는 기능이 없습니다.
• subagent-driven-development, dispatching-parallel-agents 같은 서브에이전트 의존 스킬은 executing-plans 같은 다른 계획 스킬을 통해 단일 세션 실행 패턴으로 자동 폴백합니다.
• Gemini CLI에는 list_directory, save_memory, ask_user, tracker_create_task, enter_plan_mode / exit_plan_mode처럼 Claude Code에는 직접 대응되는 기능이 없는 추가 도구도 포함됩니다.

8. 추천 학습 순서

새 워크스페이스에서 using-superpowers를 최대한 잘 활용하려면 다음 순서를 권장합니다.

1. SKILL.md부터 시작하기
   • 지시 우선순위와 의무적인 스킬 호출 규칙을 이해합니다.
2. Codex 또는 유사 환경을 사용한다면 references/codex-tools.md 열기
   • 멀티 에이전트 지원과 도구 매핑을 설정합니다.
3. Gemini CLI를 사용한다면 references/gemini-tools.md 열기
   • 도구 매핑과 서브에이전트 미지원 사항을 파악합니다.

이후에는 이 패턴을 여러분의 도구·설정 파일에 맞게 확장해 적용할 수 있습니다.

---

자주 묻는 질문(FAQ)

using-superpowers 스킬은 어떻게 설치하나요?

Skills CLI를 사용해 obra/superpowers 리포지토리에서 추가하면 됩니다.

npx skills add https://github.com/obra/superpowers --skill using-superpowers

설치 후에는 핵심 규칙이 담긴 SKILL.md와, 플랫폼별 도구 매핑이 담긴 references/ 폴더를 확인하세요.

에이전트는 언제 using-superpowers를 실행해야 하나요?

using-superpowers 스킬은 주요 에이전트가 대화나 작업을 시작할 때 실행하도록 설계되었습니다. 특히 에이전트가 다음을 수행하려 할 때 사용합니다.

• superpowers 스킬이 있는 프로젝트에서 작업을 시작할 때
• 새로운 요청에 대해 어떤 스킬을 사용할지 결정할 때
• 멀티 도구·멀티 플랫폼 개발 환경에서 동작할 때

좁은 범위의 작업을 위해 디스패치된 서브에이전트는 이 스킬을 건너뛰고, 전달받은 프롬프트나 지시를 그대로 따르면 됩니다.

using-superpowers가 사용자 지시를 덮어쓰나요?

아니요. 이 스킬은 사용자 지시가 항상 최우선이라고 명시합니다. 지시 우선순위는 다음과 같습니다.

1. 사용자 지시 (CLAUDE.md, GEMINI.md, AGENTS.md 및 직접 프롬프트 포함)
2. using-superpowers를 포함한 superpowers 스킬
3. 기본 시스템 프롬프트 동작

사용자 지시와 스킬이 충돌하는 경우, 에이전트는 반드시 사용자 지시를 따릅니다.

“의무적인 스킬 호출(mandatory skill invocation)”이 실제로는 어떤 의미인가요?

의무적인 스킬 호출이란 다음을 뜻합니다.

• 현재 작업에 스킬이 적용될 현실적인 가능성이 조금이라도 있다면, 에이전트는 그 스킬을 호출해야 합니다.
• 관련 스킬이 존재할 수 있는 상황에서는, 에이전트가 먼저 답변을 하거나 추가 질문을 해서는 안 됩니다.

이를 통해 다음을 보장합니다.

• 안전성·워크플로우 관련 스킬이 일관되게 적용됩니다.
• 에이전트가 즉흥적으로 처리하기보다는 검증된 절차에 의존합니다.

using-superpowers는 Claude Code에 어떤 영향을 주나요?

Claude Code에서의 동작은 다음과 같습니다.

• 에이전트는 using-superpowers를 포함한 스킬을 로드하고 따르기 위해 Skill 도구를 사용해야 합니다.
• 스킬 파일을 직접 열기 위해 Read 도구를 사용해서는 안 되며, 해당 목적에는 Skill 도구만 사용해야 합니다.
• using-superpowers가 활성화되면 에이전트는 이 스킬이 정의한 지시 우선순위와 스킬 호출 규칙을 따릅니다.

같은 리포지토리의 다른 스킬과 조합하면, 스킬 중심의 견고한 개발 워크플로우를 구성할 수 있습니다.

using-superpowers는 Gemini CLI에서는 어떻게 동작하나요?

Gemini CLI에서는 다음과 같이 동작합니다.

• 스킬은 activate_skill 도구를 사용해 활성화됩니다.
• using-superpowers는 Gemini가 세션 시작 시 스킬 메타데이터를 로드하고, 요청 시 전체 내용을 활성화한다는 점을 설명합니다.
• superpowers 스킬에서 참조하는 도구 이름은 references/gemini-tools.md에서 Gemini CLI 도구로 매핑됩니다.

단, Gemini CLI는 서브에이전트를 지원하지 않는다는 점을 기억해야 합니다. 서브에이전트 디스패치에 의존하는 스킬은 자동으로 단일 세션 실행 패턴으로 폴백합니다.

다른 에이전트 플랫폼에서도 using-superpowers를 사용할 수 있나요?

네. 플랫폼이 스킬(skills) 또는 도구(tools) 개념을 지원한다면 사용할 수 있습니다.

• 동작과 지시 우선순위에 대한 단일 기준으로 SKILL.md를 참고하세요.
• references/codex-tools.md, references/gemini-tools.md를 확인해, superpowers 도구 이름을 플랫폼에 맞게 매핑하는 예시로 활용하세요.
• 여러분의 플랫폼 도구가 이 스킬이 기대하는 동작과 정렬되도록 유사한 매핑 레이어를 구현하면 됩니다.

플랫폼의 기능에 따라 매핑을 조정하거나 확장해야 할 수도 있습니다.

스킬을 설치한 후 먼저 읽어야 할 파일은 무엇인가요?

빠르고 실용적인 셋업을 위해서는 다음 순서를 추천합니다.

1. SKILL.md — 핵심 동작, 지시 우선순위, 의무적인 스킬 호출 규칙
2. references/codex-tools.md — Codex 또는 Codex 유사 환경을 사용하는 경우
3. references/gemini-tools.md — Gemini CLI를 사용하는 경우

이후 obra/superpowers 리포지토리의 다른 스킬을 탐색하면서, 더 완성도 높은 워크플로우를 구성할 수 있습니다.

using-superpowers만으로 충분한가요?

using-superpowers는 스킬을 어떻게 발견하고 적용할지에 대한 기반층을 제공합니다. 하지만 계획 수립, 코드 리뷰, 테스트 등 목적별 스킬과 함께 사용할 때 가장 큰 효과를 발휘합니다.

이 스킬을 에이전트 설정의 첫 레이어로 두고, 프로젝트 요구사항에 맞는 도메인 특화 스킬을 그 위에 추가해 구성하는 것을 추천합니다.