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上でアプリケーションを構築する際に、ベストプラクティスの慣習に従うことを支援するエージェントスキルのコレクションです。このリポジトリには、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に特化したスキル	バリデーター、インデックス、冪等なミューテーション、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 – 商用・非商用問わず無料で使用可能。