본문 바로가기
프로그래밍/Util

[Superpowers] Codex 전역 제거와 프로젝트 단위 설치

by JLearn 2026. 8. 25.
반응형

Codex에서 Superpowers를 전역 플러그인으로 설치하면 여러 프로젝트에서 동일한 Superpowers 기능을 사용할 수 있습니다.

특정 프로젝트에서만 Superpowers를 사용하고 싶다면 전역 플러그인을 제거하고, 프로젝트 저장소의 .agents/skills 아래에 필요한 Superpowers skill을 배치하는 방법을 사용할 수 있습니다.

Codex 공식 문서에서는 저장소 범위의 로컬 skill을 현재 작업 디렉터리부터 Git 저장소 루트까지 존재하는 .agents/skills에서 탐색한다고 설명합니다. 사용자 전체에 적용되는 skill은 $HOME/.agents/skills에서 탐색합니다.

이 글에서는 Ubuntu 24.04와 Windows 11 환경에서 다음 구성을 기준으로 설명합니다.

전역 Superpowers 플러그인
        ↓
       제거

프로젝트/
└── .agents/
    └── skills/
        ├── brainstorming/
        ├── systematic-debugging/
        ├── test-driven-development/
        └── ...

이 글의 목적은 Superpowers를 Codex의 전역 플러그인으로 사용하는 대신 특정 Git 프로젝트에서만 사용할 수 있도록 변경하는 것입니다.
플러그인 자체를 프로젝트 범위로 설치하는 것이 아니라, Superpowers가 제공하는 skill을 Codex의 저장소 범위 skill로 배치하는 방식입니다.

Codex skill 경로 이해하기

Codex 공식 문서에서는 skill 위치를 설명할 때 다음과 같은 표기를 사용합니다.

$CWD/.agents/skills
$REPO_ROOT/.agents/skills
$HOME/.agents/skills

이 표기들은 모두 같은 종류의 변수가 아닙니다. Ubuntu에서 실제로 사용할 수 있는 shell 변수와 Codex 문서에서 경로를 설명하기 위해 사용하는 표기를 구분해야 합니다.

표기 의미 확인 방법 예시
$HOME 현재 사용자의 홈 디렉터리 echo "$HOME" /home/user
$PWD 현재 shell의 작업 디렉터리 pwd 또는 echo "$PWD" /home/user/projects/system-service
$CWD Codex 공식 문서에서 현재 작업 디렉터리(Current Working Directory)를 나타내는 설명용 표기 실제 경로는 pwd로 확인 /home/user/projects/system-service
$REPO_ROOT Codex 공식 문서에서 Git 저장소의 최상위 디렉터리를 나타내는 설명용 표기 git rev-parse --show-toplevel /home/user/projects/system-service

따라서 Ubuntu shell에서 다음 두 변수는 실제로 사용할 수 있습니다.

echo "$HOME"
echo "$PWD"

예를 들어

cd ~/projects/system-service

echo "$HOME"
echo "$PWD"

결과는 다음과 비슷합니다.

/home/user
/home/user/projects/system-service

반면 다음 표현은 Codex 문서의 의미를 설명하기 위한 표기이므로 Ubuntu shell 변수라고 생각하면 안 됩니다.

$CWD
$REPO_ROOT

예를 들어 다음 명령은 일반적인 Ubuntu 환경에서는 의도대로 동작하지 않습니다.

echo "$CWD"
echo "$REPO_ROOT"

사용자가 별도로 같은 이름의 변수를 정의하지 않았다면 빈 값이 출력될 수 있습니다.

$CWD가 의미하는 현재 작업 디렉터리

Codex 공식 문서에서 $CWD는 Codex를 실행한 현재 작업 디렉터리를 의미합니다.

Ubuntu에서는 실제 현재 작업 디렉터리를 다음 명령으로 확인합니다.

pwd

예를 들어

cd ~/projects/system-service/system-api
pwd

결과가

/home/user/projects/system-service/system-api

라면 Codex 문서의 다음 표기는

$CWD/.agents/skills

실제로 다음 경로를 의미합니다.

/home/user/projects/system-service/system-api/.agents/skills

