Agent Skills for UserSpice

These skills were originally developed for Claude Code and are now maintained as portable, host-neutral Agent Skills. Claude Code and Codex have documented install and invocation paths; other coding agents can use the same SKILL.md workflows when they support the Agent Skills format. Each skill remains independently installable.

The installed UserSpice source is authoritative. The skills inspect users/ for live helper and class signatures instead of relying on baked-in copies that can go stale. The optional AI Prompts plugin adds versioned framework context when it is installed.

userspice-audit

Audits a UserSpice project's custom PHP against the UserSpice security and best-practices checklist. It reports findings with file paths, line numbers, evidence, and concrete fixes. It never modifies application code or Git configuration.

What it scans — top-level pages, usersc/, custom folders, plugins, and AJAX parsers/. It skips framework code under users/, dependencies, generated reports, and backup folders.
What it checks — unsafe request access, missing CSRF protection, SQL string concatenation, unescaped output, unsafe redirects, weak token generation, missing rate limiting, misplaced AJAX endpoints, and other UserSpice-specific risks.
How it runs — it may split bounded scopes across workers when the host supports parallel agents, with a sequential fallback when it does not. You can also audit a single file or narrow the scope.
Output — one dated Markdown report under _noupload/audit-reports/, grouped by severity. The skill does not read, add, or change .gitignore.

Invoke it from inside a UserSpice project directory:

# Claude Code /userspice-audit /userspice-audit usersc/contact.php # OpenAI Codex $userspice-audit $userspice-audit usersc/contact.php

userspice-helper-lookup

Given a helper name, class method, or task description, this read-only skill returns the live signature, source location, intended use, a worked example, and relevant warnings. It searches the installed users/helpers/ and users/classes/ source so its answer matches the version you are actually running.

By name — look up safeReturn and get the declaration plus correct usage.
By class method — inspect methods such as Token::check or Redirect::sanitized directly from their class files.
By task — ask for a “CSRF field for a form,” “safe redirect,” or “rate limit a login” without knowing the helper name first.
Warnings included — known weak or commonly misused helpers are returned with the preferred alternative and the reason.

# Claude Code /userspice-helper-lookup Token::check # OpenAI Codex $userspice-helper-lookup Token::check

userspice-page-scaffold

Generates one new UserSpice PHP page using helpers verified against the installed framework. Choose a guarded display page, a self-posting validated form, or an AJAX endpoint inside a parsers/ folder. The complete proposed file is previewed before anything is written.

Framework-aware — verifies live signatures for page guards, CSRF handling, validation, escaping, redirects, and flash messages before generating code.
Explicit confirmation — confirms the target path and shows the full proposed output before the write.
One-file boundary — writes only the confirmed target file. It does not change routes, menus, database schema, Git configuration, or host-agent settings.
Audit-aligned output — generated code is designed to follow the same security and best-practices checklist used by userspice-audit.

# Claude Code /userspice-page-scaffold feedback.php # OpenAI Codex $userspice-page-scaffold feedback.php

How to install

Clone the canonical repository once:

git clone https://github.com/UserSpice-AI/userspice-claude-skills.git

Claude Code

Copy one or all skill directories under ~/.claude/skills/:

mkdir -p ~/.claude/skills cp -r userspice-claude-skills/userspice-audit ~/.claude/skills/ cp -r userspice-claude-skills/userspice-helper-lookup ~/.claude/skills/ cp -r userspice-claude-skills/userspice-page-scaffold ~/.claude/skills/

OpenAI Codex

Copy one or all skill directories under ~/.agents/skills/:

mkdir -p ~/.agents/skills cp -r userspice-claude-skills/userspice-audit ~/.agents/skills/ cp -r userspice-claude-skills/userspice-helper-lookup ~/.agents/skills/ cp -r userspice-claude-skills/userspice-page-scaffold ~/.agents/skills/

Codex can also discover project-scoped skills under .agents/skills/. Both hosts can use symlinks when you prefer one checked-out copy. For another agent, consult that host's documentation for its skill directory and invocation syntax.

Write boundaries and host permissions

Your coding agent—not the skill—owns sandboxing, command approvals, and permission settings. The skills describe the work they need but never edit Claude Code settings, Codex settings, Git configuration, or other host-agent configuration.

userspice-helper-lookup is read-only.
userspice-page-scaffold writes one explicitly previewed and confirmed target file.
userspice-audit writes one new report under _noupload/audit-reports/.
None of the skills modify framework code under users/ or touch the database.

The audit deliberately leaves _noupload/ alone. If your repository tracks that directory, the generated report appears in the working tree normally.

Requirements and compatibility

Agent host — Claude Code is the primary development environment. Codex supports the Agent Skills structure; representative runtime testing is still in progress. Other hosts may work when they support compatible SKILL.md workflows.
UserSpice — version 6.0.9 or newer. Older or unknown versions require confirmation because helpers and rules may differ.
Shell — a Bash-compatible environment with awk, find, and grep. Linux and macOS run natively; Windows users should use Git Bash or WSL with forward-slash paths.
Not supported directly — Windows Command Prompt and PowerShell do not provide the bundled shell environment.

Where the source lives

Source: github.com/UserSpice-AI/userspice-claude-skills. Bug reports, feature requests, and questions go on the repository's issue tracker. Report prompt-injection, permission-escalation, or unsafe-file-operation issues privately using the instructions in the repository's SECURITY.md.