pnpm 12.11.0 Skills 권한 실측: 한 번 승인한다는 건 정확히 무엇을 의미할까?

설명: pnpm v12.11.0 소스 코드와 해당 버전의 문서를 바탕으로 Skills의 탐색 범위, 승인 및 링크 동작을 정리하고, 독립적인 합성 모델로 핵심 분기를 검증해 개발자가 의존성 업그레이드와 권한 관리 방식을 평가할 수 있도록 돕습니다.

탐색 범위와 권한 경계

처음에는 문제를 단순하게 생각했습니다. 의존성에 SKILL.md가 추가되면 pnpm이 설치 시 이를 Agent 디렉터리에 넣거나, 아예 신경 쓰지 않을 거라고요. 하지만 pnpm 12.11.0의 특정 버전 소스를 따라가 보니 그 사이에 탐색, 권한 확인, 링크 생성 단계가 있었습니다. “한 번 승인”한다는 것이 무엇을 의미하는지 판단하려면 바로 이 경계들을 살펴봐야 합니다.

먼저 탐색 로직부터 추적했습니다. 의존성 트리에 Skill 파일이 있기만 하면 승인 절차에 들어갈 거라고 생각했죠. 하지만 실제 탐색 범위는 더 좁았습니다. pnpm은 lockfile에서 각 workspace importer의 직접 의존성을 확인하고, Skills 디렉터리도 한 단계만 스캔합니다. 간접 의존성은 이 탐색 경로에 포함되지 않으므로, “의존성 트리에 파일이 있다”와 “pnpm이 그 파일을 탐색한다”를 같은 의미로 봐서는 안 됩니다.

그다음에는 설치, 링크 생성, Agent 로딩을 분리해서 살펴봤습니다. 패키지 파일은 이미 의존성 디렉터리에 들어 있을 수 있습니다. 권한 상태에 따라 pnpm이 해당 파일의 대상 디렉터리 링크를 생성할지가 결정되고, 이후 Claude Code나 다른 Agent가 이를 읽는지, 어떻게 처리하는지는 각 클라이언트가 결정합니다. pnpm 소스가 다루는 것은 링크이지, Skill 콘텐츠를 파싱하거나 실행하는 것이 아닙니다.

권한 분기에는 승인 대기, 거부, 승인 상태가 있습니다. 승인은 패키지 단위 작업으로 처리되며, pnpm approve에는 빌드 스크립트와 Skills 권한이 모두 관련됩니다. 그렇다고 파일을 하나씩 검토한다는 뜻은 아닙니다. 빌드 스크립트 권한과 permissions.skills는 별개의 권한 영역입니다. 패키지의 빌드 스크립트가 승인되었다고 해서 Skill 콘텐츠까지 별도로 검토된 것은 아닙니다.

가장 오래 멈춰서 확인한 부분은 승인 범위였습니다. v12.11.0 공식 문서에 따르면 패키지 단위로 한 번 승인하면 해당 의존성의 모든 Skills가 승인되며, 이후 버전에도 그 승인이 이어집니다. 업그레이드 시에는 새 버전의 지시 내용이 바뀌었는지 살펴봐야 합니다. 이전 승인 상태가 여전히 적용되더라도 새 버전에서 Skill이 추가되거나 수정될 수 있습니다.

workspace에 사용 가능한 여러 버전이 동시에 있으면 소스는 설치된 적격 registry 버전 중 가장 높은 버전을 선택합니다. 따라서 실제로 어떤 콘텐츠가 링크되는지에 영향을 주며, package.json의 버전 범위만 확인해서는 충분하지 않습니다. 업그레이드 후 Agent가 어떤 콘텐츠를 읽을 수 있는지 판단하려면 실제로 선택된 패키지 버전과 그 안에 포함된 Skill도 확인해야 합니다.

