# Form Manager

> >

- **Type:** Skill
- **Install:** `agentstack add skill-dusty-cjh-knowuv-skill-set-form-manager`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [dusty-cjh](https://agentstack.voostack.com/s/dusty-cjh)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [dusty-cjh](https://github.com/dusty-cjh)
- **Source:** https://github.com/dusty-cjh/knowuv-skill-set/tree/main/skills/form-manager

## Install

```sh
agentstack add skill-dusty-cjh-knowuv-skill-set-form-manager
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Form Manager Skill

This skill connects AI-generated landing pages to the KnowUV backend, enabling real customer data
collection. When a user builds a registration or lead-capture page, this skill handles all backend
interactions: submitting data, browsing submissions, and managing form lifecycle.

## Setup: Read Credentials First

**Before any API call**, read credentials from `config.ini` (in the same directory as this
SKILL.md). Parse `KEY = VALUE` lines, ignoring lines starting with `#`.

Required keys:
- `USER_ID` — the author ID sent with every form request
- `USER_TOKEN` — the API bearer token

### If credentials are missing or still placeholder

If `USER_ID` is `your_user_id_here` or `USER_TOKEN` is `your_token_here`, pause and guide the
user:

> **Setup needed before we can continue:**
>
> 1. **User ID**: Find your numeric user ID at **https://knowuv.com/admin/internal/profile** (shown as
>    "Account ID" or similar). Paste it here.
> 2. **API Token**: Visit **https://knowuv.com/JZfdJ** to get your token. Paste it here.
>
> Once you share both, I'll save them to `config.ini` so you won't need to do this again.

After the user provides them, write both to `config.ini`:
```
USER_ID = 
USER_TOKEN = 
```
Confirm: "Saved! Your credentials are ready — let's continue."

---

## Base URL & Request Format

- **Host**: `https://api.knowuv.com`
- **Path**: `/knowuv.UserInteractionService/`
- **Method**: Always `POST`
- **Content-Type**: `application/json`
- **Auth header**: `Authorization: Token `

All responses:
```json
{ "code": 0, "msg": "...",  }
```

`code = 0` is success. Non-zero means failure — show the user the `msg` in plain language.

| code | meaning |
|------|---------|
| 0 | Success |
| 1 | Invalid parameters |
| 3 | Server error — try again |
| 4 | Rate limited — wait a moment |
| 7 | Not found |
| 9 | Unauthorized — token may be wrong or expired |
| 14 | Insufficient balance |

---

## Key Concepts

### Form Name (`name`)
A concise, descriptive identifier for the form. This is how you distinguish forms from one
another — think of it like a filename. Examples: `summer-camp-2024`, `product-waitlist-q3`,
`contact-form-homepage`.

- If the user doesn't provide one, generate a sensible name from their description (e.g.,
  "summer camp registration page" → `summer-camp-registration`).
- Ask the user to confirm if unsure — the name is permanent and used in all future lookups.

### Author (`author`)
Always the `USER_ID` from `config.ini`. This is the knowuv.com account that owns all forms
created with this skill. Users never need to specify it.

### Payload
The actual form submission data — a **JSON-encoded string** (not a nested object). Example:
```json
"{\"name\": \"Alice\", \"email\": \"alice@example.com\", \"course\": \"Math\"}"
```

When generating landing pages, the HTML form's submit handler must serialize field values to
JSON and pass the result as the `payload` string.

---

## API Reference

### Submit Form

Used by landing pages (or the agent on behalf of the user) to record a customer submission.

**POST** `/knowuv.UserInteractionService/SubmitForm`

```json
{
  "name": "summer-camp-registration",
  "author": "",
  "payload": "{\"student_name\":\"Alice\",\"grade\":\"5\",\"course\":\"Math\",\"parent_phone\":\"138xxxx\"}"
}
```

Response:
```json
{ "code": 0, "msg": "OK", "submitId": "69cb65d684c94d414df5e88a" }
```

The `submitId` is a unique ID for this submission. Show it to the user as confirmation.

---

### List Forms

Show all forms owned by the user.

**POST** `/knowuv.UserInteractionService/ListForm`

```json
{
  "name": "",
  "author": "",
  "page": 1,
  "page_size": 20
}
```

Filter by providing a partial `name`. Response `data` is a list of form objects with fields:
`name`, `author`, `submit_count`, `last_submit_time`, `ctime`, `id`.

Present as a table: Form Name | Submissions | Last Activity | Created.

