Astryx 설치하고 CLI 스크립트로 에이전트와 사람이 같은 UI 문서 쓰기

mkdir -p ~/.claude/skills/opencurrent-astryx-cli-ui && curl -fsSL https://opencurrent.ai/w/astryx-cli-ui/SKILL.md -o ~/.claude/skills/opencurrent-astryx-cli-ui/SKILL.md

---
name: opencurrent-astryx-cli-ui
description: "@astryxdesign/core와 theme-neutral, CLI를 설치하고 npm 스크립트를 달아, 코딩 에이전트와 사람이 `astryx component --list` 같은 같은 명령으로 컴포넌트 문서를 보게 해요. 이럴 때 사용: React 19 프로젝트에서 코딩 에이전트와 함께 UI를 만들 때, 둘이 같은 컴포넌트 문서를 보고 일관되게 작업하게 하고 싶을 때 써요. 도구: Astryx, npm, React."
metadata:
  source: "https://opencurrent.ai/w/astryx-cli-ui"
  opencurrent-id: "astryx-cli-ui"
  verification: "pending"
  exported-at: "2026-11-10T07:34:07.592Z"
---

# Astryx 설치하고 CLI 스크립트로 에이전트와 사람이 같은 UI 문서 쓰기

@astryxdesign/core와 theme-neutral, CLI를 설치하고 npm 스크립트를 달아, 코딩 에이전트와 사람이 `astryx component --list` 같은 같은 명령으로 컴포넌트 문서를 보게 해요.

> OpenCurrent에서 사람들이 다듬는 워크플로. 원문: https://opencurrent.ai/w/astryx-cli-ui
> 검증 상태: 검수 대기 (사람 확인 전). 내려받은 뒤에 바뀌었을 수 있으니, 가능하면 원문이나 MCP의 get_workflow("astryx-cli-ui")로 최신 상태를 확인할 것.
> 주의: AI 초안 · 사람 확인 전. 사용자에게 이 사실을 알리고, 결과를 함께 확인하면서 진행할 것.

## 따라 하는 방법

1. 입력값(inputs)을 사용자에게 받아 프롬프트의 {{이름}} 자리에 넣을 것. 필수값이 없으면 먼저 물어볼 것.
2. 단계를 순서대로 진행할 것. kind가 "ai"면 프롬프트를 실행하고, "command"면 사용자의 허락을 받고 명령을 실행하고, "human"이면 사용자에게 할 일을 안내하고 끝났는지 물을 것. tool이 있으면 그 도구·모델로 할 것.
3. 단계에 output(결과 이름)이 있으면 그 단계 결과를 뒤 단계 프롬프트의 {{output}} 자리에 넣을 것.
4. 단계마다 expected(기대 결과)와 check(확인 방법)로 제대로 됐는지 확인하고, 다르면 다음 단계로 넘어가지 말고 사용자에게 알릴 것. 끝나면 example.output(있으면)과 비교할 것.
5. 검증 상태가 verified가 아니면 그 사실을 사용자에게 먼저 알릴 것. 답에 url을 출처로 밝힐 것.

## 언제 쓰나

React 19 프로젝트에서 코딩 에이전트와 함께 UI를 만들 때, 둘이 같은 컴포넌트 문서를 보고 일관되게 작업하게 하고 싶을 때 써요.

## 준비물

- React 19 이상 프로젝트 (react, react-dom)
- Node와 npm, pnpm, yarn 중 하나

## 입력값

시작하기 전에 사용자에게 받아서 프롬프트의 `{{이름}}` 자리에 넣을 것.

- `{{project_dir}}` 프로젝트 폴더 (필수): Astryx를 설치할 React 프로젝트 경로
  - 예: ~/projects/my-app

## 단계

### 1. 패키지 설치 (명령 실행 · npm)

