# Inject

> Patch an existing Apps in Toss mini-app's build setup. Three facets: `/ait:inject-devtools` adds the `@apps-in-toss/devtools` unplugin for browser dev, registered for whichever bundler the project uses ("기존 Vite 프로젝트에 devtools 붙여줘", "Rspack 쓰는 기존 프로젝트에 devtools 붙여줘"); `/ait:inject-debugger-client` installs `@apps-in-toss/debugger-client` (on-device attach) as a devDependency behind an opt-in build flag so release builds do not contain it; `/ait:inject-tossface` wires the Tossface emoji web font (CDN link or subset bundling) into the project's global stylesheet. Idempotent, minimal edits. This skill only INSTALLS packages/assets into a build setup — it never diagnoses a running app. "폰에서 이상하게 동작하는데 디버깅하고 싶어" / "라이브 상태를 보고 싶어" is `debug`, not this.

- Skill: `toss/inject` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx get-skill add toss/inject`
- Raw SKILL.md: https://api.skillmd.com/api/skills/toss/inject/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: toss (https://skillmd.com/u/toss)
- Updated: 2026-11-12
- Page: https://skillmd.com/skills/toss/inject

---


# inject skill

이 skill은 세 facet을 담는다 — `/ait:inject-devtools`(devtools unplugin 주입), `/ait:inject-debugger-client`(on-device attach 패키지 설치), `/ait:inject-tossface`(이모지 서체 Tossface 배선). 셋 다 기존 프로젝트의 빌드 셋업을 최소 변경으로 패치하는 brownfield station 2 도구라 하나로 묶였다(agent-plugin#280 debugger-client facet 추가). 사용자가 어느 command로 진입했는지에 따라 아래 해당 facet으로 분기한다 — 세 facet은 독립이며 서로를 자동 실행하지 않는다.

## 목적

이미 `@apps-in-toss/web-framework`를 쓰는 기존 미니앱 프로젝트의 개발 환경을 확장한다.
`new-miniapp`이 greenfield(빈 디렉토리)라면 이 skill은 **brownfield** — 기존 파일을 최소한으로
수정하고, 이미 설정이 있으면 skip한다. 어느 facet이든 생성·수정하는 파일에 과장·홍보성 문구를
넣지 않는다.

세 facet은 목적이 다르다:

- **devtools facet** (`/ait:inject-devtools`): `@apps-in-toss/devtools` unplugin을 빌드 config에
  추가해 토스 앱 없이 브라우저에서 mock SDK로 개발·테스트한다. 인자 없음.
- **debugger-client facet** (`/ait:inject-debugger-client`): `@apps-in-toss/debugger-client`(on-device
  attach)을 **`devDependencies`**로 설치하고, 빌드 타임 `__DEBUG_BUILD__` 게이트 import를
  진입점에, 그 값을 정하는 `define`을 번들러 설정에 와이어업한다. 기본 빌드는 값이 `false`라
  번들에 attach 코드가 들어가지 않고, `AIT_DEBUG_BUILD=1`을 명시한 디버그 빌드만
  `true`가 되어 환경 3(intoss-private) on-device 디버깅에 attach 표면을 남긴다.
  디버그 빌드는 검수·출시에 올리지 않는다.
  인자 없음.
- **tossface facet** (`/ait:inject-tossface`): 이모지를 토스페이스 글리프로 렌더하도록
  CDN 링크 또는 서체 subset 번들을 프로젝트 전역 스타일시트에 와이어업한다. `design` skill의
  서체 정책상 본문 서체는 금지 대상이지만 이모지 서체(Tossface)는 권장 대상이다. 인자 없음.

## devtools facet — `/ait:inject-devtools`

번들러는 스택을 가정하지 않고 프로젝트의 `package.json` scripts와 번들러 설정 파일에서 읽는다.
lockfile로 패키지 매니저를 감지해 `@apps-in-toss/devtools`를 devDep으로 설치한 뒤,
설치된 패키지 README(`node_modules/@apps-in-toss/devtools/README.md`)에서 그 번들러의 배선
절을 찾아 그대로 등록한다. 번들러별 코드는 이 skill이 들고 있지 않다. README가 다루지 않는
번들러면 사용자에게 알리고 묻는다. 이미 설정이 있으면 skip. 콘솔 인증 불필요 — 로컬 dev
전용이고, production 번들에는 넣지 않는다.

핵심 절차: (1) `package.json` 확인 → (2) 번들러 확인 → (3) PM 감지 → (4) idempotency
확인 → (5) devDep 설치 → (6) README의 해당 번들러 절대로 최소 변경 등록 → (6-1) dev 서버·빌드로
사후 검증 → (7) 완료 seam. README 읽는 법·지원 범위 밖 처리·유지할 앱인토스 고유 사실·하지
말아야 할 것은 —

**상세가 필요하면 Read `<이 skill의 base directory>/references/devtools.md`.**

## debugger-client facet — `/ait:inject-debugger-client`

`@apps-in-toss/debugger-client`을 **`devDependencies`**로 설치하고(harness GitHub Release
tarball URL — npm 미발행), 진입점에 빌드 타임 게이트 import를 멱등하게 삽입한다.

```ts
declare const __DEBUG_BUILD__: boolean;
declare const __AIT_RELAY_KEYS__: ReadonlyArray<{ publicKey: string; notAfter: number }>;

