PluginDataSkill Model

PluginDataSkill model for storing SKILL.md-based plugin data configuration.

class smarter.apps.plugin.models.plugin_data_skill.PluginDataSkill(*args, **kwargs)

Bases: PluginDataBase

Stores the configuration and content of a Smarter plugin based on the.

SKILL.md standard.

This model is used for plugins that expose a “skill”: a self-contained Markdown document with a YAML frontmatter header describing the skill (name, description, and optionally license and allowed-tools), followed by a Markdown body containing the instructions the LLM should follow when the skill is invoked. Skills may also reference bundled resources (scripts, references, assets) that ship alongside the SKILL.md file.

PluginDataSkill provides methods for:

• Parsing skill_document into its YAML frontmatter and Markdown body.

• Validating that the frontmatter conforms to the SKILL.md spec (i.e. contains the required name and description keys).

• Returning sanitized skill data (name, description, instructions, allowed tools, license, and bundled resources) for use in LLM prompts.

• Extracting and caching the set of top-level keys present in the parsed frontmatter.

This model is a concrete subclass of PluginDataBase, and is referenced by PluginMeta to provide the data payload for skill-type plugins. It is also used in conjunction with PluginSelector and PluginPrompt to enable full plugin lifecycle management.

Typical use cases include plugins that teach the LLM a repeatable procedure, workflow, or domain-specific technique – for example, “how to fill out this PDF form” or “how to generate a pptx deck” – without requiring a remote API or SQL connection.

See also:

• PluginDataBase

• PluginDataStatic

• PluginDataSql

• PluginMeta

Parameters:

• id (Unknown) – Primary key: ID

• created_at (Unknown) – Created at

• updated_at (Unknown) – Updated at

• description (Unknown) – Description. A brief description of what this plugin returns. Be verbose, but not too verbose.

• parameters (Unknown) – Parameters. A JSON dict containing parameter names and data types. Example: {‘required’: [], ‘properties’: {‘max_cost’: {‘type’: ‘float’, ‘description’: ‘the maximum cost that a student is willing to pay for a course.’}, ‘description’: {‘enum’: [‘AI’, ‘mobile’, ‘web’, ‘database’, ‘network’, ‘neural networks’], ‘type’: ‘string’, ‘description’: ‘areas of specialization for courses in the catalogue.’}}}

• test_values (Unknown) – Test values. A JSON dict containing test values for each parameter. Example: {‘city’: ‘San Francisco’}

• skill_document (Unknown) –

  Skill document. The raw contents of the SKILL.md file for this plugin: a YAML frontmatter block (name, description, and optionally license and allowed-tools) followed by a Markdown body containing the instructions returned to the LLM when this plugin is invoked by the user prompt.

  The raw SKILL.md document (frontmatter + Markdown body) that this plugin returns to the LLM.

• metadata (Unknown) –

  Metadata. Parsed YAML frontmatter from skill_document (name, description, license, allowed-tools, and any additional custom keys).

  Cached, parsed representation of the YAML frontmatter block.

  Repopulated on every save().

• allowed_tools (Unknown) –

  Allowed tools. Optional list of tool names this skill is permitted to invoke, mirroring the SKILL.md ‘allowed-tools’ frontmatter key.

  Denormalized copy of the frontmatter’s allowed-tools list, kept in sync on save() for efficient querying.

• resources (Unknown) –

  Resources. Optional list of bundled resource file references (e.g. scripts/, references/, assets/ paths) that accompany this skill, expressed as relative paths.

  Relative paths to any bundled files (scripts, references, assets) shipped alongside this skill.

Relationship fields:

Parameters:

• plugin (Unknown) – Plugin (related name: plugin_data_base_plugin)

• plugindatabase_ptr (Unknown) – Primary key: Plugindatabase ptr (related name: plugindataskill)

exception DoesNotExist

Bases: DoesNotExist

exception MultipleObjectsReturned

Bases: MultipleObjectsReturned

exception NotUpdated

Bases: NotUpdated

allowed_tools

JSONField

Allowed tools. Optional list of tool names this skill is permitted to invoke, mirroring the SKILL.md ‘allowed-tools’ frontmatter key.

Denormalized copy of the frontmatter’s allowed-tools list, kept in sync on save() for efficient querying.

Type:

Type

data(params=None)

Return the skill document as a structured dictionary of frontmatter + instructions.

Unlike sanitized_return_data(), this returns the untruncated body and the full, unfiltered frontmatter mapping (including any custom keys beyond the standard SKILL.md fields).

