Matt Pocock의 retro 스킬 검토: 세션 회고로 코딩 에이전트 환경 고치기 · 첨부 자료 (retro_skill_review_thumbnail.png)



이 글은 저장소의 SKILL.md와 공식 문서, 변경 이력을 읽고 격리된 폴더에 직접 설치해 본 결과를 정리한 리뷰다. 2026년 10월 7일 기준 main 브랜치(v1.3.1)를 봤다.


Matt Pocock의 retro 스킬 검토: 세션 회고로 코딩 에이전트 환경 고치기

한눈에 보는 retro

하는 일 끝난 코딩 세션을 읽고 에이전트 환경의 개선 후보를 심각도순으로 제안

실행 방식 사용자가 직접 호출(Claude Code는 /retro, Codex는 $retro)

바꾸는 대상 코드가 아니라 환경. 사용자가 고르기 전에는 아무것도 수정하지 않음

주의할 점 첫 단계에서 writing-for-agents 스킬을 부르므로 함께 설치해야 함



01 retro는 어떤 스킬인가


retro는 코딩 세션의 기록을 읽고 에이전트가 고생한 지점을 찾는다. 그 원인이 된 환경, 즉 파일 안내, 자동 검사, 코딩 규칙, 도구 구성 중 무엇을 바꾸면 좋을지 후보 목록을 낸다.


버그를 직접 고치지는 않는다. 그 버그가 왜 생길 수 있었는지 묻고 다음에는 막아 줄 검사나 안내, 규칙을 제안한다.


GitHub의 retro SKILL.md · 출처: mattpocock/skills
GitHub의 retro SKILL.md · 출처: mattpocock/skills
01 retro는 어떤 스킬인가

항목

내용

저장소

mattpocock/skills (MIT 라이선스, GitHub 별 약 27.8만)

구성 파일

SKILL.md(44줄), agents/openai.yaml

실행 방식

사용자 호출 전용

처음 공개

2026년 8월 24일

정식 편입

2026년 9월 24일 v1.3.0에서 Engineering 묶음으로

설치 수

약 18.4만(skills.sh 집계)


스크립트는 없고 지시문만 있는 스킬이다. 실행 방식은 SKILL.md 머리말과 Codex용 설정 파일에 각각 적혀 있다.


---
name: retro
description: "Conduct a retrospective on a coding session."
disable-model-invocation: true
---


interface:
  display_name: "Retro"
  short_description: "Conduct a retrospective on a coding session."
policy:
  allow_implicit_invocation: false


두 설정은 각 호스트에서 retro의 자동 호출을 비활성화하려는 설정이다. 공식 문서상 Claude Code는 disable-model-invocation: true로 자동 호출을 막고, Codex는 allow_implicit_invocation: false여도 명시적인 $skill 호출은 허용한다. retro는 각각 /retro와 $retro로 직접 호출하는 구성이며, 이 설정 자체가 실행 중의 변경을 통제하는 별도 권한 장치는 아니다.


저장소가 제안하는 작업 흐름에서 retro는 마지막 단계다. grill-with-docs, to-spec, to-tickets, implement, code-review를 거친 뒤 이번 작업이 어떻게 흘러갔는지 돌아볼 때 쓴다.



02 설치 명령 뜯어보기


이번에 검토한 명령은 아래와 같다.


npx skills add https://github.com/mattpocock/skills --skill retro


npx skills는 Vercel Labs가 만든 에이전트 스킬 설치 CLI다. 저장소를 내려받아 SKILL.md가 있는 폴더를 찾고 고른 스킬을 에이전트별 스킬 폴더에 넣는다.


--skill retro는 저장소에 있는 38개 스킬 가운데 retro 하나만 고른다는 뜻이다. 에이전트를 지정하지 않으면 어느 에이전트에 설치할지 묻고 기본 설치 범위는 현재 프로젝트 폴더다. -g를 붙이면 사용자 전역에 설치된다.


격리된 임시 폴더에서 Claude Code와 Codex를 지정해 실제로 설치해 봤다(skills CLI 1.7.1). 설치된 파일은 아래 네 개다.


./.agents/skills/retro/SKILL.md
./.agents/skills/retro/agents/openai.yaml
./.claude/skills/retro -> ../../.agents/skills/retro
./skills-lock.json


원본은 .agents/skills/retro에 들어가고 Codex는 이 경로를 바로 읽는다. Claude Code용 .claude/skills/retro는 원본을 가리키는 심볼릭 링크다. skills-lock.json에는 출처 저장소와 파일 경로, 해시가 기록된다.


설치된 SKILL.md는 저장소 main 브랜치의 파일과 해시까지 같았다. 설치가 끝나면 CLI는 "스킬은 에이전트 권한 그대로 실행되니 쓰기 전에 검토하라"는 안내를 띄운다.


skills.sh의 retro 페이지. 설치 수와 보안 감사 결과가 함께 나온다 · 출처: skills.sh
skills.sh의 retro 페이지. 설치 수와 보안 감사 결과가 함께 나온다 · 출처: skills.sh