if (__DEBUG_BUILD__) {
  import('@apps-in-toss/debugger-client').then((m) =>
    m.startDebugConsole({ relayPublicKeys: __AIT_RELAY_KEYS__ }),
  );
}
```

`__AIT_RELAY_KEYS__`는 번들러 `define`이 디버그 빌드에서만 채운다.
`define: { __AIT_RELAY_KEYS__: JSON.stringify(debugBuild ? await readRelayPublicKeys(process.cwd()) : []) }`
처럼 `@apps-in-toss/debugger/relay-keys`의 `readRelayPublicKeys`를 쓴다. 이 함수는 키 에이전트(메모리 전용)에서
공개키와 만료 시각만 받아 오고, 디스크에 비밀을 만들지 않는다. 키는 기본 24시간 유효하므로 만료되면 디버그 번들을
다시 빌드해 업로드한다. 공개키는 커밋하지 않아도 된다. QR 테스트 호스트에서는 이 키로 attach URL의 서명을
확인하므로 키가 없으면 연결되지 않는다(`blocked-relay-key`).

`__DEBUG_BUILD__`는 번들러 `define`이 환경 변수 `AIT_DEBUG_BUILD`에서 읽어 정한다. 기본(release)
빌드는 `false`로 접혀 번들러가 패키지 그래프를 통째로 지우므로 배포 번들에 attach 코드가
남지 않는다. `AIT_DEBUG_BUILD=1`을 명시한 디버그 빌드만 `true`가 되고, 설정 파일에
`'true'`를 고정으로 쓰지 않는다. 릴리즈 빌드는 `npm run build`, 디버그 빌드는
`AIT_DEBUG_BUILD=1 npm run build`다. 디버그 빌드는 검수·출시에 올리지 않는다. 번들러는 `package.json`과
설정 파일에서 읽고, 하나로 좁혀지지 않으면 추측하지 않고 사용자에게 묻는다.
런타임 self-gate만 있는 `/auto` import는 코드가 번들에 남으므로 삽입하지 않는다.
프로젝트에 이미 `/auto` import가 있으면 사용자에게 알린 뒤 게이트 import로 바꾼다.

프로젝트에 0.3.0 이하의 옛 이름 `@apps-in-toss/debug-console`이 있으면 "이미 설치됨"으로 끝내지
않는다. 이름이 `@apps-in-toss/debugger-client`로 바뀌었고 debugger와 함께 0.4.0 이상이어야 연결되므로,
`setup-debugger/references/upgrade-check.md`의 마이그레이션 경로(0절·2-B절)로 안내한다.

이 패키지는 예전 `@apps-in-toss/devtools`의 `./in-app` export였다 — devtools의 MCP
데몬·on-device attach 표면이 `debugger` 패키지(`@apps-in-toss/debugger` +
`@apps-in-toss/debugger-client`)로 분리되면서 나뉘었다.

핵심 절차: (1) `package.json` 확인 → (2) 기존 설치·와이어업 확인(idempotency, 게이트 없는
`/auto` 발견 포함) → (3) 번들러 감지 → (4) `devDependencies`로 설치 → (5) 진입점 감지 +
게이트 import 삽입 → (6) 번들러 `define` 추가 → (7) 빌드 두 번으로 검증(기본 빌드에서 마커
0건, 마지막 빌드는 릴리즈 빌드로 남김) → (8) 완료 seam. 하지 말아야 할 것은 —

**상세가 필요하면 Read `<이 skill의 base directory>/references/debugger-client.md`.**

## tossface facet — `/ait:inject-tossface`

이모지를 토스페이스 글리프로 렌더한다. `design` skill의 서체 정책상 본문 서체(`Toss
Product Sans` 계열)는 금지지만, 이모지 서체 `Tossface`(`toss/tossface`로 공개 배포)는
금지 대상이 아니라 **권장 대상**이다 — 시스템마다 모양이 갈리는 이모지 대신 어디서나
같은 글리프로 렌더된다. 먼저 기존 배선 여부를 grep으로 확인해(idempotency) 이미 있으면
skip한다. 콘솔 인증 불필요 — 로컬 작업이다.

**두 모드 중 하나를 사용자 확인 후 진행한다** — **모드 A(CDN 링크)**는 번들 증가
0이고 토스 앱 webview에서 CDN 로드가 확인됐지만(2026-10-14, iOS·Android) 네트워크에 의존하고, **모드 B(subset 번들 포함)**는
네트워크 없이 결정적으로 동작하지만 담는 subset마다 약 520KB~1.9MB가 늘고 라이선스가
요구하는 저작권 고지·전문 동봉이 따른다.

핵심 절차: (0) 기존 배선 확인(idempotency) → (1) 두 모드 대가 계산 + 모드 확정 →
(2) 모드 A는 `@import`/`<link>` 삽입, 모드 B는 코드포인트 대조 → subset 선정(+ 선정
직후 재확정) → 원본 파일 배치 → 라이선스 동봉 → CSS 작성 → (3) `font-family` 맨
앞에 `Tossface` 추가 → (4) 완료 seam. `@import` 위치 제약(다른 규칙보다 항상 앞에
와야 한다)·정확한 CDN 스니펫·라이선스 근거는 —

**상세가 필요하면 Read `<이 skill의 base directory>/references/tossface.md`.**

## 다음 단계 (facet별 seam)

세 facet 모두 seam을 **슬래시 + 자연어 2표면**으로 인쇄한다(통일 규칙 —
로컬 `docs/design/skill-conventions.md`(repo 미포함 — maintainer-local) §9).

**devtools facet** 완료 후:

```
@apps-in-toss/devtools 설정 완료 · <config-file> 패치

