SDF Custom Skill agentskill XML: SKILL.md Paths and Deployment Validation

An SDF custom skill agentskill XML definition must be deployed with its referenced content folder containing SKILL.md. To pass SuiteCloud deployment validation, align the XML metadata, SKILL.md front matter, instruction body, and the folder reference required for the project type.

TL;DR: An SDF custom skill consists of an agentskill XML definition and a content folder containing SKILL.md. The XML <name> and <description> must exactly match the SKILL.md front-matter values, including capitalization. Use [/SuiteApps/<application_id>/<skill_folder>/] for SuiteApp projects and [/Skills/<skill_folder>/] for account customization projects (ACPs).

Key takeaways

Include both the agentskill XML definition and its referenced folder containing SKILL.md in the project.
Match XML <name> and <description> exactly to the corresponding SKILL.md front-matter values, including capitalization.
Use the project-type-specific <skillfolder> format: [/SuiteApps/<application_id>/<skill_folder>/] for SuiteApps or [/Skills/<skill_folder>/] for ACPs.
SKILL.md needs a nonempty Markdown instruction body.
Only users with the Administrator role can set <ispublic> to T.

Prerequisites

Before packaging a skill, confirm that the SuiteCloud project includes both the XML definition and the referenced content folder. The folder, SKILL.md, matching front matter, and instructions must be present together when the project is validated and deployed.

Also identify the project type: SuiteApp or account customization project (ACP). That choice determines both the content location and the <skillfolder> reference. For local setup, review SuiteCloud CLI prerequisites for development and SuiteCloud CLI installation for NetSuite 2026.2. SuiteApp teams can also review the SuiteApp project properties guide before using an application ID in a skill folder reference.

The 2026.2 update added Skills as XML Definitions for defining and deploying custom skills through SuiteCloud Development Framework (SDF).

SDF custom skill components: agentskill XML and SKILL.md

Each custom skill has two connected components:

An agentskill XML definition.
A skill content folder containing a file named SKILL.md.

The XML <skillfolder> element connects the definition to the content. Its reference must identify an existing folder in the SuiteCloud project. That folder must contain SKILL.md at validation and deployment time.

SKILL.md supplies front-matter name and description values that correspond to the XML definition. It must also contain a nonempty Markdown instruction body. A valid package therefore needs the XML, the referenced folder, the required file, matching metadata, and instructions.

Which XML items define an SDF custom skill?

XML item	Purpose and validation significance
`scriptid` attribute	Identifies the `agentskill` SDF custom object.
`<name>`	Specifies the skill name. It must exactly match the `name` value in the `SKILL.md` front matter, including capitalization.
`<description>`	Specifies the skill description. It must exactly match the `description` value in the `SKILL.md` front matter, including capitalization.
`<skillfolder>`	Specifies the File Cabinet folder containing `SKILL.md`.
`<isinactive>`	Indicates whether the skill is inactive. Use `F` for an active skill.
`<ispublic>`	Indicates whether the skill is public and available for other users to invoke. Only users with the Administrator role can set this value to `T`.

Treat <name>, <description>, and <skillfolder> as a coordinated set. The first two values are compared with the SKILL.md front matter, and the folder reference identifies where the required Markdown file belongs.

How to structure the agentskill XML and SKILL.md

Use the following packaging sequence:

Identify the project type. Determine whether the project is a SuiteApp or an ACP. This controls the skill content location and <skillfolder> format.
Create the content folder in the required location. SuiteApp content belongs in the SuiteApp directory. ACP content belongs in the Skills directory at the File Cabinet root.
Add SKILL.md. The referenced folder must include a file named exactly SKILL.md, with matching name and description front matter and a nonempty Markdown instruction body.
Create the XML definition. Include the scriptid attribute, <name>, <description>, <skillfolder>, <isinactive>, and <ispublic> elements used by the definition.
Copy metadata exactly. The XML <name> must equal the front-matter name, and XML <description> must equal the front-matter description. Capitalization must match.
Set status values intentionally. <isinactive>F</isinactive> marks a skill as active. <ispublic>F</ispublic> does not mark it as public; setting <ispublic> to T requires the Administrator role.
Validate the complete project state. Include the XML and referenced content folder together before validation and deployment.

Where should skillfolder point in SuiteApp and ACP projects?

The required location and <skillfolder> reference depend on the project type.