즉, $CWD를 명령어에 그대로 입력하는 것이 아니라 현재 작업 디렉터리라는 의미로 해석해야 합니다.

$REPO_ROOT가 의미하는 Git 저장소 루트

$REPO_ROOT도 Ubuntu에 기본으로 존재하는 환경 변수가 아닙니다.

Codex 공식 문서에서는 Git 저장소의 최상위 디렉터리를 설명하기 위해 $REPO_ROOT라는 표기를 사용합니다.

실제 Git 저장소 루트는 다음 명령으로 확인할 수 있습니다.

git rev-parse --show-toplevel

예를 들어 현재 위치가

/home/user/projects/system-service/system-api/src

이고 다음 명령을 실행했을 때

git rev-parse --show-toplevel

결과가

/home/user/projects/system-service

라면 Codex 문서의

$REPO_ROOT/.agents/skills

는 실제로 다음 경로를 의미합니다.

/home/user/projects/system-service/.agents/skills

$HOME과 $PWD는 실제로 사용할 수 있습니다

$HOME은 현재 사용자의 홈 디렉터리를 나타냅니다.

echo "$HOME"

예:

/home/user

따라서 다음 경로는 실제 shell 표현으로 사용할 수 있습니다.

$HOME/.agents/skills

예를 들어

ls "$HOME/.agents/skills"

는 일반적으로 다음 디렉터리를 확인하는 것과 같습니다.

/home/user/.agents/skills

$PWD는 현재 shell의 작업 디렉터리를 나타냅니다.

echo "$PWD"

예:

/home/user/projects/system-service

따라서 다음처럼 사용할 수도 있습니다.

ls "$PWD/.agents/skills"

다만 프로젝트 안에서 작업 중이라면 다음과 같이 상대 경로를 사용하는 편이 더 간단합니다.

ls .agents/skills

Codex가 저장소의 skill을 찾는 방식

Codex 공식 문서에 따르면 Git 저장소 안에서 실행할 경우 현재 작업 디렉터리부터 저장소 루트까지 올라가면서 각 디렉터리의 .agents/skills를 확인합니다.

예를 들어 다음 구조가 있다고 가정합니다.

/home/user/projects/system-service/
├── .agents/
│   └── skills/
│       └── 공통 프로젝트 skill
└── system-api/
    └── .agents/
        └── skills/
            └── system-api 전용 skill

다음 위치에서 Codex를 실행합니다.

cd /home/user/projects/system-service/system-api
codex

이때 의미상

$CWD
= /home/user/projects/system-service/system-api

$REPO_ROOT
= /home/user/projects/system-service

가 됩니다. 따라서 Codex는 다음 위치의 skill을 탐색할 수 있습니다.

/home/user/projects/system-service/system-api/.agents/skills
/home/user/projects/system-service/.agents/skills

여기서 중요한 점은 $CWD와 $REPO_ROOT라는 실제 변수가 생성되는 것이 아니라, Codex 문서에서 각각의 위치를 설명하기 위해 이 이름을 사용한다는 것입니다.

Windows 11에서의 경로 표현

Windows에서도 Codex 공식 문서의 $CWD와 $REPO_ROOT는 실제 Windows 환경 변수 이름으로 이해하면 안 됩니다.

프로젝트가 다음 위치에 있다고 가정합니다.

C:\projects\system-service

저장소 범위 skill은 다음 위치에 둘 수 있습니다.

C:\projects\system-service\.agents\skills

Windows 명령 프롬프트에서 현재 작업 디렉터리를 확인하려면

cd

현재 디렉터리를 변수 형태로 사용하려면

echo %CD%

PowerShell에서는

Get-Location

또는:

$PWD

를 사용할 수 있습니다.

정리하면 다음과 같습니다.

환경 홈 디렉터리 현재 작업 디렉터리 Git 저장소 루트
Ubuntu bash/zsh $HOME $PWD, pwd git rev-parse --show-toplevel
Windows CMD %USERPROFILE% %CD%, cd git rev-parse --show-toplevel
Windows PowerShell $HOME $PWD, Get-Location git rev-parse --show-toplevel
Codex 공식 문서의 설명용 표기 $HOME $CWD $REPO_ROOT