다음 단계 (명령을 몰라도 됩니다 — 따옴표 안 문장을 그대로 말해도 같은 단계로 갑니다):
  npm run dev               # 브라우저에서 앱 실행 (프로젝트의 dev 스크립트, 하단에 AIT DevTools 패널)
                            #   말로: "브라우저에서 개발 서버 띄워줘"
  /ait:debug                # 브라우저 패널·window.__ait 상태로 디버깅
                            #   말로: "브라우저에서 앱 상태가 이상한데 디버깅해줘"
```

**debugger-client facet** 완료 후:

```
@apps-in-toss/debugger-client 설정 완료 · <진입점>에 __DEBUG_BUILD__ 게이트 import, <설정 파일>에 define 추가

다음 단계 (명령을 몰라도 됩니다 — 따옴표 안 문장을 그대로 말해도 같은 단계로 갑니다):
  AIT_DEBUG_BUILD=1 npm run build  # 디버그 빌드에만 attach 표면 포함 (기본 빌드에는 없음, 검수·출시에 올리지 않음)
                                   #   (2.x 폴백은 AIT_DEBUG_BUILD=1 npm run bundle:ait)
  /ait:debug                          # 환경 3 QR attach로 on-device 디버깅
                                      #   말로: "미니앱이 폰에서 이상하게 동작하는데 라이브 상태를 디버깅하고 싶어"
```

**tossface facet** 완료 후:

```
Tossface 배선 완료 · <모드 A: CDN 링크 추가 | 모드 B: subset <N>개 번들, +<증가량>>

다음 단계 (명령을 몰라도 됩니다 — 따옴표 안 문장을 그대로 말해도 같은 단계로 갑니다):
  npm run dev               # 브라우저에서 이모지 렌더 확인
                            #   말로: "브라우저에서 개발 서버 띄워줘"
  /ait:design                # 화면 렌더 무결성(G7 등) 판정으로 이어서 확인
                            #   말로: "화면 디자인 품질 점검해줘"
