General Add Value Type
Developmentgeneral-add-value-typeGeneral Add Value Type is an Agent Skill for development published in the umbraco/Umbraco-CMS repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Add a new value type — a named, typed string constant that extends UmbValueTypeMap. Use when a feature needs to declare what type of value it holds so it can be referenced in collection columns or value summary manifests. Also use when a property editor needs to expose its value type for use in collection views.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/umbraco/Umbraco-CMS/blob/HEAD/src/Umbraco.Web.UI.Client/.claude/skills/general-add-value-type/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/general-add-value-type, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Add Value Type
Add a new value type constant to UmbValueTypeMap.
Foundational documentation
Read before proceeding:
- Value Type — full reference, naming convention, rules
What you need from the user
- Feature name — kebab-case (e.g.,
color-picker,user-group) - Package path — where the feature lives (e.g.,
src/packages/property-editors/color-picker/) - Value type key — the string alias:
- For a property editor: use the schema alias (e.g.,
'Umbraco.ColorPicker') - For a domain type: use
Umb.ValueType.{Entity}.{Shape}(e.g.,'Umb.ValueType.UserGroup.References')
- For a property editor: use the schema alias (e.g.,
- TypeScript type — the type of the raw value (e.g.,
string,boolean,UmbReferenceByUnique[])
Step 1: Create the constant file
File: {package-path}/value-type/constants.ts
export const UMB_{FEATURE}_VALUE_TYPE = '{value-type-key}' as const;
declare global {
interface UmbValueTypeMap {
[UMB_{FEATURE}_VALUE_TYPE]: {TValue};
}
}
Rules:
- The string value is always
as const. - The
declare globalblock is in the same file as the constant. - One constant per file — do not group multiple value types.
Property editor example
import type { UmbColorPickerPropertyEditorValue } from '../types.js';
export const UMB_COLOR_PICKER_VALUE_TYPE = 'Umbraco.ColorPicker' as const;
declare global {
interface UmbValueTypeMap {
[UMB_COLOR_PICKER_VALUE_TYPE]: UmbColorPickerPropertyEditorValue;
}
}
Domain type example
import type { UmbReferenceByUnique } from '@umbraco-cms/backoffice/models';
export const UMB_USER_GROUP_REFERENCES_VALUE_TYPE = 'Umb.ValueType.UserGroup.References' as const;
declare global {
interface UmbValueTypeMap {
[UMB_USER_GROUP_REFERENCES_VALUE_TYPE]: UmbReferenceByUnique[];
}
}
Step 2: Export from the package index
Add to the package index.ts:
export * from './value-type/constants.js';
Checklist
- Constant declared with
as const -
declare globalblock extendsUmbValueTypeMapin the same file - Key follows naming convention (schema alias for property editors,
Umb.ValueType.{Entity}.{Shape}for domain types) - TypeScript type is the correct raw value type
- One constant per file
- Constant exported from package
index.ts - Compiles:
npm run compile