$HOME과 $PWD는 Ubuntu shell에서 실제 값을 확인하고 사용할 수 있습니다. 반면 $CWD와 $REPO_ROOT는 Codex 공식 문서가 각각 현재 작업 디렉터리와 Git 저장소 루트를 설명하기 위해 사용하는 표기이므로 실제 Ubuntu 환경 변수처럼 사용하면 안 됩니다.

전역 Superpowers 설치 상태 확인과 삭제

Superpowers는 현재 Codex 공식 플러그인 마켓플레이스를 통해 설치할 수 있습니다. Superpowers 공식 저장소에서도 Codex CLI에서 /plugins를 열고 superpowers를 검색해 설치하는 방법을 안내합니다.

따라서 Superpowers를 플러그인으로 설치했다면 파일을 직접 삭제하기보다 Codex의 플러그인 관리 기능으로 제거하는 것이 우선입니다.

Codex CLI를 실행합니다.

codex

Codex 안에서 다음 명령을 실행합니다.

/plugins

설치된 플러그인 목록에서 Superpowers를 선택한 뒤 Uninstall plugin을 실행합니다.

Codex 공식 문서에서는 CLI의 /plugins 브라우저에서 설치된 플러그인을 확인하고 설치·제거하거나 활성화 상태를 변경할 수 있다고 설명합니다.

플러그인을 제거한 뒤에는 새 Codex 세션을 시작하는 것이 좋습니다.

플러그인을 제거하면 해당 Codex 환경에서 플러그인 번들은 제거됩니다.
플러그인이 외부 connector를 함께 사용했다면 connector 연결까지 자동으로 해제되는 것은 아니므로 별도로 관리해야 합니다.

사용자 전역 skill도 함께 확인하기

플러그인을 제거했더라도 과거에 Superpowers skill을 직접 사용자 범위 위치에 설치했다면 별도의 skill이 남아 있을 수 있습니다.

Ubuntu:

find ~/.agents/skills -maxdepth 2 -name SKILL.md -print 2>/dev/null

Windows PowerShell:

Get-ChildItem "$HOME\.agents\skills" -Recurse -Filter SKILL.md -ErrorAction SilentlyContinue

Superpowers의 개별 skill은 반드시 superpowers라는 디렉터리 아래에 있는 것은 아닙니다.

예를 들어 다음과 같은 형태일 수 있습니다.

~/.agents/skills/
├── brainstorming/
├── systematic-debugging/
├── test-driven-development/
└── writing-plans/

따라서 다음처럼 superpowers라는 문자열만 검색해서는 전역 설치 여부를 완전히 판단할 수 없습니다.

find ~/.agents/skills -iname '*superpower*'

사용자 범위의 .agents/skills 내용을 직접 확인하는 것이 더 확실합니다.

$HOME/.agents/skills 전체를 무조건 삭제하면 직접 만든 다른 전역 skill까지 삭제될 수 있습니다.
각 디렉터리의 SKILL.md를 확인한 뒤 Superpowers에서 가져온 skill만 삭제하는 것이 안전합니다.

과거 Superpowers 설치 방식에서 사용한 다음 경로가 남아 있을 수도 있습니다.

~/.config/superpowers/

Ubuntu 확인:

ls -la ~/.config/superpowers 2>/dev/null

Windows PowerShell 확인:

Get-ChildItem "$HOME\.config\superpowers" -Force -ErrorAction SilentlyContinue

현재 사용하지 않는 과거 설치 경로임을 확인한 후 삭제합니다.

Ubuntu:

rm -rf ~/.config/superpowers

Windows PowerShell:

Remove-Item "$HOME\.config\superpowers" -Recurse -Force

그래도 찾지 못한 경우에는 superpowers로 디렉토리 검사작업을 진행하여 확인합니다.

Ubuntu 24.04에서 프로젝트 단위로 설치하기

예제로 프로젝트 위치를 다음과 같이 가정합니다.

/home/user/projects/system-service

프로젝트 루트로 이동합니다.

cd ~/projects/system-service

현재 실제 작업 디렉터리를 확인합니다.

pwd

예상 결과:

/home/user/projects/system-service