```

각 facet의 완전한 완료 블록(변경 요약·주의사항 포함)은 세 facet 모두 위 references
파일에 있다.

## Out of scope (이 skill이 하지 않는 것)

- ❌ 새 프로젝트 생성 (greenfield) — `/ait:new` (`new-miniapp` skill).
- ❌ 콘솔 인증·등록·업로드 — console MCP 도구(`miniapp_create`/`bundle_upload`/
  `bundle_upload_complete`)의 역할.
- ❌ 번들 설정(`apps-in-toss.config.ts`) 최초 생성 — 정본 경로(create-ait-app)는
  `/ait:new`에 기본 포함, `--local` 폴백만 `new-miniapp`의 L-5 절차로 추가.
- ❌ (devtools) 브라우저에서 panel이 실제로 뜨는지의 E2E 검증 — 사용자가 직접 `npm run dev`로 확인. (dev 서버·빌드가 에러 없이 도는지까지만 이 skill이 확인한다.)
- ❌ (devtools) 라이브러리 빌드에 mock 주입 — 앱(미니앱) 전용.
- ❌ (devtools) README에 없는 번들러에 추측으로 배선 — 사용자에게 알리고 묻는다.
- ❌ **실행 중인 앱을 진단하는 것** — 이 skill은 패키지를 *설치*할 뿐이다. "폰에서 이상하게 동작한다", "라이브 상태를 보고 싶다"는 `/ait:debug`(`debug` skill). debugger-client facet은 그 진단을 *가능하게 하는 준비물*이지 진단 자체가 아니다.
- ❌ (debugger-client) MCP 데몬 등록 — `/ait:setup-debugger`가 프로젝트 `.mcp.json`에 배선(`/ait:debug` §5 참조).
- ❌ (debugger-client) 게이트 없는 `import '@apps-in-toss/debugger-client/auto'` 삽입 — 배포 번들에 코드가 남는다.
- ❌ (debugger-client) 번들러가 불확실한 채로 `define`을 추측해 쓰는 것 — 사용자에게 묻는다.
- ❌ (tossface) 재-subsetting·포맷 변환 — 원본 파일을 그대로만 배치한다
  (`references/tossface.md`의 "tossface facet 하지 말아야 할 것" 절 참조).
- ❌ (tossface) 본문 서체로 사용 — 이모지 서체다. 본문 서체 금지는 `design` skill의
  "토스 브랜드·UI 모방 금지" 절이 다루는 별개 축이다.

## 참고

- **create-ait-app 프로젝트에 IAP/IAA 예제 추가**: 이 skill의 두 facet과는
  무관한 별도 CLI 서브커맨드지만, 같은 brownfield 자리라 여기 남긴다 —
  `npx -y create-ait-app@latest add-sample [directory] --inline --sample iap,iaa`
  (`directory` 생략 시 기본값은 cwd `.`). 대상이 Apps in Toss 프로젝트로
  인식될 때만 동작하고(`inspectSampleProject()` — `@apps-in-toss/web-framework`
  의존성 또는 `apps-in-toss.config.ts` 존재로 판정, 아니면 즉시 거부),
  `--sample`을 생략하면 interactive checkbox 프롬프트로 빠진다. 이 skill은 이
  명령을 실행하지 않는다 — `new-miniapp` skill의 Step 6 완료 안내가 같은 명령을
  노출한다.
- 표준 dev 환경 셋업(브라우저 mock·실기기 미리보기) 등 주제별 가이드는 docs MCP
  (`searchDocumentation`/`getPage`)로 조회한다.
- devtools facet 상세: `<이 skill의 base directory>/references/devtools.md`
- debugger-client facet 상세: `<이 skill의 base directory>/references/debugger-client.md`
- tossface facet 상세: `<이 skill의 base directory>/references/tossface.md`
- 짝 skill: `new-miniapp` (새 프로젝트 생성 — create-ait-app 호출 + devtools 후처리 배선), `debug` (devtools facet이 깔아둔 브라우저 panel 또는 debugger-client facet이 깔아둔 환경 3 attach 표면을 소비하는 디버깅), `design` (tossface facet 배선 후 화면 렌더 무결성 판정 — "토스 브랜드·UI 모방 금지" 절이 이모지 서체 정책의 정본).
- `@apps-in-toss/devtools`(mock+panel+unplugin, 브라우저 dev 전용) 소스 — 구 repo 이력에만 존재(재생성으로 링크 소멸, maintainer 로컬 백업 mirror에서 열람 가능)
- `@apps-in-toss/debugger-client`(on-device attach): https://github.com/toss/apps-in-toss-harness/tree/main/packages/debugger-client
- `@apps-in-toss/debugger`(MCP 데몬, `/ait:setup-debugger`가 프로젝트 `.mcp.json`에 배선): https://github.com/toss/apps-in-toss-harness/tree/main/packages/debugger
- `Tossface`(공개 배포 이모지 서체): https://github.com/toss/tossface (`LICENSE` 전문, 공개 안내 페이지 `https://toss.im/tossface/copyright`).

