feat: add Graplix agent skill (#28)

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: tonyfromundefined

.changeset/bright-carrots-wash.md

@@ -0,0 +1,6 @@
+---
+"@graplix/codegen": patch
+"@graplix/engine": patch
+---
+
+docs: add skills

.github/workflows/deploy-packages.yml

@@ -27,6 +27,8 @@ jobs:
 
       - run: yarn build
 
+      - run: yarn build:docs
+
       - name: Create Release Pull Request or Publish to npm
         id: changesets
         uses: changesets/action@v1

.tech-specs/2026-04-16-0001-agent-skill.md

@@ -0,0 +1,165 @@
+# Agent Skill for Graplix
+
+**참고 PR:** daangn/ventyd#85, #87, #89, #91
+
+---
+
+## 목표
+
+에이전트(Claude Code, Cursor 등)가 Graplix를 올바르게 사용할 수 있도록 [Agent Skills Specification](https://agentskills.io) 형식의 `skill/` 디렉터리를 추가한다.
+
+`npx skills add daangn/graplix` 명령 하나로 설치 가능하게 한다.
+
+---
+
+## 배경
+
+ventyd 프로젝트(daangn/ventyd#85~91)에서 동일한 패턴을 먼저 구현했다. Graplix도 같은 방식을 따른다.
+
+핵심 아이디어는 두 가지다:
+1. **`skill/`** — 리포지토리에 체크인되는 에이전트 지식 베이스. SKILL.md + references/.
+2. **embedded docs** — npm 패키지(`@graplix/engine`)에 `dist/docs/*.md`로 번들링된 문서. 에이전트가 설치된 버전에 정확히 매칭되는 문서를 `node_modules`에서 직접 읽을 수 있다.
+
+ventyd와 다른 점: Graplix는 별도 문서 사이트가 없으므로, `generate-docs.ts`는 docs 사이트 빌드 결과 대신 각 패키지의 `README.md`를 소스로 사용한다.
+
+---
+
+## 작업 범위
+
+### 1. `skill/` 디렉터리 (PR #85 상당)
+
+루트에 생성. `@graplix/engine` 기준으로 작성한다.
+
+```
+skill/
+  SKILL.md                        # 핵심 지식: 스키마 문법, buildEngine, check/explain, resolver, resolveType
+  README.md                       # 설치 안내 (npx skills add daangn/graplix)
+  references/
+    quick-start.md                # 설치부터 첫 번째 권한 체크까지
+    schema-syntax.md              # .graplix 스키마 문법 레퍼런스 (type, relations, define, direct/from/or)
+    embedded-docs.md              # node_modules/@graplix/engine/dist/docs/ 읽는 방법
+    common-errors.md              # 자주 발생하는 에러와 해결책
+```
+
+**ventyd의 `remote-docs.md`에 해당하는 파일을 만들지 않는다.** Graplix는 공개 문서 사이트가 없으므로, 대신 `schema-syntax.md`로 스키마 문법을 다룬다.
+
+#### `SKILL.md` 주요 내용
+
+- frontmatter: `name: graplix`, description, license, metadata
+- "Do not trust internal knowledge" 경고 (embedded docs 우선 참조)
+- Available Files Reference 표
+- 핵심 개념: ReBAC, schema 문법, `buildEngine` 옵션, `check`/`explain`, `Resolver` 인터페이스, `resolveType`, `ResolverInfo`
+- 완전한 예제 (User + Repository 시나리오)
+- Critical Rules: resolveType 필수, context 필수, relation resolver는 도메인 엔티티 반환, EntityRef 직접 사용 금지
+
+#### `skill/references/schema-syntax.md` 주요 내용
+
+- `.graplix` 파일 전체 문법 (Langium 기반)
+- `type`, `relations`, `define` 키워드
+- Term 종류: direct(`[TypeA, TypeB]`), from(`relation from source`), or(`term or term`)
+- 네이밍 규칙: `snake_case`
+- 완전한 예제 스키마
+
+### 2. `scripts/generate-docs.ts` (PR #85 상당)
+
+`@graplix/engine` 패키지의 `dist/docs/`에 번들링될 Markdown 파일을 생성하는 스크립트.
+
+**소스**: docs 사이트가 없으므로, 각 패키지의 `README.md`를 복사한다.
+
+```
+packages/engine/README.md   → dist/docs/engine.md
+packages/language/README.md → dist/docs/language.md  
+packages/codegen/README.md  → dist/docs/codegen.md
+```
+
+추가로, `packages/language/src/graplix.langium`의 문법 정의를 읽어 `dist/docs/schema-syntax.md`로 생성한다 (실제 문법 소스 기반).
+
+구현 요점:
+- `dist/docs/` 없으면 생성
+- 소스 파일이 없으면 `console.warn`하고 skip (exit code 0 유지) — PR #89 교훈
+
+### 3. `packages/engine/package.json` 업데이트 (PR #85, #87 상당)
+
+```json
+{
+  "files": ["dist"],        // dist/docs/ 자동 포함됨 (변경 불필요)
+  "scripts": {
+    "build": "tsdown",
+    "build:docs": "tsx ../../scripts/generate-docs.ts",
+    "prepack": "yarn build:docs",
+    "test": "vitest --run --passWithNoTests"
+  }
+}
+```
+
+`prepack`은 `npm publish` / `yarn npm publish` 직전에 자동 실행된다.
+`build:docs`는 수동으로도 실행 가능하다.
+
+루트 `package.json`에도 편의 스크립트 추가:
+
+```json
+{
+  "scripts": {
+    "build:docs": "yarn workspace @graplix/engine build:docs"
+  }
+}
+```
+
+### 4. `devDependencies` 추가
+
+`scripts/generate-docs.ts` 실행에 필요:
+
+- `tsx` — 루트 devDependencies에 추가
+
+### 5. CI 워크플로우 업데이트 (PR #91 상당)
+
+`.github/workflows/deploy-packages.yml`의 `yarn build`와 publish 사이에 `yarn build:docs` 스텝 추가:
+
+```yaml
+- run: yarn build
+
+- run: yarn build:docs   # ← 추가
+
+- name: Create Release Pull Request or Publish to npm
+  ...
+```
+
+---
+
+## 결정 사항
+
+| 항목 | 결정 | 근거 |
+|------|------|------|
+| embedded docs 소스 | 각 패키지 README.md | 문서 사이트 없음, README가 가장 권위 있는 소스 |
+| `remote-docs.md` | 만들지 않음 | 공개 URL 없음 |
+| `schema-syntax.md` 추가 | ventyd에 없는 파일 | ReBAC 스키마 문법은 Graplix 고유 개념이라 별도 레퍼런스 필요 |
+| 스크립트 위치 | 루트 `scripts/` | 모노레포 패턴, 루트 devDep(tsx) 활용 |
+| embedded docs 위치 | `@graplix/engine`만 | 에이전트가 가장 많이 사용하는 패키지, 단일 진입점 |
+| prepack 실패 처리 | warn + skip (exit 0) | PR #89 패턴: CI 릴리즈 실패 방지 |
+
+---
+
+## 파일 변경 목록
+
+| 파일 | 변경 |
+|------|------|
+| `skill/SKILL.md` | 신규 |
+| `skill/README.md` | 신규 |
+| `skill/references/quick-start.md` | 신규 |
+| `skill/references/schema-syntax.md` | 신규 |
+| `skill/references/embedded-docs.md` | 신규 |
+| `skill/references/common-errors.md` | 신규 |
+| `scripts/generate-docs.ts` | 신규 |
+| `packages/engine/package.json` | `build:docs`, `prepack` 스크립트 추가 |
+| `package.json` | `build:docs` 스크립트, `tsx` devDep 추가 |
+| `.github/workflows/deploy-packages.yml` | `yarn build:docs` 스텝 추가 |
+
+---
+
+## 검증 계획
+
+1. `yarn build:docs` 실행 → `packages/engine/dist/docs/*.md` 생성 확인
+2. `packages/engine/dist/docs/` 파일에 README 내용이 올바르게 복사됐는지 확인
+3. `skill/SKILL.md` frontmatter가 Agent Skills Specification을 통과하는지 확인
+4. `yarn workspace @graplix/engine pack --dry-run`으로 `dist/docs/` 포함 확인
+5. `scripts/generate-docs.ts`를 소스 없이 실행 → warn 출력 후 exit 0 확인

package.json

@@ -12,6 +12,7 @@
   ],
   "scripts": {
     "build": "ultra -r build",
+    "build:docs": "yarn workspace @graplix/engine build:docs",
     "changeset:publish": "changeset publish",
     "changeset:version": "changeset version && yarn install --mode update-lockfile",
     "format": "biome check --fix --unsafe",
@@ -21,6 +22,7 @@
     "@biomejs/biome": "^2.3.15",
     "@changesets/cli": "^2.29.8",
     "@types/node": "24.10.13",
+    "tsx": "^4.19.4",
     "typescript": "^5.9.3",
     "ultra-runner": "^3.10.5"
   },

packages/engine/package.json

@@ -34,6 +34,8 @@
   ],
   "scripts": {
     "build": "tsdown",
+    "build:docs": "tsx ../../scripts/generate-docs.ts",
+    "prepack": "yarn build:docs",
     "test": "vitest --run --passWithNoTests"
   },
   "dependencies": {

scripts/generate-docs.ts

@@ -0,0 +1,59 @@
+import { copyFile, mkdir, readdir } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(SCRIPT_DIR, "..");
+const PACKAGES_DIR = resolve(REPO_ROOT, "packages");
+const DOCS_OUT = resolve(PACKAGES_DIR, "engine/dist/docs");
+
+const SOURCES: Array<{ src: string; dest: string }> = [
+  {
+    src: resolve(PACKAGES_DIR, "engine/README.md"),
+    dest: resolve(DOCS_OUT, "engine.md"),
+  },
+  {
+    src: resolve(PACKAGES_DIR, "language/README.md"),
+    dest: resolve(DOCS_OUT, "language.md"),
+  },
+  {
+    src: resolve(PACKAGES_DIR, "codegen/README.md"),
+    dest: resolve(DOCS_OUT, "codegen.md"),
+  },
+];
+
+async function main() {
+  let distExists = true;
+  try {
+    await readdir(resolve(PACKAGES_DIR, "engine/dist"));
+  } catch {
+    distExists = false;
+  }
+
+  if (!distExists) {
+    console.warn(
+      "Skipping docs generation: packages/engine/dist/ not found. Run `yarn workspace @graplix/engine build` first.",
+    );
+    return;
+  }
+
+  await mkdir(DOCS_OUT, { recursive: true });
+
+  let count = 0;
+  for (const { src, dest } of SOURCES) {
+    try {
+      await copyFile(src, dest);
+      console.log(`  ${src.replace(REPO_ROOT + "/", "")} → ${dest.replace(REPO_ROOT + "/", "")}`);
+      count++;
+    } catch {
+      console.warn(`  Skipping ${src.replace(REPO_ROOT + "/", "")} — not found`);
+    }
+  }
+
+  console.log(`\nGenerated ${count} docs in packages/engine/dist/docs/`);
+}
+
+main().catch((error) => {
+  console.error("Failed to generate docs:", error);
+  process.exit(1);
+});

skill/README.md

@@ -0,0 +1,48 @@
+# Graplix Skill
+
+Agent skill for the [Graplix](https://github.com/daangn/graplix) TypeScript ReBAC (Relation-Based Access Control) toolkit.
+
+Graplix Skills are folders of instructions and resources that coding agents can discover and use to gain Graplix knowledge. They contain setup instructions, best practices, and methods for retrieving current documentation.
+
+## Installation
+
+Install using any coding agent that supports the [Skills standard](https://agentskills.io):
+
+```bash
+npx skills add daangn/graplix
+```
+
+```bash
+pnpm dlx skills add daangn/graplix
+```
+
+```bash
+yarn dlx skills add daangn/graplix
+```
+
+```bash
+bun x skills add daangn/graplix
+```
+
+## Compatibility
+
+Works with any coding agent that supports the Skills standard, including:
+
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
+- [Cursor](https://cursor.com)
+- [Codex](https://openai.com/codex)
+- [OpenCode](https://opencode.ai)
+
+Also available on [GitHub](https://github.com/daangn/graplix).
+
+## What's Included
+
+- **SKILL.md** - Core Graplix knowledge: schema syntax, buildEngine, resolvers, resolveType, check/explain, and critical rules
+- **references/quick-start.md** - Installation and first permission check guide
+- **references/schema-syntax.md** - `.graplix` schema language reference
+- **references/embedded-docs.md** - How to find API documentation in installed packages
+- **references/common-errors.md** - Troubleshooting guide for frequent errors
+
+## License
+
+MIT