Git 저장소 루트도 확인합니다.

git rev-parse --show-toplevel

현재 작업 디렉터리와 저장소 루트가 모두 다음이라면:

/home/user/projects/system-service

이 프로젝트의 저장소 범위 skill 위치는 다음입니다.

/home/user/projects/system-service/.agents/skills

프로젝트용 skill 디렉터리를 생성합니다.

mkdir -p .agents/skills

Superpowers 공식 저장소를 임시 위치에 clone합니다.

rm -rf /tmp/superpowers
git clone https://github.com/obra/superpowers.git /tmp/superpowers

Superpowers의 skill을 프로젝트로 복사합니다.

cp -R /tmp/superpowers/skills/. .agents/skills/

복사가 끝나면 임시 저장소를 삭제합니다.

rm -rf /tmp/superpowers

설치 결과를 확인합니다.

find .agents/skills -maxdepth 2 -name SKILL.md -print

예:

.agents/skills/brainstorming/SKILL.md
.agents/skills/systematic-debugging/SKILL.md
.agents/skills/test-driven-development/SKILL.md
.agents/skills/writing-plans/SKILL.md
...

최종 구조는 다음과 같습니다.

system-service/
├── .agents/
│   └── skills/
│       ├── brainstorming/
│       │   └── SKILL.md
│       ├── systematic-debugging/
│       │   └── SKILL.md
│       ├── test-driven-development/
│       │   └── SKILL.md
│       └── ...
├── AGENTS.md
├── build.gradle
└── src/

프로젝트 루트에서 Codex를 실행합니다.

cd ~/projects/system-service
codex

Codex CLI에서는 다음 명령으로 사용 가능한 skill을 확인할 수 있습니다.

/skills

또는 $를 입력해 skill을 명시적으로 선택할 수 있습니다.

예:

$systematic-debugging

Codex는 사용자의 요청이 SKILL.md의 description과 일치하면 해당 skill을 자동으로 선택할 수도 있습니다.

skill 변경이 바로 반영되지 않는다면 Codex를 종료하고 다시 실행합니다.

Windows 11에서 프로젝트 단위로 설치하기

예제 프로젝트를 다음과 같이 가정합니다.

C:\projects\system-service

명령 프롬프트

프로젝트로 이동합니다.

cd /d C:\projects\system-service

현재 위치를 확인합니다.

cd

또는:

echo %CD%

Git 저장소 루트도 확인합니다.

git rev-parse --show-toplevel

프로젝트용 skill 디렉터리를 생성합니다.

mkdir .agents\skills

임시 위치에 Superpowers를 clone합니다.

rmdir /S /Q "%TEMP%\superpowers" 2>nul
git clone https://github.com/obra/superpowers.git "%TEMP%\superpowers"

Superpowers skill을 복사합니다.

xcopy "%TEMP%\superpowers\skills\*" ".agents\skills\" /E /I /Y

임시 저장소를 삭제합니다.

rmdir /S /Q "%TEMP%\superpowers"

설치 결과를 확인합니다.

dir .agents\skills

SKILL.md 파일까지 확인하려면:

dir .agents\skills\SKILL.md /S /B

프로젝트 루트에서 Codex를 실행합니다.

codex

Codex에서 다음 명령으로 확인합니다.

/skills

PowerShell

PowerShell에서는 다음과 같이 진행할 수 있습니다.

Set-Location "C:\projects\system-service"

Get-Location

New-Item -ItemType Directory -Force ".agents\skills" | Out-Null

Remove-Item "$env:TEMP\superpowers" -Recurse -Force -ErrorAction SilentlyContinue

git clone https://github.com/obra/superpowers.git "$env:TEMP\superpowers"

Copy-Item "$env:TEMP\superpowers\skills\*" ".agents\skills" -Recurse -Force

Remove-Item "$env:TEMP\superpowers" -Recurse -Force

확인:

Get-ChildItem ".agents\skills" -Recurse -Filter SKILL.md

PowerShell에서 현재 작업 디렉터리는 $PWD로도 확인할 수 있습니다.

$PWD

필요한 Superpowers skill만 설치하기

Superpowers의 모든 skill을 프로젝트에 복사할 필요는 없습니다.