skills.sh 페이지에는 보안 감사 결과도 나온다. Gen Agent Trust Hub, Socket, Snyk 세 곳 모두 PASS였다.


CLI는 익명 사용 통계를 보낸다. 끄려면 DISABLE_TELEMETRY=1이나 DO_NOT_TRACK=1을 설정한다.



03 retro가 일하는 순서


SKILL.md의 절차는 네 단계다.


03 retro가 일하는 순서

단계

하는 일

1

writing-for-agents 스킬을 불러 에이전트용 문서 작성 규칙을 읽는다

2

세션 기록을 읽는다. 지정하지 않으면 현재 세션을 보고, 지난 세션은 이 컴퓨터의 세션 로그에서 찾는다

3

7개 범주에서 개선 후보를 찾는다

4

후보를 심각도순으로 사용자에게 보여 준다


7개 범주에는 각각 언제 볼지가 붙어 있다. 그래서 모든 범주를 기계적으로 채우기보다 세션에서 실제로 일어난 일에 맞는 범주만 보게 된다.


03 retro가 일하는 순서

범주

이럴 때 본다

고치는 방법

Navigation

파일이나 정보를 찾는 데 오래 걸렸을 때

에이전트가 이미 읽는 파일에 안내 포인터 추가

Automated checks

도구로 잡을 수 있는 실수를 했거나 가드레일이 아예 없을 때

린트 규칙, 타입, 테스트, pre-commit 훅, CI

Coding standards

리뷰 에이전트가 실수를 놓쳤을 때

기계적 위반은 자동 검사로, 판단이 필요한 것만 CODING_STANDARDS.md로

Global AGENTS.md

AGENTS.md가 지나치게 클 때

지시를 코딩 규칙이나 검사로 옮김

Tool economy

비용이 큰 도구 호출이 있었을 때

도구를 줄이거나 바꿈

No-ops

지시 파일이 비대할 때

행동을 바꾸지 않는 문장 삭제

Information access

핵심 정보에 접근하지 못했을 때

개발 서버 로그를 파일로 남기기, 외부 서비스 읽기 권한


범주별로 고칠 위치를 정리한 공식 문서 표 · 출처: AI Hero
범주별로 고칠 위치를 정리한 공식 문서 표 · 출처: AI Hero

04 설계에서 눈여겨볼 점


코딩 규칙은 리뷰어에게 맡긴다. 구현 에이전트는 탐색과 코딩, 디버깅을 모두 맡아 컨텍스트 부담이 가장 크다. 리뷰 에이전트는 diff만 받으므로 규칙을 적용할 여유가 있다.


기계적 위반은 문장이 아니라 검사로 막는다. 금지된 API, import 형태, 파일 위치 규칙처럼 패턴이 정해진 위반은 린트 규칙이나 pre-commit 훅, CI로 만든다. 9월 15일 커밋에서 추가된 원칙이다.


새 검사를 만들기 전에 있는 검사부터 본다. package.json의 lint·check 스크립트와 CI 설정을 먼저 읽고 연결되지 않았거나 고장 난 검사가 있으면 그것을 발견으로 보고한다. pre-commit 훅도 CI도 없는 저장소는 그 자체가 발견이다.


CLAUDE.md와 AGENTS.md는 최소로 둔다. 이 파일들은 모든 세션의 컨텍스트에 들어가므로 다른 문서로 가는 안내 포인터 정도만 남기라고 한다.


쓰지 않는 동안 컨텍스트 비용이 없다. Claude Code 문서에 따르면 disable-model-invocation: true인 스킬은 설명문도 컨텍스트에 올라가지 않고 호출할 때만 전체가 로드된다.


공식 문서는 약점도 숨기지 않는다. 한 세션만 보기 때문에 지난달 추가한 규칙이 지금도 필요한지는 판단하지 못하고 이 부분을 스스로 가장 약한 지점이라고 적었다.



05 검토하며 찾은 주의점


05 검토하며 찾은 주의점

주의점

내용

대응

writing-for-agents 의존성

첫 단계가 이 스킬을 부르지만 --skill retro만으로는 설치되지 않는다(직접 설치해 확인)

--skill writing-for-agents를 함께 지정한다

Claude Code 중심 표현

첫 단계의 Skill tool은 Claude Code의 도구 이름이다. Codex 문서에는 같은 이름의 도구가 없다

Codex에서는 $writing-for-agents처럼 스킬 이름을 직접 언급한다

세션 로그 위치

지난 세션을 볼 때 로그 위치를 에이전트가 찾아야 한다. Claude Code는 ~/.claude/projects 아래 평문 JSONL로 기본 30일, Codex는 CODEX_HOME(기본 ~/.codex) 아래에 남긴다

세션 ID나 로그 경로를 직접 알려 준다. 로그에 민감한 정보가 있을 수 있다

리뷰 흐름 전제

