mirror of
https://github.com/waynesutton/convexskills.git
synced 2026-09-14 16:28:42 +08:00
fix(skills): name field must match folder name for /skill commands
This commit is contained in:
Wayne Sutton
+31
-11
@@ -2,14 +2,22 @@
|
||||
|
||||
import { fileURLToPath } from "url";
|
||||
import { dirname, join, resolve } from "path";
|
||||
import { readFileSync, writeFileSync, mkdirSync, existsSync, copyFileSync, readdirSync } from "fs";
|
||||
import {
|
||||
readFileSync,
|
||||
writeFileSync,
|
||||
mkdirSync,
|
||||
existsSync,
|
||||
copyFileSync,
|
||||
readdirSync,
|
||||
} from "fs";
|
||||
|
||||
const __filename = fileURLToPath(import.meta.url);
|
||||
const __dirname = dirname(__filename);
|
||||
const packageRoot = join(__dirname, "..");
|
||||
|
||||
const SKILLS = {
|
||||
"convex-best-practices": "Guidelines for building production-ready Convex apps",
|
||||
"convex-best-practices":
|
||||
"Guidelines for building production-ready Convex apps",
|
||||
"convex-functions": "Writing queries, mutations, actions, and HTTP actions",
|
||||
"convex-realtime": "Patterns for building reactive applications",
|
||||
"convex-schema-validator": "Database schema definition and validation",
|
||||
@@ -50,7 +58,9 @@ EXAMPLES:
|
||||
convex-skills show convex-functions
|
||||
|
||||
AVAILABLE SKILLS:
|
||||
${Object.entries(SKILLS).map(([name, desc]) => ` ${name.padEnd(30)} ${desc}`).join("\n")}
|
||||
${Object.entries(SKILLS)
|
||||
.map(([name, desc]) => ` ${name.padEnd(30)} ${desc}`)
|
||||
.join("\n")}
|
||||
`);
|
||||
}
|
||||
|
||||
@@ -64,14 +74,20 @@ function listSkills() {
|
||||
|
||||
function installSkill(skillName, targetDir) {
|
||||
const skillsPath = join(packageRoot, "skills", skillName, "SKILL.md");
|
||||
|
||||
|
||||
if (!existsSync(skillsPath)) {
|
||||
console.error(`Error: Skill not found: ${skillName}`);
|
||||
console.log("Run 'convex-skills list' to see available skills.");
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
const targetPath = join(targetDir, ".claude", "skills", skillName, "SKILL.md");
|
||||
const targetPath = join(
|
||||
targetDir,
|
||||
".claude",
|
||||
"skills",
|
||||
skillName,
|
||||
"SKILL.md",
|
||||
);
|
||||
const targetSkillDir = dirname(targetPath);
|
||||
|
||||
if (!existsSync(targetSkillDir)) {
|
||||
@@ -94,12 +110,14 @@ function installAllSkills(targetDir) {
|
||||
installSkill(skillName, targetDir);
|
||||
});
|
||||
|
||||
console.log(`\nDone! Installed ${skills.length} skills to ${join(targetDir, ".claude", "skills")}`);
|
||||
console.log(
|
||||
`\nDone! Installed ${skills.length} skills to ${join(targetDir, ".claude", "skills")}`,
|
||||
);
|
||||
}
|
||||
|
||||
function installTemplates(targetDir) {
|
||||
const templatesDir = join(packageRoot, "templates");
|
||||
|
||||
|
||||
// Install CLAUDE.md template
|
||||
const claudeTemplate = join(templatesDir, "CLAUDE.md");
|
||||
if (existsSync(claudeTemplate)) {
|
||||
@@ -115,9 +133,11 @@ function installTemplates(targetDir) {
|
||||
// Install skill templates
|
||||
const skillTemplatesDir = join(templatesDir, "skills");
|
||||
if (existsSync(skillTemplatesDir)) {
|
||||
const templates = readdirSync(skillTemplatesDir).filter((f) => f.endsWith(".md"));
|
||||
const templates = readdirSync(skillTemplatesDir).filter((f) =>
|
||||
f.endsWith(".md"),
|
||||
);
|
||||
const targetSkillsDir = join(targetDir, ".claude", "skills");
|
||||
|
||||
|
||||
if (!existsSync(targetSkillsDir)) {
|
||||
mkdirSync(targetSkillsDir, { recursive: true });
|
||||
}
|
||||
@@ -139,7 +159,7 @@ function installTemplates(targetDir) {
|
||||
|
||||
function showSkill(skillName) {
|
||||
const skillsPath = join(packageRoot, "skills", skillName, "SKILL.md");
|
||||
|
||||
|
||||
if (!existsSync(skillsPath)) {
|
||||
console.error(`Error: Skill not found: ${skillName}`);
|
||||
process.exit(1);
|
||||
@@ -151,7 +171,7 @@ function showSkill(skillName) {
|
||||
|
||||
function printSkillPath(skillName) {
|
||||
const skillsPath = join(packageRoot, "skills", skillName, "SKILL.md");
|
||||
|
||||
|
||||
if (!existsSync(skillsPath)) {
|
||||
console.error(`Error: Skill not found: ${skillName}`);
|
||||
process.exit(1);
|
||||
|
||||
@@ -17,11 +17,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
||||
- `files.md`: Codebase structure reference
|
||||
- `task.md`: Completed task tracking
|
||||
- `docs.md`: Documentation index
|
||||
- `skills/convex/SKILL.md`: Umbrella skill indexing all Convex skills
|
||||
|
||||
### Changed
|
||||
|
||||
- Updated `README.md` with templates section and repository structure
|
||||
|
||||
### Fixed
|
||||
|
||||
- Skill `name` field now matches folder name for `/skill` commands to work
|
||||
- Changed from human readable (e.g., `Convex Best Practices`) to kebab-case (e.g., `convex-best-practices`)
|
||||
- Added `displayName` field for human readable names
|
||||
- Affects all 12 Convex skill files
|
||||
|
||||
## [1.0.0] - 2026-01-14
|
||||
|
||||
### Added
|
||||
|
||||
@@ -0,0 +1,380 @@
|
||||
# Convex Skills: Build and Maintenance Guide
|
||||
|
||||
A practical guide for building, publishing, and maintaining AI agent skills packages.
|
||||
|
||||
## How This Package Was Built
|
||||
|
||||
### Architecture Overview
|
||||
|
||||
The package follows a simple, modular structure that works across multiple AI coding agents (Claude Code, Codex, OpenCode, Cursor, Gemini).
|
||||
|
||||
```
|
||||
convex-skills/
|
||||
├── skills/ # Core skills (SKILL.md files)
|
||||
├── templates/ # Starter templates for forks
|
||||
├── command/ # Slash commands (OpenCode)
|
||||
├── bin/cli.js # CLI for npm installs
|
||||
├── index.js # Programmatic API
|
||||
├── package.json # npm configuration
|
||||
├── AGENTS.md # Agent-facing docs
|
||||
├── CLAUDE.md # Claude-specific context
|
||||
└── GEMINI.md # Gemini-specific context
|
||||
```
|
||||
|
||||
### Key Design Decisions
|
||||
|
||||
**1. One skill per folder**
|
||||
|
||||
Each skill lives in `skills/<skill-name>/SKILL.md`. This pattern:
|
||||
|
||||
- Makes discovery straightforward for AI agents
|
||||
- Enables selective installation
|
||||
- Follows the Agent Skills spec from Anthropic
|
||||
|
||||
**2. Frontmatter metadata**
|
||||
|
||||
Every `SKILL.md` starts with YAML frontmatter:
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: convex-best-practices
|
||||
description: Guidelines for building production-ready Convex apps
|
||||
version: 1.0.0
|
||||
author: Convex
|
||||
tags: [convex, best-practices, typescript]
|
||||
---
|
||||
```
|
||||
|
||||
**3. Multi-agent support files**
|
||||
|
||||
Different AI tools read different files:
|
||||
|
||||
- `AGENTS.md` and `CLAUDE.md` for Claude Code
|
||||
- `GEMINI.md` for Gemini CLI
|
||||
- `.cursor/rules/` for Cursor IDE
|
||||
|
||||
**4. Dual distribution**
|
||||
|
||||
The package supports both:
|
||||
|
||||
- **npm install**: CLI and programmatic access
|
||||
- **git clone**: Direct file access and forking
|
||||
|
||||
### Publishing to npm
|
||||
|
||||
**Initial setup:**
|
||||
|
||||
```bash
|
||||
# Login to npm (once)
|
||||
npm login
|
||||
|
||||
# Verify package.json has correct scope
|
||||
# name: "@waynesutton/convex-skills"
|
||||
```
|
||||
|
||||
**Publish workflow:**
|
||||
|
||||
```bash
|
||||
# Bump version in package.json
|
||||
npm version patch # or minor/major
|
||||
|
||||
# Publish
|
||||
npm publish --access public
|
||||
|
||||
# Verify
|
||||
npm info @waynesutton/convex-skills
|
||||
```
|
||||
|
||||
**package.json essentials:**
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "@waynesutton/convex-skills",
|
||||
"version": "1.0.3",
|
||||
"type": "module",
|
||||
"main": "index.js",
|
||||
"bin": {
|
||||
"convex-skills": "./bin/cli.js"
|
||||
},
|
||||
"files": [
|
||||
"skills/**/*.md",
|
||||
"templates/**/*.md",
|
||||
"AGENTS.md",
|
||||
"CLAUDE.md",
|
||||
"GEMINI.md",
|
||||
"index.js",
|
||||
"bin/"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
The `files` array controls what gets published. Use `.npmignore` for additional exclusions.
|
||||
|
||||
---
|
||||
|
||||
## Maintenance Checklist
|
||||
|
||||
### Weekly
|
||||
|
||||
- [ ] Check Convex docs for API changes
|
||||
- [ ] Review GitHub issues
|
||||
- [ ] Update skills if Convex releases new features
|
||||
|
||||
### Monthly
|
||||
|
||||
- [ ] Audit all doc links in skills (broken link check)
|
||||
- [ ] Review npm download stats
|
||||
- [ ] Check for new AI agent platforms to support
|
||||
|
||||
### Per Release
|
||||
|
||||
- [ ] Update `changelog.md` with changes
|
||||
- [ ] Bump version following semver
|
||||
- [ ] Test CLI commands locally
|
||||
- [ ] Test `npm pack` before publishing
|
||||
- [ ] Tag release in git
|
||||
|
||||
---
|
||||
|
||||
## Updating Skills
|
||||
|
||||
### Adding a New Skill
|
||||
|
||||
1. Create folder: `skills/<skill-name>/`
|
||||
|
||||
2. Create `SKILL.md` with required structure:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: skill-name
|
||||
description: What this skill does
|
||||
version: 1.0.0
|
||||
author: Convex
|
||||
tags: [convex, relevant-tags]
|
||||
---
|
||||
|
||||
# Skill Name
|
||||
|
||||
## Documentation Sources
|
||||
|
||||
[Links to official docs]
|
||||
|
||||
## Instructions
|
||||
|
||||
[Step-by-step guidance]
|
||||
|
||||
## Examples
|
||||
|
||||
[Working code examples]
|
||||
|
||||
## Best Practices
|
||||
|
||||
[Rules to follow]
|
||||
|
||||
## References
|
||||
|
||||
[Additional resources]
|
||||
```
|
||||
|
||||
3. Add to `index.js` SKILLS object:
|
||||
|
||||
```javascript
|
||||
export const SKILLS = {
|
||||
// ... existing
|
||||
"new-skill-name": "Description",
|
||||
};
|
||||
```
|
||||
|
||||
4. Add to `bin/cli.js` SKILLS object (same format)
|
||||
|
||||
5. Update `files.md` with new skill entry
|
||||
|
||||
6. Update `changelog.md`
|
||||
|
||||
7. Bump version and publish
|
||||
|
||||
### Updating Existing Skills
|
||||
|
||||
1. Edit the `SKILL.md` file
|
||||
2. Update version in frontmatter if significant change
|
||||
3. Document in `changelog.md`
|
||||
4. Bump package version (patch for fixes, minor for features)
|
||||
|
||||
---
|
||||
|
||||
## Version Strategy
|
||||
|
||||
Follow [Semantic Versioning](https://semver.org/):
|
||||
|
||||
| Change Type | Version Bump | Example |
|
||||
| ------------------------------ | ------------ | ------------- |
|
||||
| Typo fixes, doc clarifications | patch | 1.0.3 → 1.0.4 |
|
||||
| New skill added | minor | 1.0.4 → 1.1.0 |
|
||||
| Breaking structure change | major | 1.1.0 → 2.0.0 |
|
||||
|
||||
---
|
||||
|
||||
## Testing Before Publish
|
||||
|
||||
```bash
|
||||
# Test CLI locally
|
||||
node bin/cli.js list
|
||||
node bin/cli.js show convex-best-practices
|
||||
|
||||
# Test npm pack (see what will be published)
|
||||
npm pack --dry-run
|
||||
|
||||
# Create local tarball for testing
|
||||
npm pack
|
||||
npm install ./waynesutton-convex-skills-1.0.3.tgz -g
|
||||
|
||||
# Test install commands
|
||||
convex-skills list
|
||||
convex-skills install convex-best-practices --dir /tmp/test-project
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Future Updates Roadmap
|
||||
|
||||
### Short Term (Next 30 Days)
|
||||
|
||||
- [ ] Add `convex-auth` skill for authentication patterns
|
||||
- [ ] Add `convex-vector-search` skill for AI/embeddings
|
||||
- [ ] Add `convex-testing` skill for test patterns
|
||||
- [ ] Update all skills to reference Convex v1.18+ APIs
|
||||
|
||||
### Medium Term (Next 90 Days)
|
||||
|
||||
- [ ] Add skill validation CLI command
|
||||
- [ ] Auto-generate skill index from folder structure
|
||||
- [ ] Add `convex-deployment` skill for production patterns
|
||||
- [ ] Add `convex-rate-limiting` skill
|
||||
- [ ] Consider monorepo tooling if skills grow significantly
|
||||
|
||||
### Long Term
|
||||
|
||||
- [ ] Automated doc link checking in CI
|
||||
- [ ] Community contribution pipeline
|
||||
- [ ] Skill versioning independent of package version
|
||||
- [ ] Integration tests for each skill's code examples
|
||||
|
||||
---
|
||||
|
||||
## Common Maintenance Tasks
|
||||
|
||||
### Fixing Broken Documentation Links
|
||||
|
||||
1. Search all skills for the broken URL
|
||||
2. Update to current Convex docs URL
|
||||
3. Verify new link works
|
||||
4. Patch release
|
||||
|
||||
```bash
|
||||
# Find all doc links
|
||||
grep -r "docs.convex.dev" skills/
|
||||
```
|
||||
|
||||
### Syncing with Convex API Changes
|
||||
|
||||
When Convex releases new versions:
|
||||
|
||||
1. Check [Convex changelog](https://docs.convex.dev/changelog)
|
||||
2. Search skills for affected patterns
|
||||
3. Update examples to use new APIs
|
||||
4. Note deprecations in skill Best Practices section
|
||||
|
||||
### Adding Support for New AI Agent
|
||||
|
||||
1. Create agent-specific context file (like `GEMINI.md`)
|
||||
2. Add installation instructions to README
|
||||
3. Test with the target agent
|
||||
4. Document in changelog
|
||||
|
||||
---
|
||||
|
||||
## Automation Ideas
|
||||
|
||||
### GitHub Actions for Link Checking
|
||||
|
||||
```yaml
|
||||
name: Check Links
|
||||
on:
|
||||
schedule:
|
||||
- cron: "0 0 * * 0" # Weekly
|
||||
jobs:
|
||||
linkcheck:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: lycheeverse/lychee-action@v1
|
||||
with:
|
||||
args: --verbose ./skills/
|
||||
```
|
||||
|
||||
### Pre-publish Checklist Script
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# scripts/pre-publish.sh
|
||||
|
||||
echo "Running pre-publish checks..."
|
||||
|
||||
# Check all skills have frontmatter
|
||||
for skill in skills/*/SKILL.md; do
|
||||
if ! head -1 "$skill" | grep -q "^---$"; then
|
||||
echo "ERROR: $skill missing frontmatter"
|
||||
exit 1
|
||||
fi
|
||||
done
|
||||
|
||||
# Verify index.js matches skills folder
|
||||
echo "Skills in folder: $(ls -1 skills | wc -l)"
|
||||
echo "Skills in index.js: $(grep -c '"convex-' index.js)"
|
||||
|
||||
echo "All checks passed!"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Publish New Version
|
||||
|
||||
```bash
|
||||
# 1. Update changelog.md
|
||||
# 2. Bump version
|
||||
npm version patch
|
||||
|
||||
# 3. Publish
|
||||
npm publish --access public
|
||||
|
||||
# 4. Push tags
|
||||
git push && git push --tags
|
||||
```
|
||||
|
||||
### Test Installation Locally
|
||||
|
||||
```bash
|
||||
npm pack
|
||||
npm install -g ./waynesutton-convex-skills-*.tgz
|
||||
convex-skills list
|
||||
```
|
||||
|
||||
### Check Published Package
|
||||
|
||||
```bash
|
||||
npm info @waynesutton/convex-skills
|
||||
npm view @waynesutton/convex-skills versions
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Resources
|
||||
|
||||
- [npm Publishing Guide](https://docs.npmjs.com/cli/v10/commands/npm-publish)
|
||||
- [Semantic Versioning](https://semver.org/)
|
||||
- [Keep a Changelog](https://keepachangelog.com/)
|
||||
- [Agent Skills Spec](https://github.com/anthropics/skills)
|
||||
- [Convex Documentation](https://docs.convex.dev/)
|
||||
- [Convex LLMs.txt](https://docs.convex.dev/llms.txt)
|
||||
@@ -4,101 +4,104 @@ Brief description of each file in the repository.
|
||||
|
||||
## Root Files
|
||||
|
||||
| File | Description |
|
||||
|------|-------------|
|
||||
| `AGENTS.md` | Agent skills specification for AI coding agents |
|
||||
| `CLAUDE.md` | Claude Code project context (mirrors AGENTS.md) |
|
||||
| `CONTRIBUTING.md` | Contribution guidelines |
|
||||
| `GEMINI.md` | Gemini CLI integration instructions |
|
||||
| `LICENSE` | Apache-2.0 license |
|
||||
| `README.md` | Project overview and installation |
|
||||
| `changelog.md` | Version history following keepachangelog format |
|
||||
| `files.md` | This file, codebase structure reference |
|
||||
| `task.md` | Completed task tracking |
|
||||
| File | Description |
|
||||
| ------------------------------- | ----------------------------------------------- |
|
||||
| `AGENTS.md` | Agent skills specification for AI coding agents |
|
||||
| `CLAUDE.md` | Claude Code project context (mirrors AGENTS.md) |
|
||||
| `CONTRIBUTING.md` | Contribution guidelines |
|
||||
| `GEMINI.md` | Gemini CLI integration instructions |
|
||||
| `LICENSE` | Apache-2.0 license |
|
||||
| `README.md` | Project overview and installation |
|
||||
| `changelog.md` | Version history following keepachangelog format |
|
||||
| `files.md` | This file, codebase structure reference |
|
||||
| `task.md` | Completed task tracking |
|
||||
| `convex-skills-updates-plan.md` | Build guide and maintenance plan |
|
||||
|
||||
## Skills Directory (`skills/`)
|
||||
|
||||
Core Convex skills for AI agents.
|
||||
Core Convex skills for AI agents. Each skill has `name` matching folder name for `/skill` commands.
|
||||
|
||||
| Skill | Description |
|
||||
|-------|-------------|
|
||||
| `convex-agents/SKILL.md` | Building AI agents with Convex |
|
||||
| `convex-best-practices/SKILL.md` | Production-ready app guidelines |
|
||||
| `convex-component-authoring/SKILL.md` | Creating reusable Convex components |
|
||||
| `convex-cron-jobs/SKILL.md` | Scheduled functions and background tasks |
|
||||
| `convex-file-storage/SKILL.md` | File upload, storage, and serving |
|
||||
| `convex-functions/SKILL.md` | Queries, mutations, actions |
|
||||
| `convex-http-actions/SKILL.md` | HTTP endpoints and webhooks |
|
||||
| `convex-migrations/SKILL.md` | Schema evolution and data migrations |
|
||||
| `convex-realtime/SKILL.md` | Reactive patterns and subscriptions |
|
||||
| `convex-schema-validator/SKILL.md` | Schema definition and validation |
|
||||
| `convex-security-audit/SKILL.md` | Deep security review patterns |
|
||||
| `convex-security-check/SKILL.md` | Quick security audit checklist |
|
||||
| Skill | Description |
|
||||
| ------------------------------------- | ---------------------------------------- |
|
||||
| `avoid-feature-creep/SKILL.md` | Prevent scope creep in development |
|
||||
| `convex/SKILL.md` | Umbrella index for all Convex skills |
|
||||
| `convex-agents/SKILL.md` | Building AI agents with Convex |
|
||||
| `convex-best-practices/SKILL.md` | Production-ready app guidelines |
|
||||
| `convex-component-authoring/SKILL.md` | Creating reusable Convex components |
|
||||
| `convex-cron-jobs/SKILL.md` | Scheduled functions and background tasks |
|
||||
| `convex-file-storage/SKILL.md` | File upload, storage, and serving |
|
||||
| `convex-functions/SKILL.md` | Queries, mutations, actions |
|
||||
| `convex-http-actions/SKILL.md` | HTTP endpoints and webhooks |
|
||||
| `convex-migrations/SKILL.md` | Schema evolution and data migrations |
|
||||
| `convex-realtime/SKILL.md` | Reactive patterns and subscriptions |
|
||||
| `convex-schema-validator/SKILL.md` | Schema definition and validation |
|
||||
| `convex-security-audit/SKILL.md` | Deep security review patterns |
|
||||
| `convex-security-check/SKILL.md` | Quick security audit checklist |
|
||||
|
||||
## Command Directory (`command/`)
|
||||
|
||||
Slash command definitions for OpenCode integration.
|
||||
|
||||
| File | Description |
|
||||
|------|-------------|
|
||||
| File | Description |
|
||||
| ----------- | ------------------------------------------------------ |
|
||||
| `convex.md` | `/convex` slash command entrypoint with decision trees |
|
||||
|
||||
## Templates Directory (`templates/`)
|
||||
|
||||
Templates for developers to copy when forking.
|
||||
|
||||
| File | Description |
|
||||
|------|-------------|
|
||||
| `CLAUDE.md` | Project context template for Convex projects |
|
||||
| `skills/README.md` | Installation guide for skill templates |
|
||||
| `skills/dev.md` | Full-stack development practices template |
|
||||
| `skills/help.md` | Problem-solving methodology template |
|
||||
| `skills/gitrules.md` | Git safety protocols template |
|
||||
| File | Description |
|
||||
| -------------------- | -------------------------------------------- |
|
||||
| `CLAUDE.md` | Project context template for Convex projects |
|
||||
| `skills/README.md` | Installation guide for skill templates |
|
||||
| `skills/dev.md` | Full-stack development practices template |
|
||||
| `skills/help.md` | Problem-solving methodology template |
|
||||
| `skills/gitrules.md` | Git safety protocols template |
|
||||
|
||||
## Claude Skills Directory (`.claude/skills/`)
|
||||
|
||||
Active Claude Code skills for this repository.
|
||||
|
||||
| File | Description |
|
||||
|------|-------------|
|
||||
| `convex.md` | Convex-specific coding guidelines |
|
||||
| `dev.md` | Full-stack development practices |
|
||||
| `gitrules.md` | Git safety protocols |
|
||||
| `help.md` | Problem-solving methodology |
|
||||
| `write.md` | Writing style guide |
|
||||
| File | Description |
|
||||
| ------------- | --------------------------------- |
|
||||
| `convex.md` | Convex-specific coding guidelines |
|
||||
| `dev.md` | Full-stack development practices |
|
||||
| `gitrules.md` | Git safety protocols |
|
||||
| `help.md` | Problem-solving methodology |
|
||||
| `write.md` | Writing style guide |
|
||||
|
||||
## PRDs Directory (`prds/`)
|
||||
|
||||
Product requirement documents and planning.
|
||||
|
||||
| File | Description |
|
||||
|------|-------------|
|
||||
| `CLAUDE-MD-STRATEGY.md` | Strategy for CLAUDE.md templates |
|
||||
| `CLAUDE-MD-STRATEGY_1.md` | Alternate strategy document |
|
||||
| `MARKETPLACE-SUBMISSION.md` | Marketplace submission guidelines |
|
||||
| `create-convex-opencode-integration.md` | OpenCode integration spec |
|
||||
| `future-skills-exploration.md` | Future skills roadmap |
|
||||
| `phase3-convex-docs-recommendations.md` | Convex docs improvement recommendations |
|
||||
| `phase4-convex-ai-website-recommendations.md` | convex.dev/ai recommendations |
|
||||
| `skillsplan.md` | Skills development plan |
|
||||
| File | Description |
|
||||
| --------------------------------------------- | --------------------------------------- |
|
||||
| `CLAUDE-MD-STRATEGY.md` | Strategy for CLAUDE.md templates |
|
||||
| `CLAUDE-MD-STRATEGY_1.md` | Alternate strategy document |
|
||||
| `MARKETPLACE-SUBMISSION.md` | Marketplace submission guidelines |
|
||||
| `create-convex-opencode-integration.md` | OpenCode integration spec |
|
||||
| `future-skills-exploration.md` | Future skills roadmap |
|
||||
| `phase3-convex-docs-recommendations.md` | Convex docs improvement recommendations |
|
||||
| `phase4-convex-ai-website-recommendations.md` | convex.dev/ai recommendations |
|
||||
| `skillsplan.md` | Skills development plan |
|
||||
|
||||
## OpenCode Directory (`.opencode/`)
|
||||
|
||||
OpenCode plugin configuration and templates.
|
||||
|
||||
| Directory | Description |
|
||||
|-----------|-------------|
|
||||
| `agent/` | Agent templates for orchestration |
|
||||
| `command/` | Command templates for Convex operations |
|
||||
| `plugin/` | Plugin hooks and tools |
|
||||
| `skill/` | OpenCode-specific skills |
|
||||
| `config.json` | Plugin configuration |
|
||||
| Directory | Description |
|
||||
| ------------- | --------------------------------------- |
|
||||
| `agent/` | Agent templates for orchestration |
|
||||
| `command/` | Command templates for Convex operations |
|
||||
| `plugin/` | Plugin hooks and tools |
|
||||
| `skill/` | OpenCode-specific skills |
|
||||
| `config.json` | Plugin configuration |
|
||||
|
||||
## Cursor Directory (`.cursor/`)
|
||||
|
||||
Cursor IDE configuration.
|
||||
|
||||
| Directory | Description |
|
||||
|-----------|-------------|
|
||||
| `plans/` | Development plans |
|
||||
| `rules/` | Workspace rules for Cursor |
|
||||
| Directory | Description |
|
||||
| --------- | -------------------------- |
|
||||
| `plans/` | Development plans |
|
||||
| `rules/` | Workspace rules for Cursor |
|
||||
|
||||
@@ -52,7 +52,8 @@ export function getSkillPath(skillName) {
|
||||
* Available skills with descriptions
|
||||
*/
|
||||
export const SKILLS = {
|
||||
"convex-best-practices": "Guidelines for building production-ready Convex apps",
|
||||
"convex-best-practices":
|
||||
"Guidelines for building production-ready Convex apps",
|
||||
"convex-functions": "Writing queries, mutations, actions, and HTTP actions",
|
||||
"convex-realtime": "Patterns for building reactive applications",
|
||||
"convex-schema-validator": "Database schema definition and validation",
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
---
|
||||
name: Convex Agents
|
||||
name: convex-agents
|
||||
displayName: Convex Agents
|
||||
description: Building AI agents with the Convex Agent component including thread management, tool integration, streaming responses, RAG patterns, and workflow orchestration
|
||||
version: 1.0.0
|
||||
author: Convex
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
---
|
||||
name: Convex Best Practices
|
||||
name: convex-best-practices
|
||||
displayName: Convex Best Practices
|
||||
description: Guidelines for building production-ready Convex apps covering function organization, query patterns, validation, TypeScript usage, error handling, and the Zen of Convex design philosophy
|
||||
version: 1.0.0
|
||||
author: Convex
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
---
|
||||
name: Convex Component Authoring
|
||||
name: convex-component-authoring
|
||||
displayName: Convex Component Authoring
|
||||
description: How to create, structure, and publish self-contained Convex components with proper isolation, exports, and dependency management
|
||||
version: 1.0.0
|
||||
author: Convex
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
---
|
||||
name: Convex Cron Jobs
|
||||
name: convex-cron-jobs
|
||||
displayName: Convex Cron Jobs
|
||||
description: Scheduled function patterns for background tasks including interval scheduling, cron expressions, job monitoring, retry strategies, and best practices for long-running tasks
|
||||
version: 1.0.0
|
||||
author: Convex
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
---
|
||||
name: Convex File Storage
|
||||
name: convex-file-storage
|
||||
displayName: Convex File Storage
|
||||
description: Complete file handling including upload flows, serving files via URL, storing generated files from actions, deletion, and accessing file metadata from system tables
|
||||
version: 1.0.0
|
||||
author: Convex
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
---
|
||||
name: Convex Functions
|
||||
name: convex-functions
|
||||
displayName: Convex Functions
|
||||
description: Writing queries, mutations, actions, and HTTP actions with proper argument validation, error handling, internal functions, and runtime considerations
|
||||
version: 1.0.0
|
||||
author: Convex
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
---
|
||||
name: Convex HTTP Actions
|
||||
name: convex-http-actions
|
||||
displayName: Convex HTTP Actions
|
||||
description: External API integration and webhook handling including HTTP endpoint routing, request/response handling, authentication, CORS configuration, and webhook signature validation
|
||||
version: 1.0.0
|
||||
author: Convex
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
---
|
||||
name: Convex Migrations
|
||||
name: convex-migrations
|
||||
displayName: Convex Migrations
|
||||
description: Schema migration strategies for evolving applications including adding new fields, backfilling data, removing deprecated fields, index migrations, and zero-downtime migration patterns
|
||||
version: 1.0.0
|
||||
author: Convex
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
---
|
||||
name: Convex Realtime
|
||||
name: convex-realtime
|
||||
displayName: Convex Realtime
|
||||
description: Patterns for building reactive apps including subscription management, optimistic updates, cache behavior, and paginated queries with cursor-based loading
|
||||
version: 1.0.0
|
||||
author: Convex
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
---
|
||||
name: Convex Schema Validator
|
||||
name: convex-schema-validator
|
||||
displayName: Convex Schema Validator
|
||||
description: Defining and validating database schemas with proper typing, index configuration, optional fields, unions, and migration strategies for schema changes
|
||||
version: 1.0.0
|
||||
author: Convex
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
---
|
||||
name: Convex Security Audit
|
||||
name: convex-security-audit
|
||||
displayName: Convex Security Audit
|
||||
description: Deep security review patterns for authorization logic, data access boundaries, action isolation, rate limiting, and protecting sensitive operations
|
||||
version: 1.0.0
|
||||
author: Convex
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
---
|
||||
name: Convex Security Check
|
||||
name: convex-security-check
|
||||
displayName: Convex Security Check
|
||||
description: Quick security audit checklist covering authentication, function exposure, argument validation, row-level access control, and environment variable handling
|
||||
version: 1.0.0
|
||||
author: Convex
|
||||
|
||||
@@ -0,0 +1,62 @@
|
||||
---
|
||||
name: convex
|
||||
displayName: Convex Development
|
||||
description: Umbrella skill for all Convex development patterns. Routes to specific skills like convex-functions, convex-realtime, convex-agents, etc.
|
||||
version: 1.0.0
|
||||
author: Convex
|
||||
tags: [convex, backend, database, realtime]
|
||||
---
|
||||
|
||||
# Convex Development Skills
|
||||
|
||||
This is an index skill for Convex development. Use specific skills for detailed guidance:
|
||||
|
||||
## Core Development
|
||||
|
||||
| Skill | Command | Use When |
|
||||
|-------|---------|----------|
|
||||
| Functions | `/convex-functions` | Writing queries, mutations, actions |
|
||||
| Schema | `/convex-schema-validator` | Defining database schemas and validators |
|
||||
| Realtime | `/convex-realtime` | Building reactive subscriptions |
|
||||
| HTTP Actions | `/convex-http-actions` | Webhooks and HTTP endpoints |
|
||||
|
||||
## Data & Storage
|
||||
|
||||
| Skill | Command | Use When |
|
||||
|-------|---------|----------|
|
||||
| File Storage | `/convex-file-storage` | File uploads, serving, storage |
|
||||
| Migrations | `/convex-migrations` | Schema evolution, data backfills |
|
||||
|
||||
## Advanced Patterns
|
||||
|
||||
| Skill | Command | Use When |
|
||||
|-------|---------|----------|
|
||||
| Agents | `/convex-agents` | Building AI agents with tools |
|
||||
| Cron Jobs | `/convex-cron-jobs` | Scheduled background tasks |
|
||||
| Components | `/convex-component-authoring` | Reusable Convex packages |
|
||||
|
||||
## Security
|
||||
|
||||
| Skill | Command | Use When |
|
||||
|-------|---------|----------|
|
||||
| Security Check | `/convex-security-check` | Quick security audit checklist |
|
||||
| Security Audit | `/convex-security-audit` | Deep security review |
|
||||
|
||||
## Guidelines
|
||||
|
||||
| Skill | Command | Use When |
|
||||
|-------|---------|----------|
|
||||
| Best Practices | `/convex-best-practices` | General patterns and guidelines |
|
||||
|
||||
## Quick Start
|
||||
|
||||
For most tasks:
|
||||
1. Start with `/convex-best-practices` for general patterns
|
||||
2. Use `/convex-functions` for writing backend logic
|
||||
3. Use `/convex-schema-validator` for data modeling
|
||||
4. Use specific skills as needed for your use case
|
||||
|
||||
## Documentation
|
||||
|
||||
- Primary: https://docs.convex.dev
|
||||
- LLM-optimized: https://docs.convex.dev/llms.txt
|
||||
Reference in New Issue
Block a user