예를 들어 다음 skill만 사용한다고 가정합니다.

brainstorming
systematic-debugging
test-driven-development
writing-plans
executing-plans
requesting-code-review
receiving-code-review
finishing-a-development-branch

Ubuntu:

rm -rf /tmp/superpowers
git clone https://github.com/obra/superpowers.git /tmp/superpowers

mkdir -p .agents/skills

cp -R /tmp/superpowers/skills/brainstorming .agents/skills/
cp -R /tmp/superpowers/skills/systematic-debugging .agents/skills/
cp -R /tmp/superpowers/skills/test-driven-development .agents/skills/
cp -R /tmp/superpowers/skills/writing-plans .agents/skills/
cp -R /tmp/superpowers/skills/executing-plans .agents/skills/
cp -R /tmp/superpowers/skills/requesting-code-review .agents/skills/
cp -R /tmp/superpowers/skills/receiving-code-review .agents/skills/
cp -R /tmp/superpowers/skills/finishing-a-development-branch .agents/skills/

rm -rf /tmp/superpowers

Windows PowerShell:

Remove-Item "$env:TEMP\superpowers" -Recurse -Force -ErrorAction SilentlyContinue
git clone https://github.com/obra/superpowers.git "$env:TEMP\superpowers"

New-Item -ItemType Directory -Force ".agents\skills" | Out-Null

$skills = @(
    "brainstorming",
    "systematic-debugging",
    "test-driven-development",
    "writing-plans",
    "executing-plans",
    "requesting-code-review",
    "receiving-code-review",
    "finishing-a-development-branch"
)

foreach ($skill in $skills) {
    Copy-Item "$env:TEMP\superpowers\skills\$skill" ".agents\skills" -Recurse -Force
}

Remove-Item "$env:TEMP\superpowers" -Recurse -Force

필요한 skill만 설치하면 프로젝트의 목적이 더 명확해지고 외부 skill 업데이트를 검토하기도 편합니다.

Git으로 프로젝트 skill 관리하기

프로젝트의 .agents/skills를 팀에서도 동일하게 사용하려면 Git에 포함할 수 있습니다.

확인:

git status

예:

Untracked files:
  .agents/

Git에 추가합니다.

git add .agents/skills
git commit -m "Add project Codex skills"

다른 개발자가 저장소를 clone하면 프로젝트에 포함된 skill도 함께 내려받게 됩니다.

git clone <repository-url>
cd system-service
codex

이 경우 각 개발자가 Superpowers 플러그인을 전역으로 별도 설치하지 않아도 저장소의 skill을 사용할 수 있습니다.

개인적으로만 사용하려면 .gitignore에 추가할 수도 있습니다.

.agents/skills/

다만 다른 PC에서 저장소를 clone할 경우 다시 설치해야 합니다.

업데이트하는 방법

프로젝트에 직접 복사한 Superpowers skill은 전역 플러그인처럼 자동으로 갱신되는 것으로 가정하면 안 됩니다.

필요할 때 Superpowers 공식 저장소의 최신 내용을 다시 받아 변경 사항을 검토한 뒤 반영하는 것이 좋습니다.

Ubuntu:

cd ~/projects/system-service

rm -rf /tmp/superpowers
git clone https://github.com/obra/superpowers.git /tmp/superpowers

rm -rf .agents/skills
mkdir -p .agents/skills
cp -R /tmp/superpowers/skills/. .agents/skills/

rm -rf /tmp/superpowers

변경 내용을 확인합니다.

git diff -- .agents/skills

Windows PowerShell:

Set-Location "C:\projects\system-service"

Remove-Item "$env:TEMP\superpowers" -Recurse -Force -ErrorAction SilentlyContinue
git clone https://github.com/obra/superpowers.git "$env:TEMP\superpowers"

Remove-Item ".agents\skills" -Recurse -Force
New-Item -ItemType Directory -Force ".agents\skills" | Out-Null

Copy-Item "$env:TEMP\superpowers\skills\*" ".agents\skills" -Recurse -Force

Remove-Item "$env:TEMP\superpowers" -Recurse -Force

업데이트 후 Git diff를 확인합니다.

