Claude Code skills for UserSpice

Each skill ships as a folder under ~/.claude/skills/ with a SKILL.md file. Claude Code discovers them on startup and lets you trigger them by slash command. All three are read-only on the framework itself — they grep users/ for canonical signatures rather than carrying baked-in copies that go stale.

/userspice-audit

Audits a UserSpice project's custom code (everything outside users/) against the 12 rules of the official UserSpice Security & Best Practices guide. Reports findings with file paths, line numbers, and concrete fixes. Never modifies code — it only reports.

What it scans — top-level pages, usersc/, custom folders, plugins, and AJAX parsers/. Skips users/ (framework), vendor/, node_modules/, _noupload/, and backup folders.
The 12 rules — direct $_POST / $_GET access, missing CSRF tokens, SQL string concatenation, $_SERVER direct access, unescaped output, unsafe redirects, weak crypto for tokens, missing rate-limiting on auth endpoints, $config shadowing, AJAX endpoints outside parsers/, and more.
Modes — parallel (default, dispatches subagents for plugins and large folders), --walk for file-by-file with inline findings, --scope to narrow to one bucket, or single-file mode by passing a .php path.
Output — a dated markdown report at _noupload/audit-reports/audit-report-YYYY-MM-DD.md, grouped by severity. Adds _noupload/ to .gitignore if missing.

Invoke from inside a UserSpice project directory:

/userspice-audit # whole project (minus framework/vendor) /userspice-audit usersc/contact.php # single file /userspice-audit --scope plugins # just usersc/plugins/ /userspice-audit --walk # sequential, with inline findings

/userspice-helper-lookup

Given a helper name, a class method, or a task description, returns the canonical signature with file:line, a one-line "use this when," and a worked example. The signature comes from a live grep of users/helpers/ and users/classes/ — so it's always current, even when documentation or model memory has drifted.

By name — /userspice-helper-lookup safeReturn. Greps the helpers folder for the function declaration and prints the signature.
By class method — /userspice-helper-lookup Token::check or /userspice-helper-lookup Redirect::sanitized. Reads the class file directly.
By task — /userspice-helper-lookup "csrf field for a form" or /userspice-helper-lookup "rate limit a login". Matches against an internal topic map covering output escaping, input, CSRF, SQL, server vars, redirects, crypto, rate limiting, outbound HTTP, and page guards.
Known weak helpers — flags random_password(), Cookie::delete(), err(), write_php_ini(), and a handful of others, with the recommended replacement and the reason.

/userspice-page-scaffold

Generates a new UserSpice page with the security helpers wired correctly on day one: init.php include, securePage guard, CSRF via tokenHere(), Token::check on submit, Validate->check(), safeReturn() for output, usError / usSuccess flash, and a redirect-after-POST. The generated file passes /userspice-audit cleanly.

Three templates — simple (guarded display page, no form), form (posts to itself, validated, redirects on success), and ajax (parsers/ endpoint that returns JSON, with re-checked auth and CSRF).
Asks before writing — chained Q&A for path, page type, auth level, page title, form fields, and (optional) DB-write table. Shows the full proposed file with line numbers before writing.
Writes exactly one file — doesn't modify menus, routes, the database, or anything else. The init.php path is computed from file depth; every other include uses $abs_us_root . $us_url_root . '…'.
Field types supported — text, email, password, textarea, number, checkbox, select(opt1|opt2), hidden. Validation rules emit with is_numeric / valid_email / matches matched to the type.

Invoke from inside a UserSpice project directory:

/userspice-page-scaffold # interactive /userspice-page-scaffold feedback.php # path passed in /userspice-page-scaffold parsers/save_note.php # ajax endpoint

How to install

Skills install per-user under ~/.claude/skills/<name>/SKILL.md. Clone the repo and drop each folder into place:

git clone https://github.com/UserSpice-AI/userspice-claude-skills.git 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/

Or install just the one you want by copying that folder only. Verify Claude Code sees them — open a Claude Code session in any directory and type /; the three commands should appear in the list.

Permissions

The skills run find and grep extensively to locate UserSpice installs, walk file trees, and look up helper signatures. Without an allowlist, Claude Code will prompt for permission on every call.

After the first run, userspice-audit and userspice-page-scaffold offer to add the relevant entries to either ~/.claude/settings.json (global) or <install>/.claude/settings.json (project). Or add them yourself before the first run:

{ "permissions": { "allow": ["Bash(find:*)", "Bash(grep:*)"] } }

The skills never modify code under users/ and never touch the database. userspice-page-scaffold writes exactly one new file at a path you confirm; userspice-audit writes only an audit report under _noupload/audit-reports/; userspice-helper-lookup is read-only.

Requirements

Claude Code with skill support — the ~/.claude/skills/ folder is read on startup.
UserSpice 6.0.9+ on the site you're working with. Older installs trigger a warning and a y/N gate — helper signatures, rule numbers, and KB references are calibrated against 6.0.9. Override the floor with the MIN_USERSPICE_VER environment variable if needed.
Bash — every skill is bash-driven for the discovery / grep steps. Native on Linux and macOS. On Windows, run Claude Code under Git Bash or WSL; both ship the required commands. Use forward-slash paths on Windows (C:/Users/you/site, not C:\Users\…). Direct cmd / PowerShell is not supported.
Optional — the AI Prompts plugin installed at usersc/plugins/ai_prompts/. Each skill detects it automatically and treats its prompt files as the most current canonical reference for UserSpice patterns. If the plugin isn't installed, the skills fall back to the canonical guide at userspice.com/userspice-best-practices/.

Compatibility

Linux — native.
macOS — native.
Windows (Git Bash) — supported. Use forward-slash paths.
Windows (WSL) — supported. Use forward-slash paths.
Windows (cmd / PowerShell directly) — not supported; Claude Code must be using a bash environment.

Where the source lives

Source: github.com/UserSpice-AI/userspice-claude-skills. Bug reports, feature requests, and questions go on the repo's issue tracker. Security-relevant issues (prompt injection vectors, permission escalations, unsafe file operations) should be reported privately by email — see the repo's SECURITY.md.