Project type	Skill content location	`<skillfolder>` reference
SuiteApp project	The SuiteApp directory	`[/SuiteApps/<application_id>/<skill_folder>/]`
Account customization project (ACP)	The `Skills` directory at the File Cabinet root	`[/Skills/<skill_folder>/]`

For a SuiteApp, replace <application_id> with the project application ID and <skill_folder> with the folder that contains SKILL.md. The SuiteApp Application ID structure provides project-level context for that identifier.

For an ACP, place the content under the File Cabinet root Skills directory and use the [/Skills/<skill_folder>/] pattern. In either project type, the referenced folder must exist in the project and contain SKILL.md.

Active SuiteApp skill example

This SuiteApp example defines an active, non-public custom skill. Its <skillfolder> reference is [/SuiteApps/com.netsuite.sdfskills/simple-test-skill/].

<agentskill scriptid="customskill_simple_test_skill">
    <name>simple-test-skill</name>
    <description>Tiny deterministic test skill for confirming skill discovery and invocation.</description>
    <skillfolder>[/SuiteApps/com.netsuite.sdfskills/simple-test-skill/]</skillfolder>
    <isinactive>F</isinactive>
    <ispublic>F</ispublic>
</agentskill>

The referenced folder must contain SKILL.md. Its front-matter name must be simple-test-skill, and its front-matter description must be Tiny deterministic test skill for confirming skill discovery and invocation. The file must also include a nonempty Markdown instruction body.

In this example, <isinactive>F</isinactive> marks the skill as active. <ispublic>F</ispublic> does not mark it as public. An ACP can use the same metadata-matching approach, but its content belongs under Skills and uses [/Skills/<skill_folder>/].

What does deployment validate?

SuiteCloud project deployment validates the definition and its content as one package. Before deployment, confirm all four conditions:

The <skillfolder> reference identifies an existing folder in the project.
The folder contains SKILL.md.
XML <name> and <description> exactly match the corresponding SKILL.md front-matter values.
SKILL.md contains the skill instructions.

This means that an XML definition alone is incomplete. The referenced folder, required file, matching metadata, and instructions must all be present at validation and deployment time. Teams can incorporate these checks into their SuiteCloud Developer Assistant workflow.

Common packaging checks

Check	What to verify	Correction
Folder reference	`<skillfolder>` follows the project-type pattern and identifies a project folder.	Use `[/SuiteApps/<application_id>/<skill_folder>/]` for SuiteApps or `[/Skills/<skill_folder>/]` for ACPs.
Required file	The referenced folder contains `SKILL.md`.	Add a file named exactly `SKILL.md` to that folder.
Name match	XML `<name>` equals front-matter `name`.	Copy the value exactly, including capitalization.
Description match	XML `<description>` equals front-matter `description`.	Align the complete value exactly, including capitalization.
Instructions	`SKILL.md` has a nonempty Markdown instruction body.	Add the skill instructions to the Markdown file.
Public setting	`<ispublic>` is set appropriately for the intended skill visibility.	Retain `F` for a non-public skill; only an Administrator can set `T`.

The scriptid attribute identifies the agentskill object, but it does not replace the required XML-to-front-matter matching for <name> and <description>.

Final validation checklist

Before running the normal SuiteCloud project validation and deployment workflow, inspect the XML and SKILL.md together:

Confirm both <name> values are exactly the same.
Confirm both <description> values are exactly the same.
Follow <skillfolder> to an existing project folder.
Confirm that folder includes SKILL.md.
Confirm SKILL.md includes skill instructions.
Confirm <isinactive>F</isinactive> if the skill should be active.
Confirm <ispublic>F</ispublic> if the skill should not be public.

FAQ

Which XML elements must exactly match SKILL.md front matter?

The <name> and <description> elements must exactly match the corresponding name and description values in SKILL.md, including capitalization.

How should skillfolder be formatted for SuiteApps and ACPs?

Use [/SuiteApps/<application_id>/<skill_folder>/] for SuiteApp projects and [/Skills/<skill_folder>/] for ACPs. The referenced folder must exist in the project.

What two components must an SDF custom skill include?

It must include an agentskill XML definition and a skill content folder containing SKILL.md.

What does deployment validate for a custom skill?

Deployment validates the referenced folder, the presence of SKILL.md, exact XML-to-front-matter matches for name and description, and skill instructions in the Markdown file.

Who can set ispublic to T?

Only users with the Administrator role can set <ispublic> to T.