rizzforms

Create forms, configure webhook delivery, manage submissions, and generate embed HTML using the RizzForms API and bundled CLI. Use this skill whenever the us...

Security Scan

The skill's README describes a bundled CLI and requires an admin API key, but the package metadata/manifest does not include the CLI or declare the API key—these mismatches are concerning and should be resolved before trusting the skill.

Purpose & Capability

The skill claims to bundle a CLI for managing RizzForms and to perform form/webhook management via the RizzForms API, which is coherent with the description. However, the file manifest does not include the promised CLI at scripts/rizzforms (only SKILL.md and references/api.md are present). Additionally, the SKILL.md expects an admin API key and a config file path (~/.config/rizzforms/config) even though the registry metadata lists no required environment variables or config paths. The absence of the actual CLI binary/script in the bundle is a material inconsistency.

Instruction Scope

The runtime instructions tell the agent to run a bundled CLI, to chmod +x <skill-path>/scripts/rizzforms, and to read/set RIZZFORMS_API_KEY or ~/.config/rizzforms/config. Those instructions imply reading/writing environment and filesystem state and executing a script — but the package does not include that script. The instructions also direct the user to obtain an admin-scoped API key and to store signing secrets; those actions are appropriate for the stated functionality but grant wide access (create/update/delete forms, read submissions) and therefore require explicit declaration and care.

Install Mechanism

This is an instruction-only skill with no install spec and no bundled code in the manifest. That minimizes installation risk. The SKILL.md references a bundled CLI, but since it is absent there is no actual install to evaluate. If a future version includes a download/extract/install step, it should be inspected for source and host provenance.

Credentials

The skill needs an API key with the admin role (RIZZFORMS_API_KEY with prefix frk_). For full form creation and webhook management this is proportionate, but the registry metadata failed to declare this required environment variable. Requesting an admin-scoped key is sensitive — least-privilege (e.g., readonly or limited-scope keys) should be preferred when possible. The SKILL.md also references storing signing_secret, which is expected for webhook verification but must be protected.

Persistence & Privilege

The skill does not request always:true and does not declare any system-wide configuration changes. Instructions involve using an API key and possibly writing a config file under the user's home directory; that is normal for API clients but should be performed only after verifying the client code. Autonomous invocation is allowed by default (platform default) but is not combined with other high-privilege flags here.

What to consider before installing

Do not provide an admin API key or run any CLI until you verify where the CLI code actually comes from. Specific recommended steps: 1) Confirm the skill bundle includes the script at scripts/rizzforms before running chmod or executing it; if it is missing, ask the publisher why or obtain the CLI only from the official RizzForms release. 2) Prefer creating a least-privilege API key (readonly or custom-scoped) for evaluation instead of an admin key; only use an admin key if absolutely necessary and you trust the code. 3) If you get the CLI, inspect its contents (source) for unexpected network endpoints, telemetry, or attempts to read unrelated files. 4) Verify the domain names (forms.rizzness.com, www.rizzness.com) and the SSL/TLS certificates are legitimate. 5) Treat signing_secret and API keys like secrets — store them securely and rotate them if exposed. If the publisher cannot explain the missing CLI or provide source code for inspection, do not install or run the skill.

RizzForms — Form Backend Skill

Create forms that collect submissions and deliver them via webhook — no server code required. RizzForms handles storage, spam filtering, and delivery.

Bundled CLI

This skill includes a CLI at scripts/rizzforms. Use it instead of writing raw curl commands — it handles authentication, pretty-prints JSON, and has commands for every API operation.

# Make sure it's executable
chmod +x <skill-path>/scripts/rizzforms

# Set the API key (or run `rizzforms config` interactively)
export RIZZFORMS_API_KEY="frk_..."

# Now use it
<skill-path>/scripts/rizzforms forms
<skill-path>/scripts/rizzforms forms:create "Contact Form"

Run <skill-path>/scripts/rizzforms help for the full command list.

Prerequisites

You need a RizzForms API key with the admin role (prefix frk_).

Check for an API key: Look for RIZZFORMS_API_KEY in the environment or ~/.config/rizzforms/config.

If no API key exists:

1. Sign up at https://forms.rizzness.com/signup
2. Go to Account Settings > API Keys > Create API Key (select Admin role)
3. Set it: export RIZZFORMS_API_KEY="frk_..."

Important: Two Subdomains

RizzForms uses two subdomains — using the wrong one is a common mistake:

Subdomain	Purpose
forms.rizzness.com	Form submissions only (/f/ and /json/ routes)
www.rizzness.com	API, dashboard, docs (/api/ routes)

HTML form action and JSON submission URLs use forms.rizzness.com. API management calls use www.rizzness.com. The CLI handles this automatically.

Workflow

Step 1: Create a form

<skill-path>/scripts/rizzforms forms:create "Contact Form"

The response includes endpoint_token, submission_url, json_url, embed_html, and examples with ready-to-use curl commands.

Save the endpoint_token — you need it for every subsequent step.

Step 2: Configure a webhook (optional)

If the user wants submissions delivered to an external URL:

<skill-path>/scripts/rizzforms plugins:create <endpoint_token> "https://their-server.com/webhook"