Parameters:

params (Optional[dict]) – Optional parameters for future extensibility (currently unused).

Returns:

A dict with frontmatter and instructions keys, or None on failure.

Return type:

Optional[dict]

classmethod get_cached_data_by_plugin(plugin, invalidate=False)

Return a single instance of PluginDataSkill by plugin.

This method caches the results to improve performance.

Parameters:

plugin (PluginMeta) – The plugin whose data should be retrieved.

Returns:

A PluginDataSkill instance if found, otherwise None.

Return type:

Optional[PluginDataSkill]

classmethod get_cached_object(*args, invalidate=False, pk=None, plugin=None, **kwargs)

Retrieve a model instance by primary key, using caching to.

optimize performance. This method is selectively overridden in models that inherit from MetaDataModel to provide class-specific function parameters.

Example usage:

# Retrieve by primary key
instance = MyModel.get_cached_object(pk=1)

Parameters:

• invalidate (Optional[bool]) – If True, invalidate the cache for this query before retrieving the object.

• pk (Optional[int]) – The primary key of the model instance to retrieve.

• plugin (Optional[PluginMeta]) – The PluginMeta instance associated with the data to retrieve.

Returns:

The model instance if found, otherwise None.

Return type:

Optional[PluginDataBase]

metadata

JSONField

Metadata. Parsed YAML frontmatter from skill_document (name, description, license, allowed-tools, and any additional custom keys).

Cached, parsed representation of the YAML frontmatter block.

Repopulated on every save().

Type:

Type

static parse_skill_document(skill_document)

Split a SKILL.md document into its parsed YAML frontmatter and Markdown body.

Parameters:

skill_document (str) – The raw SKILL.md file contents.

Returns:

A tuple of (frontmatter dict, body markdown string).

Return type:

tuple[dict[str, Any], str]

Raises:

SmarterValueError – If the document has no frontmatter block, or the frontmatter is not valid YAML, or does not parse to a dict.

plugindatabase_ptr

OneToOneField to PluginDataBase

Primary key: Plugindatabase ptr (related name: plugindataskill)

Type:

Type

plugindatabase_ptr_id

Internal field, use plugindatabase_ptr instead.

resources

JSONField

Resources. Optional list of bundled resource file references (e.g. scripts/, references/, assets/ paths) that accompany this skill, expressed as relative paths.

Relative paths to any bundled files (scripts, references, assets) shipped alongside this skill.

Type:

Type

property return_data_keys: list[str] | None

Return all top-level keys present in the parsed skill_document frontmatter.

Returns:

A list of frontmatter keys (e.g. ['name', 'description', 'license']).

Return type:

Optional[list[str]]

Raises:

SmarterValueError – If skill_document cannot be parsed.

Example:

# If skill_document frontmatter is:
# ---
# name: pdf-form-filler
# description: Fill out a PDF form given field values.
# allowed-tools: [bash, view]
# ---
return_data_keys  # ['name', 'description', 'allowed-tools']

sanitized_return_data(params=None)

Return the skill data for this plugin as a dictionary suitable for the LLM.

This returns the parsed frontmatter fields (name, description, license, allowed-tools) plus the Markdown instructions body and any bundled resource references. The instructions body is truncated to smarter_settings.plugin_max_data_results characters if it exceeds that length, to bound prompt size.

Parameters:

params (Optional[dict]) – Optional parameters for future extensibility (currently unused).

Returns:

The sanitized skill data.

Return type:

Optional[dict]

Raises:

SmarterValueError – If skill_document cannot be parsed.

save(*args, **kwargs)

Override the save method to parse/validate skill_document and sync derived fields.

skill_document

TextField

Skill document. The raw contents of the SKILL.md file for this plugin: a YAML frontmatter block (name, description, and optionally license and allowed-tools) followed by a Markdown body containing the instructions returned to the LLM when this plugin is invoked by the user prompt.

The raw SKILL.md document (frontmatter + Markdown body) that this plugin returns to the LLM.

Type:

Type

validate()

Validate the model.

Attention

Intended to be overridden in subclasses to provide custom validation logic.

Return type:

bool

validate_frontmatter()

Validate that skill_document parses correctly and its frontmatter.

contains the required SKILL.md keys.

Returns:

The parsed frontmatter dict.

Return type:

dict[str, Any]

Raises:

SmarterValueError – If required keys are missing, or allowed-tools is present but not a list of strings.