@waynesutton/convex-skills 1.0.7 → 1.0.9

package/AGENTS.md

@@ -40,7 +40,6 @@ This repository provides two complementary approaches for AI coding agents:
 | Skill                                                                    | Description                                           |
 | ------------------------------------------------------------------------ | ----------------------------------------------------- |
 | [convex-best-practices](skills/convex-best-practices/SKILL.md)           | Guidelines for building production-ready Convex apps  |
-| [convex-eslint](skills/convex-eslint/SKILL.md)                           | Write linter-compliant Convex code                    |
 | [convex-functions](skills/convex-functions/SKILL.md)                     | Writing queries, mutations, actions, and HTTP actions |
 | [convex-realtime](skills/convex-realtime/SKILL.md)                       | Patterns for building reactive applications           |
 | [convex-schema-validator](skills/convex-schema-validator/SKILL.md)       | Database schema definition and validation             |

package/README.md

@@ -1,4 +1,11 @@
-# Convex (unofficial) Skills v1
+# For official Convex Skills use Convex Agent Plugins
+
+Official Convex plugins for AI coding agents, providing development tools for building reactive backends with TypeScript.
+
+https://github.com/get-convex/convex-agent-plugins
+
+
+## Convex (unofficial) Skills 
 
 [![npm version](https://img.shields.io/npm/v/@waynesutton/convex-skills.svg)](https://www.npmjs.com/package/@waynesutton/convex-skills)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
@@ -16,7 +23,7 @@ All skills are designed to produce code that passes @convex-dev/eslint-plugin by
 - **Skills** prevent mistakes at generation time
 - **ESLint** catches anything that slips through at build time
 
-See the [convex-eslint](/skills/convex-eslint/SKILL.md) skill for setup instructions.
+See the Code Quality section in [convex-best-practices](/skills/convex-best-practices/SKILL.md) for setup instructions.
 
 ## Installation
 
@@ -35,6 +42,12 @@ convex-skills install convex-best-practices
 # Install all skills
 convex-skills install-all
 
+# Install all skills to .agents/skills
+convex-skills install-all --target agents
+
+# Symlink SKILL.md files instead of copying
+convex-skills install-all --target agents --link
+
 # Install templates (CLAUDE.md + skill templates)
 convex-skills install-templates
 ```
@@ -84,6 +97,15 @@ Codex will auto-discover `SKILL.md` files in that directory on the next start.
 
 If you are working from a repo clone, Codex also auto-discovers skills from `.codex/skills` at the repo root. You can symlink this repo’s `skills/*` into `.codex/skills` so updates flow through without copying.
 
+### Standard Agent Skills Path
+
+Some tools are standardizing on `.agents/skills` for discovery. This repo supports that layout via the CLI:
+
+```bash
+convex-skills install-all --target agents
+convex-skills install-all --target agents --link
+```
+
 ### OpenCode
 
 OpenCode discovers skills from `~/.claude/skills/<name>/SKILL.md` automatically. See OpenCode Skills docs for more details.
@@ -113,7 +135,6 @@ Copy the desired skill's `SKILL.md` file to your project's `.claude/skills/` dir
 | Skill                                                                    | Description                                           |
 | ------------------------------------------------------------------------ | ----------------------------------------------------- |
 | [convex-best-practices](skills/convex-best-practices/SKILL.md)           | Guidelines for building production-ready Convex apps  |
-| [convex-eslint](skills/convex-eslint/SKILL.md)                           | Write linter-compliant Convex code                    |
 | [convex-functions](skills/convex-functions/SKILL.md)                     | Writing queries, mutations, actions, and HTTP actions |
 | [convex-realtime](skills/convex-realtime/SKILL.md)                       | Patterns for building reactive applications           |
 | [convex-schema-validator](skills/convex-schema-validator/SKILL.md)       | Database schema definition and validation             |
@@ -133,8 +154,6 @@ convex-skills/
 ├── skills/                   # Core Convex skills for AI agents
 │   ├── convex-best-practices/
 │   │   └── SKILL.md
-│   ├── convex-eslint/
-│   │   └── SKILL.md
 │   ├── convex-functions/
 │   │   └── SKILL.md
 │   ├── convex-cron-jobs/
@@ -142,6 +161,7 @@ convex-skills/
 │   └── ...
 ├── .codex/                   # Codex integration (symlink skills here)
 │   └── README.md             # Codex setup instructions
+├── .agents/                  # Standard agent skills path
 ├── command/                  # Slash command definitions (OpenCode)
 │   └── convex.md             # /convex command entrypoint
 ├── templates/                # Templates for forking developers

package/bin/cli.js

@@ -9,6 +9,7 @@ import {
   existsSync,
   copyFileSync,
   readdirSync,
+  symlinkSync,
 } from "fs";
 
 const __filename = fileURLToPath(import.meta.url);
@@ -18,7 +19,6 @@ const packageRoot = join(__dirname, "..");
 const SKILLS = {
   "convex-best-practices":
     "Guidelines for building production-ready Convex apps",
-  "convex-eslint": "Write linter-compliant Convex code",
   "convex-functions": "Writing queries, mutations, actions, and HTTP actions",
   "convex-realtime": "Patterns for building reactive applications",
   "convex-schema-validator": "Database schema definition and validation",
@@ -32,6 +32,12 @@ const SKILLS = {
   "convex-component-authoring": "Creating reusable Convex components",
 };
 
+const TARGET_ALIASES = new Map([
+  ["claude", ".claude/skills"],
+  ["codex", ".codex/skills"],
+  ["agents", ".agents/skills"],
+]);
+
 function printHelp() {
   console.log(`
 convex-skills - Agent skills for building Convex applications
@@ -49,12 +55,17 @@ COMMANDS:
 
 OPTIONS:
   --dir <path>            Target directory (default: current directory)
+  --target <name|path>     Install target: claude, codex, agents, or a path
+  --link                  Symlink SKILL.md instead of copying
   --help, -h              Show this help message
 
 EXAMPLES:
   convex-skills list
   convex-skills install convex-best-practices
   convex-skills install-all
+  convex-skills install-all --target agents
+  convex-skills install convex-functions --target .agents/skills
+  convex-skills install convex-best-practices --target codex --link
   convex-skills install-templates
   convex-skills show convex-functions
 
@@ -73,7 +84,27 @@ function listSkills() {
   console.log("");
 }
 
-function installSkill(skillName, targetDir) {
+function ensureDir(dirPath) {
+  if (!existsSync(dirPath)) {
+    mkdirSync(dirPath, { recursive: true });
+  }
+}
+
+function resolveTargetSkillsDir(targetDir, target) {
+  if (!target) {
+    return join(targetDir, ".claude", "skills");
+  }
+
+  const alias = TARGET_ALIASES.get(target);
+  if (alias) {
+    return join(targetDir, alias);
+  }
+
+  const resolved = resolve(targetDir, target);
+  return resolved.endsWith("skills") ? resolved : join(resolved, "skills");
+}
+
+function installSkill(skillName, targetSkillsDir, useSymlink) {
   const skillsPath = join(packageRoot, "skills", skillName, "SKILL.md");
 
   if (!existsSync(skillsPath)) {
@@ -82,24 +113,24 @@ function installSkill(skillName, targetDir) {
     process.exit(1);
   }
 
-  const targetPath = join(
-    targetDir,
-    ".claude",
-    "skills",
-    skillName,
-    "SKILL.md",
-  );
+  const targetPath = join(targetSkillsDir, skillName, "SKILL.md");
   const targetSkillDir = dirname(targetPath);
 
-  if (!existsSync(targetSkillDir)) {
-    mkdirSync(targetSkillDir, { recursive: true });
+  ensureDir(targetSkillDir);
+
+  if (useSymlink) {
+    if (!existsSync(targetPath)) {
+      symlinkSync(skillsPath, targetPath);
+    }
+    console.log(`Linked ${skillName} to ${targetPath}`);
+    return;
   }
 
   copyFileSync(skillsPath, targetPath);
   console.log(`Installed ${skillName} to ${targetPath}`);
 }
 
-function installAllSkills(targetDir) {
+function installAllSkills(targetSkillsDir, useSymlink) {
   const skillsDir = join(packageRoot, "skills");
   const skills = readdirSync(skillsDir, { withFileTypes: true })
     .filter((dirent) => dirent.isDirectory())
@@ -108,11 +139,11 @@ function installAllSkills(targetDir) {
   console.log(`Installing ${skills.length} skills...\n`);
 
   skills.forEach((skillName) => {
-    installSkill(skillName, targetDir);
+    installSkill(skillName, targetSkillsDir, useSymlink);
   });
 
   console.log(
-    `\nDone! Installed ${skills.length} skills to ${join(targetDir, ".claude", "skills")}`,
+    `\nDone! Installed ${skills.length} skills to ${targetSkillsDir}`,
   );
 }
 
@@ -139,9 +170,7 @@ function installTemplates(targetDir) {
     );
     const targetSkillsDir = join(targetDir, ".claude", "skills");
 
-    if (!existsSync(targetSkillsDir)) {
-      mkdirSync(targetSkillsDir, { recursive: true });
-    }
+    ensureDir(targetSkillsDir);
 
     templates.forEach((template) => {
       const src = join(skillTemplatesDir, template);
@@ -184,6 +213,8 @@ function printSkillPath(skillName) {
 // Parse arguments
 const args = process.argv.slice(2);
 let targetDir = process.cwd();
+let target = null;
+let useSymlink = false;
 
 // Check for --dir flag
 const dirIndex = args.indexOf("--dir");
@@ -192,8 +223,21 @@ if (dirIndex !== -1 && args[dirIndex + 1]) {
   args.splice(dirIndex, 2);
 }
 
+const targetIndex = args.indexOf("--target");
+if (targetIndex !== -1 && args[targetIndex + 1]) {
+  target = args[targetIndex + 1];
+  args.splice(targetIndex, 2);
+}
+
+const linkIndex = args.indexOf("--link");
+if (linkIndex !== -1) {
+  useSymlink = true;
+  args.splice(linkIndex, 1);
+}
+
 const command = args[0];
 const arg = args[1];
+const targetSkillsDir = resolveTargetSkillsDir(targetDir, target);
 
 switch (command) {
   case "list":
@@ -205,10 +249,10 @@ switch (command) {
       console.log("Run 'convex-skills list' to see available skills.");
       process.exit(1);
     }
-    installSkill(arg, targetDir);
+    installSkill(arg, targetSkillsDir, useSymlink);
     break;
   case "install-all":
-    installAllSkills(targetDir);
+    installAllSkills(targetSkillsDir, useSymlink);
     break;
   case "install-templates":
     installTemplates(targetDir);

package/index.js

@@ -54,7 +54,6 @@ export function getSkillPath(skillName) {
 export const SKILLS = {
   "convex-best-practices":
     "Guidelines for building production-ready Convex apps",
-  "convex-eslint": "Write linter-compliant Convex code",
   "convex-functions": "Writing queries, mutations, actions, and HTTP actions",
   "convex-realtime": "Patterns for building reactive applications",
   "convex-schema-validator": "Database schema definition and validation",

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@waynesutton/convex-skills",
-  "version": "1.0.7",
-  "description": "Agent skills for building production-ready Convex applications. Includes best practices, functions, realtime patterns, schema validation, file storage, security audits, and more.",
-  "author": "Wayne Sutton",
+  "version": "1.0.9",
+  "description": "For official Convex Skills use Convex Agent Plugins at https://github.com/get-convex/convex-agent-plugins. This package provides unofficial agent skills for building production-ready Convex applications.",
+  "author": "Wayne Sutton - @waynesutton",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",

package/skills/convex-best-practices/SKILL.md

@@ -9,14 +9,32 @@ Build production-ready Convex applications by following established patterns for
 
 ## Code Quality
 
-All patterns in this skill comply with @convex-dev/eslint-plugin rules.
-Install the linter for build-time validation:
+All patterns in this skill comply with `@convex-dev/eslint-plugin`. Install it for build-time validation:
 
 ```bash
 npm i @convex-dev/eslint-plugin --save-dev
 ```
 
-See [convex-eslint](../convex-eslint/SKILL.md) for configuration details.
+```js
+// eslint.config.js
+import { defineConfig } from "eslint/config";
+import convexPlugin from "@convex-dev/eslint-plugin";
+
+export default defineConfig([
+  ...convexPlugin.configs.recommended,
+]);
+```
+
+The plugin enforces four rules:
+
+| Rule                                | What it enforces                  |
+| ----------------------------------- | --------------------------------- |
+| `no-old-registered-function-syntax` | Object syntax with `handler`      |
+| `require-argument-validators`       | `args: {}` on all functions       |
+| `explicit-table-ids`                | Table name in db operations       |
+| `import-wrong-runtime`              | No Node imports in Convex runtime |
+
+Docs: https://docs.convex.dev/eslint
 
 ## Documentation Sources
 

package/skills/convex-functions/SKILL.md

@@ -19,7 +19,7 @@ All examples in this skill comply with @convex-dev/eslint-plugin rules:
 - Argument validators on all functions
 - Explicit table names in database operations
 
-See [convex-eslint](../convex-eslint/SKILL.md) for linting setup.
+See the Code Quality section in [convex-best-practices](../convex-best-practices/SKILL.md) for linting setup.
 
 ## Documentation Sources
 

package/skills/convex-eslint/SKILL.md

@@ -1,145 +0,0 @@
----
-name: convex-eslint
-description: Write Convex code that passes @convex-dev/eslint-plugin rules by default
-version: 1.0.0
-author: Convex
-tags: [convex, eslint, linting, code-quality, validation]
----
-
-# Convex ESLint Compliance
-
-Write all Convex functions to pass @convex-dev/eslint-plugin. These rules prevent common bugs, security issues, and ensure code quality.
-
-## Documentation Sources
-
-- https://docs.convex.dev/eslint
-- https://www.npmjs.com/package/@convex-dev/eslint-plugin
-
-## Setup
-
-Install the plugin:
-
-```bash
-npm i @convex-dev/eslint-plugin --save-dev
-```
-
-Configure `eslint.config.js`:
-
-```javascript
-import { defineConfig } from "eslint/config";
-import convexPlugin from "@convex-dev/eslint-plugin";
-
-export default defineConfig([...convexPlugin.configs.recommended]);
-```
-
-## Rules
-
-### 1. no-old-registered-function-syntax
-
-Always use object syntax with a `handler` property.
-
-```typescript
-// Correct
-export const list = query({
-  args: {},
-  handler: async (ctx) => {
-    return await ctx.db.query("messages").collect();
-  },
-});
-
-// Wrong - bare function syntax
-export const list = query(async (ctx) => {
-  return await ctx.db.query("messages").collect();
-});
-```
-
-### 2. require-argument-validators
-
-Always include `args` object, even when empty.
-
-```typescript
-// Correct - with arguments
-export const get = query({
-  args: { id: v.id("messages") },
-  handler: async (ctx, { id }) => {
-    return await ctx.db.get("messages", id);
-  },
-});
-
-// Correct - no arguments
-export const listAll = query({
-  args: {},
-  handler: async (ctx) => {
-    return await ctx.db.query("messages").collect();
-  },
-});
-
-// Wrong - missing args
-export const get = query({
-  handler: async (ctx, { id }: { id: Id<"messages"> }) => {
-    return await ctx.db.get("messages", id);
-  },
-});
-```
-
-### 3. explicit-table-ids
-
-Use explicit table names in all database operations (Convex 1.31.0+).
-
-```typescript
-// Correct
-const message = await ctx.db.get("messages", messageId);
-await ctx.db.patch("messages", messageId, { text: "updated" });
-await ctx.db.replace("messages", messageId, {
-  text: "replaced",
-  author: "Alice",
-});
-await ctx.db.delete("messages", messageId);
-
-// Wrong - implicit table from ID type
-const message = await ctx.db.get(messageId);
-await ctx.db.patch(messageId, { text: "updated" });
-await ctx.db.replace(messageId, { text: "replaced", author: "Alice" });
-await ctx.db.delete(messageId);
-```
-
-Migration codemod available:
-
-```bash
-npx @convex-dev/codemod@latest explicit-ids
-```
-
-### 4. import-wrong-runtime
-
-Never import Node.js runtime files into Convex runtime files.
-
-```typescript
-// convex/queries.ts (no "use node" directive)
-
-// Correct - importing from Convex runtime file
-import { helper } from "./utils"; // utils.ts has no "use node"
-
-// Wrong - importing from Node runtime file
-import { nodeHelper } from "./nodeUtils"; // nodeUtils.ts has "use node"
-```
-
-## Best Practices
-
-1. Run ESLint before committing: `npx eslint convex/`
-2. Use auto-fix for quick migrations: `npx eslint convex/ --fix`
-3. Add to CI pipeline to catch violations early
-4. Configure your editor for real-time feedback
-
-## Quick Reference
-
-| Rule                                | What it enforces                  |
-| ----------------------------------- | --------------------------------- |
-| `no-old-registered-function-syntax` | Object syntax with `handler`      |
-| `require-argument-validators`       | `args: {}` on all functions       |
-| `explicit-table-ids`                | Table name in db operations       |
-| `import-wrong-runtime`              | No Node imports in Convex runtime |
-
-## References
-
-- [ESLint Plugin Docs](https://docs.convex.dev/eslint)
-- [Explicit IDs Announcement](https://news.convex.dev/db-table-name/)