대상 디렉터리에도 명확한 조건이 있습니다. v12.11.0은 CLAUDECODE, CURSOR_AGENT, GEMINI_CLI 환경 변수 또는 workspace에 이미 존재하는 Agent Skills 디렉터리를 참고합니다. skills.dirs를 사용하면 이를 명시적으로 재정의할 수 있습니다. 명시적으로 빈 값을 설정하면 Skills가 비활성화됩니다. 승인 시 자동으로 감지된 대상 디렉터리가 없으면 대상이 없다는 오류가 발생합니다.

# pnpm-workspace.yaml
skills:
  dirs:
    - .claude/skills
    - .cursor/skills

처음에는 권한을 철회하면 관련 디렉터리의 콘텐츠도 함께 삭제될 거라고 생각했습니다. 하지만 소스 코드와 독립 파일 시스템 모델에서 확인한 경계는 더 좁았습니다. 모델에서는 pnpm이 생성한 링크가 제거되지만, 수동으로 만든 로컬 Skill은 그대로 남습니다. 대상 경로가 실제 디렉터리로 점유되어 있으면 이를 대체하지 않습니다. 패키지 삭제나 대상 디렉터리 부재 등의 분기 역시 각각의 링크 정리 및 오류 처리 로직에 따라 이해해야 합니다.

합성 모델과 테스트 결과

각 분기를 구체적으로 확인하기 위해 Node 22.16.0 표준 라이브러리만 사용한 독립 합성 파일 시스템 모델을 작성했습니다. 임시 가짜 의존성, 합성 SKILL.md, 심볼릭 링크를 만들고 콘텐츠 지문을 계산했습니다. 여덟 가지 시나리오는 승인 대기, 거부, 승인, 업그레이드 후 Skill 추가, 권한 철회, 경로 충돌, 간접 의존성만 있는 경우, 자동으로 감지된 대상 디렉터리가 없는 경우를 각각 다뤘습니다.

모델의 여덟 가지 시나리오는 모두 통과했습니다. 업그레이드 시나리오에서는 콘텐츠 지문이 바뀌고 두 번째 Skill 링크가 생기는 것을 확인했습니다. 모델을 처음 실행했을 때는 승인된 Skill의 존재 여부를 “예상 링크 수가 0인지”로 판단해 한 시나리오가 실패했습니다. 대상 디렉터리가 없는 경우를 잘못 판정한 것이었습니다. 원인을 찾아 승인된 Skill의 수를 별도로 확인하도록 수정한 뒤 다시 실행하자 여덟 가지 모두 통과했습니다.

저장소 확인과 적용 범위

저장소를 확인할 때는 먼저 pnpm permissions 또는 pnpm permissions list로 권한을 살펴보고 workspace 설정과 대조할 수 있습니다. 의존성을 업그레이드한 뒤에는 새 버전에 포함된 Skills 파일과 변경 사항을 확인하세요. 지시 내용의 변동을 특히 우려하는 프로젝트라면 의존성 버전을 고정하고 CI에서 SKILL.md를 비교할 수 있습니다.

pnpm permissions
pnpm permissions list

경계 / 제한 사항

이번 분석은 pnpm v12.11.0 소스 코드와 해당 버전의 문서를 기준으로 했으며, 테스트에는 Node에서 독립적으로 실행되는 합성 모델을 사용했습니다. 범위는 파일 시스템 동작에 한정됩니다. 모델은 pnpm CLI, 실제 설치 및 업데이트, Agent와 연결되어 있지 않으며, 클라이언트의 탐색 및 실행 규칙도 각 클라이언트 버전에 따라 달라질 수 있습니다. pnpm 12.11.1의 환경 인식 변경 사항을 12.11.0의 기능으로 소급해서 해석해서는 안 됩니다. 패키지 단위 승인으로 인해 이후 버전까지 신뢰하게 되는 범위는 업그레이드 검토 시 고려해야 할 설계상의 경계입니다.

참고 링크: pnpm v12.11.0 소스 코드 · pnpm v12.11.0 문서