Coding standards 범주는 code-review 스킬 같은 리뷰 에이전트가 CODING_STANDARDS.md를 읽을 때 효과가 난다

리뷰까지 쓰려면 code-review도 설치한다

일반론 위험

작업이 끝난 뒤 중간의 어려움을 잊고 범주를 채우는 일반 조언을 낼 수 있다는 사용자 지적이 문서에 실려 있다

세션의 특정 순간으로 추적되지 않는 후보는 버린다


심각도 순서도 초안으로 보는 편이 맞다. 공식 문서도 조용하지만 비싼 실수가 요란하지만 사소한 실수보다 아래로 밀릴 수 있다고 적었다.


미리 돌려 보는 모드(dry-run)도 없다. 제안된 검사도 코드이니 머지를 막게 하기 전에 저장소 전체에 한 번 돌려 봐야 한다.



06 이렇게 쓰면 좋다


힘들었던 세션이 끝난 직후 같은 세션에서 /retro를 실행하는 것이 가장 좋다. 어려웠던 순간이 아직 컨텍스트에 남아 있기 때문이다.


세션이 너무 길어 컨텍스트가 흐려졌다면 정리하고 새 세션을 연 뒤 지난 세션 로그를 지정해 /retro를 실행한다.


순조롭게 끝난 세션 뒤에는 건너뛰어도 된다. 매 세션마다 돌리면 필요 없는 규칙만 쌓인다고 공식 문서도 말한다.


설치는 의존 스킬을 함께 넣는 쪽을 권한다. 모든 프로젝트에서 쓰려면 -g를 붙이고 리뷰 흐름까지 쓰려면 --skill code-review를 더한다.


npx skills add mattpocock/skills --skill retro --skill writing-for-agents -a claude-code -a codex


원저자가 제시한 효과 확인 기준은 반복되던 실수가 실패하는 검사로 바뀌는지, AGENTS.md가 시간이 갈수록 짧아지는지다. 이 글에서 두 효과를 장기 측정한 것은 아니다.



07 얼라이엑스의 정리


retro는 44줄짜리 작은 스킬이지만 원칙이 분명하다. 에이전트가 같은 실수를 하면 CLAUDE.md에 한 줄을 더하는 대신 검사나 리뷰 규칙으로 옮기라는 것이다.


다만 단독으로 설치하면 첫 단계의 의존 스킬이 빠지고 리뷰 에이전트와 코딩 규칙 흐름을 함께 쓸 때 효과가 커진다. 제안을 고르는 판단은 여전히 사람 몫이다.


얼라이엑스는 팀의 코딩 에이전트 환경, 즉 AGENTS.md와 스킬, 자동 검사 구성을 정비하는 일을 함께한다. 문의는 allaixlabs@gmail.com으로 하면 된다.




자주 묻는 질문


retro는 코드 리뷰나 자동 버그 수정 도구인가요?

주된 목적은 다르다. 원저자 문서에서 retro는 세션 기록을 근거로 다음 작업을 위한 환경 개선 후보를 제안한다. 기계적으로 판별 가능한 위반에는 자동 검사를, 판단이 필요한 문제에는 리뷰어가 읽는 규칙을 제안하는 방식이다. 사용자 선택 전에는 변경하지 않도록 설계됐지만, 지시문 기반 스킬이므로 실행 권한과 실제 변경은 별도로 확인해야 한다.


retro만 설치하면 Claude Code와 Codex에서 바로 같은 방식으로 작동하나요?

원문 검토에서는 --skill retro만 설치할 때 첫 단계가 요구하는 writing-for-agents가 함께 설치되지 않았다. Claude Code는 /retro, Codex는 $retro로 명시 호출하며, 의존 스킬도 함께 준비하는 편이 맞다. 설치 파일 확인만으로 호스트별 도구 호출이나 과거 세션 로그 탐색까지 정상 작동한다고 검증한 것은 아니다.


이 글은 retro가 실제 생산성을 높인다는 실험 결과인가요?

아니다. 원문이 보고한 직접 확인은 문서·이력 검토와 격리 폴더 설치, 파일 및 해시 확인이다. 회고 제안의 정확도, 실행 후 코드 품질, 장기적인 반복 실수 감소를 측정한 결과는 제시하지 않는다. 원저자도 한 세션만 보는 한계와 일반론 위험을 설명하므로 각 후보가 실제 세션의 특정 순간으로 추적되는지 확인해야 한다.


참고 자료



2026년 10월 7일 mattpocock/skills main 브랜치(v1.3.1)와 skills CLI 1.7.1로 확인했다. 스킬 내용은 저장소 업데이트에 따라 바뀔 수 있다.


기록 범위: 검토 기준은 2026년 10월 7일 main(v1.3.1)과 skills CLI 1.7.1이다. 문서·변경 이력 및 격리 폴더 설치 기록을 다루며, 회고 제안의 품질이나 장기적인 생산성 향상을 측정한 글은 아니다. 10월 28일에는 설명과 FAQ를 보완했고 설치·회고 실행을 다시 하지는 않았다.