Using uc-apx in a Project

uc-apx is most useful when your coding agent (Claude Code, Cursor, Windsurf, …) reaches for it on its own whenever a task touches .apx files. That takes two things: the skills installed in the project, and a one-line instruction in your agent’s project file telling it to use them.

1. Sync the Skills into the Project

uc-apx ships a set of skills — SKILL.md playbooks that teach an agent how to read, edit, and validate apexlang apps. Install them into the project so the agent picks them up automatically.

From the root of your exported APEX app:

uc-apx skills sync

This auto-detects your agent and writes the skills to the local skills directory (e.g. .claude/skills/ for Claude Code, .agents/skills/ for the universal layout). Preview first with --dry-run:

uc-apx skills sync --dry-run

Local vs. global

skills sync installs into the current directory by default — keep the skills versioned alongside the app so teammates and CI get the same playbooks. Use --global instead if you’d rather install once into ~/.claude/skills/ and have them available in every project. See skills sync for all flags.

Re-run skills sync any time to pull the latest skill content — existing files are overwritten.

2. Tell Your Agent to Use uc-apx

Installing the skills isn’t enough on its own — most agents won’t reliably discover them mid-task. Add an explicit instruction to your agent’s project memory file so it reaches for uc-apx and reads the entry-point skill first on any .apx work.

The file depends on your agent:

• Claude Code → CLAUDE.md
• Cursor / Windsurf / others → AGENTS.md

Add a section like this:

## Working with this APEX app (.apx files)

This is an Oracle APEX application exported in APEXlang (`.apx`) format. **Always**
use the `uc-apx` CLI to read, edit, and validate these files — don't hand-edit `.apx`
unless a command can't do it or the user explicitly instructs it.

Before touching any `.apx` file, read the getting-started skill first:
`skills/getting-started/SKILL.md` (or `.claude/skills/getting-started/SKILL.md`).
It routes you to the right read/edit/verify skill and states the mandatory validate gate.

Run `uc-apx validate` (and `uc-apx validate --official` when SQLcl is available) after every editing pass — a non-zero exit means the task is not done.

Why both pieces matter

The skills give the agent the how; the line in CLAUDE.md / AGENTS.md gives it the when. Without the instruction, an agent will often edit .apx by hand and skip validation. With it, the agent opens getting-started and follows the routing table to the task-specific skill.

3. Verify the Setup

Confirm the binary is reachable and the app parses:

uc-apx version
uc-apx overview

Then check the skills landed where the agent expects them:

ls .claude/skills/        # Claude Code
ls .agents/skills/        # universal layout

You should see getting-started/ alongside the read/edit/verify skill folders.

What the Agent Does Next

Once set up, a typical agent task flow looks like:

1. Reads skills/getting-started/SKILL.md to orient itself.
2. Follows the routing table to the right skill (e.g. edit/add-region-or-item-to-page).
3. Uses uc-apx create … / uc-apx edit … instead of hand-writing .apx.
4. Runs uc-apx validate after each change and before declaring done.

Next Steps

• skills sync — all flags and install targets
• Commands reference — every command and flag
• APEXlang format — understand the .apx DSL