How to use the Convex App Optimizer agent skill (convex-optimize)

What is an agent skill?

An agent skill is a folder of instructions that an AI agent, such as Claude, loads when a request matches the skill's purpose. The skill tells the agent which steps to follow, in what order, and what it may do. This skill is packaged as a folder containing a single file named SKILL.md.

What does the convex-optimize skill make the agent do?

For an existing Convex app, the agent follows a fixed workflow. It first detects the project by looking for a convex/ directory, the schema, and whether the deployment is anonymous or cloud. It then runs a scored assessment by delegating to the separate launch-readiness skill, which is not included in this package.

• Checks whether the Convex components your app depends on (@convex-dev/* packages) are out of date, using the check-updates skill.
• Offers to set up production error monitoring with the sentinel skill if the readiness report flags that no production errors are captured.
• Presents one combined, prioritized plan with security and data-loss issues first.
• Changes files only after you explicitly confirm.
• Re-runs the assessment after fixes and shows how the score changed.

How do you install the skill?

The skill is distributed as a ZIP file from the download link on this page. Unzip it so that the convex-optimize folder, containing SKILL.md, sits in one of these locations:

• Personal: ~/.claude/skills/ (available across your projects).
• Project only: a .claude/skills/ folder inside your Convex project.
• Claude apps: upload the ZIP under Settings → Capabilities → Skills.

How do you trigger the skill with a natural request?

You do not need a special command. Describe what you want in plain language while working in your Convex project. Requests that match the skill's purpose include auditing, optimizing, checking security, checking for upgrades, or preparing for launch. Mention that the app is Convex so the agent loads the right workflow.

• "Audit my Convex app and give me a prioritized cleanup plan."
• "Check whether my Convex components are out of date."
• "Get this Convex app ready for launch, including error monitoring."
• "Review the security and data-loss risks in my convex/ folder before we change anything."

What do you need before you run it?

The skill only works on a Convex project. The workflow depends on Convex conventions such as the convex/ directory and @convex-dev components. The skill also references three other skills that are not included in this package.

• A Convex project with a convex/ directory.
• The launch-readiness skill, which performs the assessment. Without it the scored audit will not run.
• The check-updates skill, for component upgrade checks.
• The sentinel skill, for observability setup.

What should you know about safety?

The skill is designed to act on code, so treat it with care. According to the source, the skill does not run scripts and does not use the network. It can, however, modify your files after you confirm a plan. Its workflow is read-only until you confirm, and it is designed not to auto-land changes on an existing production app and to re-assess after applying fixes.

Before confirming changes, keep your project under version control and make a backup. Review the plan and the diff carefully, especially for live production code.

• Make a commit or backup before you approve any changes.
• Read the prioritized plan first; security and data-loss items appear at the top.
• Do not confirm a plan you do not understand.