git diff -- .agents/skills

외부 skill의 최신 버전을 프로젝트에 바로 덮어쓰기보다 변경 내용을 검토한 뒤 반영하는 것이 좋습니다.
SKILL.md는 Codex의 작업 방식에 영향을 주는 지침이므로 일반 소스 코드 변경과 마찬가지로 검토하는 편이 안전합니다.

설치 확인과 경로 문제 해결

설치 후 가장 먼저 확인할 것은 Codex를 어느 디렉터리에서 실행했는가입니다.

Ubuntu:

pwd
git rev-parse --show-toplevel

Windows 명령 프롬프트:

cd
git rev-parse --show-toplevel

Windows PowerShell:

Get-Location
git rev-parse --show-toplevel

예를 들어 프로젝트가:

/home/user/projects/system-service

이고 skill이:

/home/user/projects/system-service/.agents/skills

에 있다면 프로젝트 내부에서 Codex를 실행하는 것이 가장 명확합니다.

cd ~/projects/system-service
codex

설치된 skill을 확인합니다.

/skills

특정 skill을 명시적으로 호출할 수도 있습니다.

$systematic-debugging

예:

$systematic-debugging

Spring Boot 애플리케이션에서 발생하는 Connection reset 원인을 분석해줘.

skill이 보이지 않는다면 디렉터리 구조를 확인합니다.

프로젝트/
└── .agents/
    └── skills/
        └── <skill-name>/
            └── SKILL.md

Ubuntu:

find .agents/skills -maxdepth 2 -name SKILL.md -print

Windows PowerShell:

Get-ChildItem ".agents\skills" -Recurse -Filter SKILL.md

Codex 공식 문서에서는 skill 변경을 자동으로 감지하지만, 변경이 보이지 않을 경우 Codex를 재시작하도록 안내합니다.

권장 구성

전역과 프로젝트 skill을 다음처럼 분리하면 관리하기 편합니다.

Ubuntu 예:

/home/user/
└── .agents/
    └── skills/
        └── 모든 프로젝트에서 사용할 개인 skill

/home/user/projects/
└── system-service/
    ├── .agents/
    │   └── skills/
    │       ├── brainstorming/
    │       ├── systematic-debugging/
    │       ├── test-driven-development/
    │       └── ...
    ├── AGENTS.md
    ├── build.gradle
    └── src/

Windows 예:

C:\Users\<사용자>\
└── .agents\
    └── skills\
        └── 모든 프로젝트에서 사용할 개인 skill

C:\projects\
└── system-service\
    ├── .agents\
    │   └── skills\
    │       ├── brainstorming\
    │       ├── systematic-debugging\
    │       ├── test-driven-development\
    │       └── ...
    ├── AGENTS.md
    ├── build.gradle
    └── src\

현재 목표라면 다음 흐름으로 구성할 수 있습니다.

Codex /plugins
    ↓
Superpowers Uninstall plugin
    ↓
사용자 범위 .agents/skills 확인
    ↓
프로젝트/.agents/skills 생성
    ↓
필요한 Superpowers skill 복사
    ↓
프로젝트 루트에서 Codex 실행
    ↓
/skills로 확인

핵심은 다음과 같습니다.

Codex 문서의 $CWD
    = 현재 작업 디렉터리를 나타내는 설명용 표기

Ubuntu의 $PWD
    = 실제 shell에서 현재 작업 디렉터리를 나타내는 값

Windows CMD의 %CD%
    = 현재 작업 디렉터리

Windows PowerShell의 $PWD
    = 현재 작업 디렉터리

이 차이를 구분하면 .agents/skills의 실제 설치 위치를 훨씬 쉽게 이해할 수 있습니다.

참고 자료

반응형
저작자표시 비영리 변경금지 (새창열림)

'프로그래밍 > Util' 카테고리의 다른 글

[Orca] Ubuntu 24.04와 Windows 11에서 Orca IDE 설치하기  (0) 2026.07.30
[Orca] Orca IDE에서 WSL 프로젝트 연결하기  (0) 2026.07.30
[Bruno] Postman에서 Bruno로 전환하기  (0) 2026.07.08

관련글

댓글

티스토리툴바