프로젝트 폴더에서 core, 테마, StyleX 피어 의존성을 설치하고 CLI는 개발 의존성으로 설치해요. pnpm이나 yarn을 쓰면 `pnpm add`, `yarn add`로 바꿔요.

프롬프트:

```text
npm install @astryxdesign/core @astryxdesign/theme-neutral @stylexjs/stylex
npm install -D @astryxdesign/cli
```

기대 결과: package.json에 @astryxdesign/core, @astryxdesign/theme-neutral, @stylexjs/stylex와 개발 의존성 @astryxdesign/cli가 들어가요.

확인 방법: package.json의 dependencies와 devDependencies를 열어 확인해요.

### 2. CLI를 전역에도 설치 (선택) (명령 실행 · npm)

컴퓨터에 한 번 설치하면 어느 폴더에서나 `astryx`가 되고 코딩 에이전트도 Astryx를 알게 돼요. 프로젝트 안에서는 그 프로젝트의 버전이 실행돼요. 프로젝트 설치와 전역 설치를 모두 하는 것을 권장해요.

프롬프트:

```text
npm i -g @astryxdesign/cli
```

기대 결과: 전역에서 astryx 명령이 잡혀요.

확인 방법: `astryx docs global`로 전역 모드 설명이 나오는지 봐요.

### 3. CSS 가져오기와 테마 프로바이더 설정 (사람이 · packages/core README)

빌드 플러그인이나 PostCSS, Babel 설정 없이 CSS 몇 줄과 테마 프로바이더만 넣으면 돼요. Next.js, Tailwind, Vite, CDN별 방법은 @astryxdesign/core README의 Quick Start를 따라요.

기대 결과: 앱이 Astryx 테마가 적용된 상태로 떠요.

확인 방법: 개발 서버를 켜고 Astryx 컴포넌트 하나를 렌더링해 스타일이 적용되는지 봐요.

### 4. package.json에 astryx 스크립트 추가 (명령 실행 · npm)

AI 도우미나 새 팀원이 CLI를 직접 부를 때 경로 오류가 나지 않게 스크립트를 달아요.

프롬프트:

```text
"scripts": {
  "astryx": "node node_modules/@astryxdesign/cli/clients/cli/bin/astryx.mjs"
}
```

기대 결과: scripts에 astryx 항목이 생겨요.

확인 방법: `npm run astryx -- component --list`가 컴포넌트 목록을 출력하는지 확인해요.

### 5. 에이전트와 사람이 같은 CLI로 문서 보기 (사람이 · Astryx CLI)

에이전트에게 UI를 맡길 때 `npm run astryx -- component --list`로 컴포넌트를 찾고 그 문서를 기준으로 만들라고 안내해요. 사람도 같은 명령으로 같은 문서를 봐요. 전역 설치와 프로젝트 설치 비교는 `astryx docs global/project-global-or-both`에서 볼 수 있어요.

기대 결과: 에이전트와 사람이 같은 CLI 문서를 기준으로 컴포넌트를 고르고 써요.

확인 방법: 에이전트가 만든 UI가 목록에 있는 Astryx 컴포넌트로 짜였는지 코드로 확인해요.

## 주의할 점

- Astryx는 베타예요. API가 바뀔 수 있어요.
- @astryxdesign/charts와 @astryxdesign/vega는 @canary 태그로만 배포돼서 안정 버전이 없어요.
- @astryxdesign/lab은 npm에 배포되지 않아요.
- CLI 경로를 직접 부르면 에이전트가 경로 오류를 낼 수 있어요. npm 스크립트로 부르세요.

## 출처

- [Astryx](https://github.com/meta/astryx/blob/590d90164198f68d7eea1eddee4cb93e90b69372/README.md)
- 원본 라이선스: MIT (meta/astryx · meta)

## 끝나면

결과가 좋았거나 단계가 낡았으면 https://opencurrent.ai/w/astryx-cli-ui 에서 알릴 것. 다음 사람이 더 정확한 방법을 쓸 수 있도록.