---

### List Submissions for a Form

Browse all customer submissions for a specific form.

**POST** `/knowuv.UserInteractionService/ListSubmitFormDetail`

```json
{
  "name": "summer-camp-registration",
  "author": "",
  "page": 1,
  "page_size": 20
}
```

Response `data` is a list of submission records: `id`, `payload` (JSON string), `user_id`,
`ctime`.

Parse each `payload` string and display as a readable table. If all submissions share the same
keys, use them as column headers. Show `ctime` as a human-readable date.

---

### Get Latest Submission

Quickly fetch the most recent submission for a form — useful for confirming a test submission
went through.

**POST** `/knowuv.UserInteractionService/GetLatestSubmitFormDetail`

```json
{
  "name": "summer-camp-registration",
  "author": "",
  "payload": ""
}
```

Response `data` is a single submission record. Parse and display the `payload` as key-value pairs.

---

### Delete a Form

Removes the form record (not its submissions — use DeleteSubmitFormDetail for those).

**POST** `/knowuv.UserInteractionService/DeleteSubmitForm`

```json
{ "id": "" }
```

The `id` comes from `ListForm`. Confirm with the user before deleting — this cannot be undone.

---

### Delete a Submission

Removes a single customer submission record.

**POST** `/knowuv.UserInteractionService/DeleteSubmitFormDetail`

```json
{ "id": "" }
```

The `id` comes from `ListSubmitFormDetail`. Confirm with the user before deleting.

---

## Workflow: Wiring a Landing Page to the Backend

When the user has an AI-generated HTML landing page and wants customer submissions to reach
the backend:

1. **Choose a form name** — ask the user or generate one from the page's purpose.
2. **Inject the submit handler** into the HTML. The handler should:
   - Collect all form field values as a plain JS object
   - Serialize it to a JSON string: `JSON.stringify(formData)`
   - POST to the SubmitForm endpoint with `name`, `author`, and `payload`
   - Show the user a success message with their `submitId`

Example fetch snippet to inject:
```javascript
async function submitToKnowUV(formData) {
  const response = await fetch('https://api.knowuv.com/knowuv.UserInteractionService/SubmitForm', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Token YOUR_TOKEN_HERE'
    },
    body: JSON.stringify({
      name: 'FORM_NAME_HERE',
      author: 'USER_ID_HERE',
      payload: JSON.stringify(formData)
    })
  });
  const result = await response.json();
  if (result.code === 0) {
    return { success: true, submitId: result.submitId };
  } else {
    throw new Error(result.msg);
  }
}
```

> **Note on token in frontend HTML**: The `USER_TOKEN` will be visible in client-side HTML.
> This is acceptable for internal/low-risk forms. For sensitive use cases, recommend the user
> proxy the submission through their own backend.

3. **Test the integration** — after the page is live, call `GetLatestSubmitFormDetail` to
   confirm a test submission arrived.
4. **View results** — direct the user to:
   `https://knowuv.com/admin/internal/form_structure`
   for a UI to browse and export all submissions.

---

## Workflow: Viewing Customer Submissions

When the user asks "who signed up?" or "show me the submissions":

1. Call `ListSubmitFormDetail` for the relevant form name.
2. Parse each `payload` field (it's a JSON string) and build a unified table.
3. If there are many fields, ask the user which columns matter most and filter accordingly.
4. For bulk export, suggest the admin panel: `https://knowuv.com/admin/internal/form_structure`

---

## Tips

- **Form name consistency**: The same `name` must be used in SubmitForm and ListSubmitFormDetail
  to link submissions to the right form. A typo creates a new, separate form.
- **Pagination**: Default to `page_size: 20`. If `total` exceeds this, offer to fetch more pages.
- **Timestamps**: `ctime` is a Unix timestamp in seconds. Convert to local time when displaying.
- **Non-technical language**: Users are often business owners, not developers. Say "customer
  submissions" not "form detail records". Say "registration form" not "SubmitForm endpoint".
- **Payload display**: Always parse and render the JSON payload as readable key-value pairs
  or a table — never dump the raw JSON string at the user.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [dusty-cjh](https://github.com/dusty-cjh)
- **Source:** [dusty-cjh/knowuv-skill-set](https://github.com/dusty-cjh/knowuv-skill-set)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-dusty-cjh-knowuv-skill-set-form-manager
- Seller: https://agentstack.voostack.com/s/dusty-cjh
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.