# Sn Sdk Fluent

> Use when working with ServiceNow Fluent DSL (.now.ts files) — generating, reviewing, or explaining metadata definitions for tables, ACLs, business rules, UI pages, client scripts, script includes, flows, service portal widgets, and other ServiceNow metadata types. Covers all 6 column types, all $id-required types, and scope prefix reading from now.config.json.

- **Type:** Skill
- **Install:** `agentstack add skill-aatrey882-servicenow-agent-skills-sn-sdk-fluent`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [aatrey882](https://agentstack.voostack.com/s/aatrey882)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [aatrey882](https://github.com/aatrey882)
- **Source:** https://github.com/aatrey882/servicenow-agent-skills/tree/main/sn-sdk-fluent

## Install

```sh
agentstack add skill-aatrey882-servicenow-agent-skills-sn-sdk-fluent
```

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

## About

# ServiceNow Fluent SDK

ServiceNow Fluent is a TypeScript-based DSL for defining application metadata (sys_metadata) as code. Files use the `.now.ts` extension and are compiled with `now-sdk build`. Two-way sync keeps metadata in sync between code and the ServiceNow instance. All Fluent APIs import from `@servicenow/sdk/core`.

## Reference Files

Read these files when you need them — do not pre-load all references at session start. Paths are relative to the skill root (the directory containing this `SKILL.md` file).

| File | When to read |
|------|--------------|
| `references/metadata-types.md` | When generating or reviewing any Fluent metadata type |
| `references/column-types.md` | When working with Table column definitions (StringColumn, IntegerColumn, etc.) |
| `references/now-globals.md` | When using Now.ID, Now.include, or the script tagged template literal |
| `references/getting-started.md` | When helping someone install the SDK or create their first project |
| `references/project-structure.md` | When explaining file layout, now.config.json, or scope prefix rules |
| `references/gotchas.md` | When encountering auth errors, XML/source conflicts, --reinstall questions, Now.ID or Now.ref usage, -now: import prefix issues, JS module sync questions, or npx vs now-sdk confusion |
| `references/cli-reference.md` | When running or explaining build, install, transform, clean, or pack commands |

## Example Assets

Use these as structural templates — only read the example that matches your target type, do not pre-load all examples:

| File | Metadata type |
|------|--------------|
| `assets/examples/table.now.ts` | Table (all 6 column types) |
| `assets/examples/acl.now.ts` | Acl + Role |
| `assets/examples/business-rule.now.ts` | BusinessRule |
| `assets/examples/client-script.now.ts` | ClientScript (.client.js extension) |
| `assets/examples/script-include.now.ts` | ScriptInclude |
| `assets/examples/ui-action.now.ts` | UiAction |
| `assets/examples/ui-page.now.ts` | UiPage |
| `assets/examples/rest-api.now.ts` | RestApi |
| `assets/examples/flow.now.ts` | Flow (trigger + action) |

## Hard Rules

1. **Read before writing.** Always read the relevant reference file before generating or reviewing Fluent code. Do not write from memory.
2. **Only use documented APIs.** Only use field names and options that appear in the reference files. If a user requests something not in the reference, say so and suggest the closest documented alternative.
3. **Never use GlideRecord.** GlideRecord is the legacy scripting API. Fluent is the correct pattern for SDK applications.
4. **Never omit `Now.ID` where required.** Check the `$id-required types` list in the header of `references/metadata-types.md` before writing any metadata type.
5. **Always import from `@servicenow/sdk/core`.** Never from `@servicenow/sdk` — the `/core` subpath is required.
6. **Scope prefix comes from `now.config.json`.** NEVER invent or assume the scope prefix. Read `references/project-structure.md` for the schema. If `now.config.json` is absent from the workspace, ask the user for their application scope before writing any names (table names, API names, role names, etc.).

7. **Never run install without a successful build first.** `now-sdk install` deploys whatever is in `dist/`. Running it without a prior `now-sdk build` silently pushes stale or missing artifacts. Build must complete cleanly before deploy.
8. **Always verify auth before deploying.** OAuth tokens expire silently. Run `now-sdk auth --list` and confirm the correct alias is active before every deploy.
9. **`sys_app.do` is the app record, not the running UI.** After deploy, the install output link points to the app record. The live UI URL is the `endpoint` value in the `UiPage()` call in the `.now.ts` source — e.g. `https://.service-now.com/.do`.

**ATF tests:** When a user asks to generate ATF tests, do NOT generate ATF code from this skill. ATF API surface is extensive and version-sensitive. Direct them to: `github.com/ServiceNow/sdk-examples/tree/main/test-atf-sample`

## Behavior by Task Type

### Build & Deploy

**Pre-deploy checklist — always run through this first:**
1. `now-sdk auth --list` → confirm the correct alias is marked as default
2. Ensure all `.now.ts` changes are saved and complete
3. Run build — it must succeed cleanly before proceeding

**The sequence — never skip or reorder:**
```bash
npm run build    # now-sdk build — type-check + bundle
npm run deploy   # now-sdk install — push artifacts to instance
```

**Post-deploy verification — always confirm the right version landed:**
1. Open `https://.service-now.com/sys_app.do?sys_id=` (scopeId is in `now.config.json`)
2. Confirm **version** matches what you just deployed
3. Confirm **state** is `Active`
4. If either is wrong, check `sys_app_install_log` on the instance for errors

**Finding the live UI URL after deploy:**
The install output shows a `sys_app.do` link — that is the app record, not the running UI. To get the live URL:
1. Open the `UiPage()` definition in your `.now.ts` source file
2. Read the `endpoint` value (e.g. `x_snc_myapp_portal.do`)
3. Live URL: `https://.service-now.com/.do`

**Targeting a specific instance:**
```bash
now-sdk install --auth    # override the default alias
```

**Common failures and fixes:**

| Symptom | Cause | Fix |
|---------|-------|-----|
| Auth error mid-deploy | Expired OAuth token | Re-run `now-sdk auth --add  --type oauth --alias ` to refresh |
| Install succeeds but UI shows old code | Build was skipped or stale | Re-run `npm run build` then `npm run deploy` |
| Type-check error blocks build | TypeScript error in source | Fix the error reported — do not bypass |
| Scope conflict on install | Another app owns the scope | Check `sys_app` for conflicting scope, resolve before retrying |

---

### Generating Fluent code

1. If the scope prefix, metadata type, or required fields have not been stated by the user and cannot be unambiguously determined from the workspace — gather them before writing (ask for each piece of information sequentially to avoid overwhelming the user)
2. Read `references/metadata-types.md` for the target metadata type
3. Read the matching example from `assets/examples/`
4. Write code following the example structure exactly
5. Use `Now.ID['descriptive_key']` for stable IDs; use `Now.include('./filename.ext')` for external scripts
6. Prefix table names, API names, and role names with `x_scope_` (where `scope` comes from `now.config.json`); if `now.config.json` is absent, apply Hard Rule 6

### Reviewing Fluent code

1. Read `references/metadata-types.md`
2. Check every field and option in the code against the reference
3. Flag options not in the reference as "not in reference — may be valid but verify against SDK docs"
4. Flag missing `$id` on types that require it (marked in the reference header)
5. Flag any GlideRecord usage
6. Flag imports from `@servicenow/sdk` (should be `@servicenow/sdk/core`)

### Explaining Fluent code

1. Read the relevant section of `references/metadata-types.md`
2. For each field, paraphrase the reference definition — do not explain from memory
3. For Now.ID, Now.include, or `script` tag questions, also read `references/now-globals.md`

## Source & license

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

- **Author:** [aatrey882](https://github.com/aatrey882)
- **Source:** [aatrey882/servicenow-agent-skills](https://github.com/aatrey882/servicenow-agent-skills)
- **License:** MIT

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-aatrey882-servicenow-agent-skills-sn-sdk-fluent
- Seller: https://agentstack.voostack.com/s/aatrey882
- 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%.