How to Work with AI

The rules and skills in this repo make AI assistants more useful. Here's how to get the most out of them.

Rules kick in automatically

The .cursor/rules/ files are always active. You don't need to reference them or paste them into prompts. When you ask an AI agent to "add a new API route," it already knows to:

Use getAuthenticatedApp() for the route group
Add validate("json", schema) middleware
Throw ApplicationError instead of using try/catch
Put the route in src/routes/<domain>/index.ts
Keep the handler thin and call a module function

Skills are triggered by context

Skills activate when the task matches their purpose. Ask the agent to "build a settings page" and the frontend-design skill produces polished UI. Ask it to "plan the billing flow" and grill-with-docs has it check the plan against the docs before writing a line. find-skills covers the rest: when a task has no matching skill, the agent looks for one on skills.sh before improvising.

Tips for better results

Be specific about location

Instead of "add a notification feature," say "add a notification feature in src/features/notifications/." The rules handle conventions, but you still need to tell the agent where to work.

Reference existing patterns

"Make it work like src/features/projects/" gives the AI a concrete example to follow. The codebase is consistent, so pointing at any domain works as a template.

Let it handle structure

Don't micromanage file placement. The rules encode the folder conventions (modules/, db/queries/, db/mutations/, schemas/). Say what you want built, and the rules handle where files go.

Review the output

AI-generated code follows your conventions, but it still needs review. Check that:

Business logic makes sense
Edge cases are handled
Database queries are efficient
The feature integrates with existing code correctly

Adding your own rules

Create a new .mdc file in .cursor/rules/:

---
description: When to activate this rule
globs:
  - "src/features/my-domain/**"
---

# My Rule

Instructions here.

Rules with globs activate only when editing matching files. Rules without globs are always active. Keep rules focused: one topic per file.

Adding skills

Create a new skill in .agents/skills/<name>/SKILL.md. Skills are longer-form guides that teach agents a complete workflow, like creating a pack or designing a UI component.