698 ／ 707
퍼블리스 라이터 스킬: AI 에이전트의 책 자동 집필
AI 에이전트가 책 한 권을 처음부터 끝까지 집필하고 발행하는 상상을 해본 적이 있는가. 퍼블리스 라이터 스킬은 이러한 비전을 현실로 만든다. 이 스킬은 클로드 코드 에이전트가 퍼블리스 편집기의 웹 도구를 활용하여 브라우저에서 직접 책을 쓰고 발행하게 한다.
개요
퍼블리스 라이터는 웹 기반 출판 플랫폼 퍼블리스(Puvles, puvles.lopapps.com)를 이용하는 클로드 코드 에이전트를 위한 특별한 기능 모음이다. 이 스킬은 에이전트가 브라우저에 열린 퍼블리스 편집기의 WebMCP 도구를 호출하여 책 집필 과정을 전적으로 처리한다. 에이전트는 데이터베이스에 직접 접근하지 않는다. 사용자가 로그인한 크롬 탭 안에서 퍼블리스 앱의 기능을 작동한다.
에이전트가 수행하는 작업은 다양하다. 새로운 프로젝트를 만들고, 파트와 챕터를 생성하며, 마크다운을 블록 단위로 변환한다. 또한 글자 수 통계를 기록하고, 블록 생성 애니메이션을 제어하며, 화면을 이동하는 등 앱의 모든 인터페이스 작업을 직접 수행한다.
두 가지 책 집필 방식
퍼블리스 라이터 스킬은 사용자의 목적에 따라 두 가지 방식으로 책을 집필한다. 에이전트는 스킬 호출 시 사용자에게 방식을 선택하도록 묻지만, 요청에 방식이 이미 명시되어 있으면 바로 작업을 진행한다.
| 방식 | 흐름 | 적합한 경우 |
|---|---|---|
| 웹에 바로 작성 | 챕터를 하나씩 초안으로 작성하고, 열린 편집기에 즉시 내용을 기록한다. | 시연, 녹화, 짧은 분량의 책 |
| 로컬에 작성 후 배포 | book.json 파일과 챕터별 마크다운 파일을 로컬 환경에 먼저 작성한다. 이후 publish 명령 한 번으로 프로젝트 생성부터 발행 완료까지 모든 과정을 처리한다. |
긴 분량의 책, 원고 사본을 코드 저장소에 보관하려는 경우 |
publish 명령은 새 프로젝트를 생성한 뒤 해당 프로젝트 ID를 book.json 파일에 자동으로 기록한다. 따라서 같은 명령을 다시 실행해도 기존 프로젝트 내에서 제목이나 코드가 동일한 파트와 챕터를 찾아 본문 내용만 갱신한다.
시스템 요구 사항
퍼블리스 라이터 스킬을 사용하려면 특정 환경이 필요하다. 아래는 이 스킬을 원활하게 작동시키는 데 필요한 주요 구성 요소이다.
- 클로드 코드 환경
- Node.js 22 이상: 내장된
fetch및WebSocket기능을 사용한다. - 원격 디버깅 포트가 열린 크롬 브라우저:
--remote-debugging-port=9222와 같은 옵션을 사용한다. - 퍼블리스 로그인 탭: 사용자가 직접 퍼블리스에 로그인해야 한다. 스킬은 사용자 비밀번호를 다루지 않는다.
- WebMCP 도구 등록 버전의 퍼블리스 앱: 크롬에 WebMCP 플래그가 없어도 앱 자체에서 폴리필을 제공하므로 스킬이 정상 작동한다.
빠른 시작 및 주요 명령
퍼블리스 라이터 스킬은 깃허브에서 클론하여 설치한다. 클로드 코드를 다시 열면 /puvles-writer로 호출할 수 있다. 로컬 개발 서버를 사용할 때는 PUVLES_HOME 및 CDP_PORT 환경 변수를 설정해야 한다.
이 스킬은 다양한 명령을 제공한다. 다음은 주요 기능과 그 실행 방식의 예시이다.
- 상태 확인:
node $S status명령으로 로그인 상태, 현재 페이지, 열린 프로젝트를 확인한다. - 프로젝트 생성:
node $S create-project "새 책 제목"명령으로 빈 프로젝트를 만들고 편집기를 연다. - 콘텐츠 작성:
create-part,create-chapter,write-chapter명령으로 책의 구조를 만들고 본문을 작성한다. - 로컬 우선 발행:
node $S init-book ./my-book --title "새 책 제목"으로book.json과chapters/폴더를 생성한다. 작성된 로컬 파일을node $S publish ./my-book --complete명령으로 퍼블리스에 발행한다.--dry-run옵션으로 발행 계획을 먼저 확인할 수 있다.
이 외에도 프로젝트 내 이미지 블록을 관리하거나(예: set-image, generate-image), 책의 판형이나 AI 지시문 같은 설정을 변경하고(예: settings), 등록된 도구를 확인하고 직접 호출하는(예: tools, call) 명령이 있다.
콘텐츠 구조와 마크다운 규칙
퍼블리스 라이터 스킬로 책을 집필할 때 로컬 파일을 사용한다면 book.json 형식에 따라 책의 메타데이터와 구조를 정의해야 한다.
book.json은 책의 제목, 설명, 판형(신국판, 46배판, B5, A5, A4 중 하나), 프로젝트 ID, 그리고 파트와 챕터 목록을 포함한다. 각 챕터 파일은 마크다운 형식이며, 문서 상단에 question과 summary를 프런트매터로 포함해야 한다. 챕터의 제목과 코드는 book.json 매니페스트에 정의한다.
마크다운 규칙: 퍼블리스 파서는 다음과 같은 마크다운 구조를 특정 블록으로 인식한다.
| 마크다운 | 퍼블리스 블록 유형 | 설명 |
|---|---|---|
---question: "핵심 질문"summary: "챕터 요약"--- |
챕터 프런트매터 | 챕터의 핵심 질문과 요약으로, 상단 보라색/회색 박스에 표시된다. |
## 절 제목 |
H2 블록 | 주요 절 제목으로 사용된다. |
### 소제목 |
H3 블록 | 절 안의 소제목으로 사용된다. |
본문 문단. **굵게**는... |
텍스트 블록 | 일반 본문 문단이다. 스크립트가 굵게 표시된 텍스트를 <b> 태그로 변환한다. |
> **조금 더 쉽게**: 초보자용 보충 설명 |
인용 박스 (초록색) | 초보자를 위한 보충 설명을 담는다. |
> **Basic Study**: 개념 정리 |
인용 박스 (분홍색) | 특정 개념을 정리하는 데 사용된다. |
| 코드 펜스(백틱 3개) | 코드 블록 | 코드 스니펫을 포함한다. |
\| 항목 \| 값 \|\|---\|---\| |
표 블록 | 구분선(\| --- \| --- \|)이 필요하며, 셀 병합은 불가하다. |
[이미지 플레이스홀더: 캡션] |
이미지 블록 (캡션만) | 캡션만 있는 이미지 자리표시자를 생성한다. |
구조 줄 사이에 있는 문단들은 하나의 텍스트 블록으로 합쳐지며, 스크립트가 문단 사이를 <br/><br/>로 연결한다. --split-paragraphs 옵션으로 이 기능을 끌 수 있다. 목록은 일반 텍스트 줄로 저장된다.
동작 원리 및 주의 사항
퍼블리스 라이터 스킬의 핵심 작동 방식은 크롬 개발자 도구 프로토콜(CDP)을 활용한다. 스크립트는 이 프로토콜로 크롬 탭에 접속하고, 페이지 내부에서 document.modelContext.getTools()를 통해 퍼블리스 앱이 등록한 WebMCP 도구 객체를 찾는다. 이후 executeTool(tool, args) 함수를 호출하여 필요한 작업을 수행한다. 페이지 이동이 발생하면, 해당 페이지의 훅이 마운트되고 도구가 등록될 때까지 대기한 뒤 작업을 진행한다.
이 스킬을 사용할 때 몇 가지 주의할 점이 있다.
- 삭제 도구: 삭제 관련 도구는 되돌릴 수 없는 영구 삭제를 수행한다. 에이전트가 임의로 사용하지 않도록
SKILL.md문서에 명시한다. - 원격 디버깅 포트: 원격 디버깅 포트가 열린 크롬은 같은 컴퓨터의 다른 프로그램에 의해 제어될 수 있다. 작업 완료 후에는 이 포트를 닫는 것이 안전하다.
- 제한된 기능: 모든 퍼블리스 기능이 도구로 제공되는 것은 아니다. 프로젝트 삭제, 멤버 관리, 편집기의 AI 글쓰기 버튼, 그리고 표의 셀 병합, 셀 이미지 삽입, 열 너비 조정, 표 캡션 등 세부적인 표 편집 기능은 이 스킬로 제어할 수 없다.
기존 책 수정 및 세부 제어
퍼블리스 라이터 스킬은 새로운 책을 집필하는 것 외에 기존 책의 내용을 세밀하게 수정하는 기능도 제공한다.
- 챕터/파트 정보 수정:
update-chapter명령으로 챕터의 제목, 코드, 질문, 요약, 완료 여부, 소속 파트, 순서를 수정한다.update-part명령은 파트의 제목, 도입글, 코드, 순서를 변경한다. - 선택적 발행:
publish <dir> --only 02-03,03-01명령을 사용하면 지정한 챕터(코드, 파일명, 제목 일부로 식별)의 내용만 선택적으로 갱신할 수 있다. - 블록 단위 편집:
blocks <chapterId>명령으로 챕터 내 블록 목록을 확인한다.insert-blocks,update-block,replace-blocks,delete-blocks명령으로 특정 위치에 블록을 삽입하거나, 기존 블록을 수정, 교체, 삭제하는 등 세밀한 본문 편집이 가능하다.
출처
- puvles-writer-skill (lifeofpi-ux) — https://github.com/lifeofpi-ux/puvles-writer-skill