waynesutton/builder-skills

Builder skills for Convex apps. Convex patterns plus a PRD, task.md, changelog, and files.md workflow for Claude Code, Codex, Cursor, and OpenCode.

개요

builder-skills는 AI 코딩 어시스턴트(Claude, Codex, Cursor, OpenCode 등)가 서버리스 백엔드 플랫폼인 Convex에서 애플리케이션을 구축할 때 모범 사례 관례를 따르도록 돕는 에이전트 기술(agent skills) 모음입니다. 이 저장소에는 17개의 작고 독립적인 "SKILL.md" 파일이 포함되어 있으며, 각 파일은 의사결정 가이드, 예제, 체크리스트 및 참조 자료로 구성되어 있어 LLM이 필요할 때 로드할 수 있습니다. 이 기술들은 Convex 관련 사항(유효성 검사기, 인덱스, 마이그레이션, 보안 검사)과 일반적인 프로젝트 관리 습관(PRD 작성, 작업/변경 로그/파일 문서 유지, 파괴적인 git 명령으로부터 보호)을 다룹니다.

이 패키지는 범용 skills.sh 설치 프로그램, Claude Code 플러그인 또는 npm을 통해 직접 설치할 수 있습니다. 설치 후, 일련의 스타터 Markdown 파일(AGENTS.md, task.md, changelog.md 등)이 사용자 저장소에 추가되어 에이전트가 작업을 추적하고 문서를 코드와 동기화할 수 있는 구조화된 작업 공간을 제공합니다.

주요 기능

기능	역할	중요성
17개의 즉시 사용 가능한 기술	각 기술은 설명, 사용 트리거, 예제 코드 및 선택적 참조 파일이 포함된 `SKILL.md` (300줄 이하)입니다.	LLM 에이전트에게 구체적이고 검증된 지침을 제공하여 Convex 관례를 위반하거나 저장소를 손상시키지 않도록 합니다.
Convex 중심 기술	유효성 검사기, 인덱스, 멱등성 변형(idempotent mutations), HTTP 작업, 마이그레이션, 보안 검사 등.	생성된 코드를 Convex의 모범 사례에 맞게 유지하고 런타임 버그를 방지합니다.
프로젝트 워크플로우 기술	`project-workflow`, `project-docs`, `git-safety`, `avoid-feature-creep`.	엄격한 개발 루프를 강제합니다: PRD → 작업 추적 → 자동 문서 업데이트 → 안전한 git 사용.
멀티 에이전트 설치	Claude, Codex, Cursor, 범용 에이전트 또는 npm CLI를 통한 모든 사용자 지정 폴더를 지원합니다.	팀이 기술을 다시 작성할 필요 없이 선호하는 LLM 어시스턴트를 사용할 수 있게 합니다.
템플릿 부트스트랩	`install-templates`는 스타터 Markdown 파일(`AGENTS.md`, `task.md`, `changelog.md`, `files.md`, `prds/lessons.md`)을 배치합니다.	에이전트가 세션 중에 읽고 쓸 수 있는 즉시 사용 가능한 "지식 베이스"를 제공합니다.
프로그래밍 방식 API	npm 패키지에서 내보낸 `listSkills`, `getSkillMeta`, `getSkill`.	도구나 사용자 지정 스크립트가 기술의 원시 Markdown을 쿼리하거나 로드할 수 있게 합니다.
안전 가드레일	`git-safety`는 명시적으로 승인되지 않는 한 파괴적인 git 명령을 차단합니다.	LLM이 위험한 명령을 실행하려고 할 때 실수로 작업이 손실되는 것을 방지합니다.

일반적인 사용 흐름

기술 세트를 설치합니다 (예: npx skills add waynesutton/builder-skills).
npx @waynesutton/builder-skills install-templates를 실행합니다. 이제 저장소에 5개의 문서 파일과 편집 가능한 기술 스텁이 포함됩니다.
에이전트에게 변경을 요청합니다. 에이전트는 먼저 prds/에 PRD를 생성하고, task.md에 작업 항목을 추가한 다음, 적절한 Convex 기술(예: convex-functions)을 사용하여 코드를 생성합니다.
변경이 완료되면 project-docs 기술을 실행합니다. 이 기술은 git log와 작업 트리를 읽고 changelog.md, files.md, task.md를 자동으로 업데이트하며 보안 정보를 스캔합니다.
기술이 출력한 커밋 메시지를 사용하여 변경 사항을 커밋합니다.

이 루프를 반복하여 코드, 문서, 프로젝트 추적을 동기화 상태로 유지하면서 일반적인 함정으로부터 보호합니다.

설치 옵션

방법	작동 방식	사용 시기
skills.sh (`npx skills add …`)	대화형 설치 프로그램이 저장소에 일반 파일을 작성합니다. 이후 `npx skills update`로 업데이트합니다.	편집 가능한 파일과 에이전트에 구애받지 않는 간단한 설정을 선호하는 경우 권장됩니다.
Claude Code 플러그인 (`claude plugins …`)	Claude 마켓플레이스에 기술을 등록합니다. Claude가 자동으로 업데이트를 관리합니다.	주로 Claude Code를 사용하며 업데이트를 자동화하고 싶은 경우.
npm CLI (`npx @waynesutton/builder-skills install-all …`)	기술 파일을 대상 폴더(`.claude/skills`, `.codex/skills` 등)에 복사하거나 심볼릭 링크합니다.	사용자 지정 에이전트를 사용하거나 특정 디렉토리에 기술이 필요한 경우.

권장 대상

Convex 백엔드를 구축하는 개발자로, Convex의 API 계약을 존중하는 AI 지원을 원하는 분.
LLM 코딩 어시스턴트(Claude, Codex, Cursor, OpenCode)를 사용하며 공유 가능하고 강제 가능한 규칙 세트가 필요한 팀.
프로젝트 관리자로, 자동화된 PRD/작업 추적 및 문서 동기화를 원하는 분.
오픈 소스 기여자로, 우발적인 git 데이터 손실을 방지하는 재현 가능한 워크플로우를 찾는 분.

제한 사항 / 미해결 질문

기술은 작성자의 워크플로우에 편향되어 있으므로 팀의 관례에 맞게 조정이 필요할 수 있습니다.
호스트 LLM이 SKILL.md 파일을 읽을 수 있어야 합니다. 이 형식을 지원하지 않는 에이전트는 래퍼가 필요합니다.
테스트나 CI 통합은 내장되어 있지 않습니다. 기술은 코드를 생성하지만 자체 테스트 스위트가 필요합니다.

빠른 시작 (CLI)

# 패키지를 전역 또는 프로젝트 내에 설치
npm i -D @waynesutton/builder-skills

# Claude(기본값)용 모든 기술을 설치하고 스타터 템플릿 배치
npx @waynesutton/builder-skills install-all
npx @waynesutton/builder-skills install-templates

이제 Markdown 스캐폴딩과 LLM 어시스턴트용 기술 파일이 준비되었습니다.

라이선스

Apache-2.0 – 상업적 및 비상업적 용도로 무료 사용 가능.