Requirements:

• URL must use HTTPS
• URL must not resolve to a private/reserved IP
• Save the signing_secret from the response — it's shown only once

The webhook receives a JSON POST on each submission:

{
  "id": 12345,
  "created_at": "2026-03-22T12:00:00Z",
  "form_id": "abc123",
  "form_name": "Contact Form",
  "ip": "203.0.113.42",
  "user_agent": "Mozilla/5.0...",
  "referrer": "https://yoursite.com/contact",
  "data": {
    "name": "Jane Doe",
    "email": "[e-mail]",
    "message": "Hello!"
  }
}

Each webhook includes an X-RizzForms-Signature header (HMAC-SHA256 of the body using the signing secret). See references/api.md for verification examples in Ruby, Node.js, and Python.

Step 3: Test the pipeline

<skill-path>/scripts/rizzforms test <endpoint_token>

This sends a test submission with ?test=true for synchronous delivery results. You can also pass custom JSON:

<skill-path>/scripts/rizzforms test <endpoint_token> '{"name": "Test", "email": "[e-mail]"}'

If the webhook returns non-2xx or times out, the delivery status will be "failed" with an error message.

Step 4: Generate HTML

Use the embed_html from the form creation response, or build a custom form. Always include the hidden honeypot field _hp for spam protection.

<form action="https://forms.rizzness.com/f/{endpoint_token}" method="POST">
  <label for="name">Name</label>
  <input type="text" id="name" name="name" required>

  <label for="email">Email</label>
  <input type="email" id="email" name="email" required>

  <label for="message">Message</label>
  <textarea id="message" name="message" required></textarea>

  <!-- Honeypot — keep hidden, critical for spam protection -->
  <input type="text" name="_hp" style="display:none" tabindex="-1" autocomplete="off">

  <button type="submit">Send</button>
</form>

RizzForms captures ALL form fields — there is no fixed schema. Add phone, company, budget, file upload, radio buttons, checkboxes — whatever is needed.

Match the user's CSS framework:

• Tailwind CSS: utility classes (class="block w-full rounded-md border...")
• Bootstrap 5: Bootstrap classes (class="form-control", class="mb-3")
• Plain CSS: semantic HTML, no framework classes

Step 5: Install in the user's project

Place the HTML form in the appropriate location in the codebase. The form action URL points to RizzForms — no server-side code is needed.

For server-side/AJAX submissions, POST JSON to https://forms.rizzness.com/json/{endpoint_token} instead.

Managing Existing Forms

# List all forms
<skill-path>/scripts/rizzforms forms

# Show form details (includes submission count, spam rate, plugin status)
<skill-path>/scripts/rizzforms forms:show <token>

# Update a form
<skill-path>/scripts/rizzforms forms:update <token> --name "New Name"
<skill-path>/scripts/rizzforms forms:update <token> --redirect "https://site.com/thanks"
<skill-path>/scripts/rizzforms forms:update <token> --active false

# List/manage plugins
<skill-path>/scripts/rizzforms plugins <token>
<skill-path>/scripts/rizzforms plugins:delete <token> <plugin_id>
<skill-path>/scripts/rizzforms plugins:rotate <token> <plugin_id>

Viewing Submissions

# Recent submissions (default: last 24h)
<skill-path>/scripts/rizzforms submissions

# Filter by form and time range
<skill-path>/scripts/rizzforms submissions --form <token> --range 7d

# Search submissions
<skill-path>/scripts/rizzforms submissions --search "[e-mail]"

# View a specific submission
<skill-path>/scripts/rizzforms submissions:show <id>

# View spam
<skill-path>/scripts/rizzforms spam --form <token>

Spam Prevention

RizzForms has three layers of spam protection:

1. Honeypot fields — Hidden _hp (or _gotcha) field. Bots fill it, submission gets marked as spam. Always include this in your HTML.
2. Turnstile CAPTCHA — Cloudflare Turnstile invisible challenge, enabled in the dashboard.
3. Rate limiting — 60 submissions per minute per IP per form. Returns HTTP 429 when exceeded.

Special Fields

These field names get automatic normalization (stored in special_normalized):

Field	Normalization
email	Whitespace trimmed
firstName, lastName	Whitespace trimmed
name	Auto-computed from firstName + lastName if both present
tags	CSV string converted to array
priority	Lowercased, validated: low/medium/high/urgent
urgent	Coerced to boolean
_optin	Coerced to boolean (marketing opt-in)

All fields are always stored as-is in payload_json regardless of normalization.

Error Handling

All errors return {"ok": false, "error": "code", "message": "..."}.

Status	Error	Meaning
401	invalid_api_key	API key missing, invalid, or expired
403	forbidden	Key lacks required permission
404	not_found	Form/plugin not found or wrong account
404	not_active	Form is deactivated — reactivate with --active true
422	unsupported_plugin	Only "webhook" type supported via API
422	invalid_config	Webhook URL invalid, not HTTPS, or private IP
503	service_unavailable	Temporary — retry shortly

Full API Reference

For complete endpoint details, webhook signing verification code, and framework quick-starts (Next.js, Astro, Hugo), see references/api.md.