PluginDataSkill Model

PluginDataSkill model for storing Agent Skill (SKILL.md) plugin data.

Note

Experimental. The SkillPlugin was designed and coded by Claude Code (Anthropic’s Claude Opus 5.5), with Lawrence McDaniel as co-author. It is experimental, and will be documented.

class smarter.apps.plugin.models.plugin_data_skill.PluginDataSkill(*args, **kwargs)[source]

Bases: PluginDataBase

Stores an Agent Skill for a Smarter plugin, per the SKILL.md standard.

An Agent Skill is a SKILL.md document – YAML frontmatter (name, description, and optionally license, compatibility, metadata and allowed-tools) followed by Markdown instructions – plus any bundled files (scripts/, references/, assets/) that the instructions refer to by relative path.

The verbatim SKILL.md text is stored in skill_document. The parsed frontmatter and the normalized allowed-tools are derived from it on every save. Bundled files are stored in resources, keyed by path relative to the skill root.

Skills that were retrieved from a remote source, such as a GitHub repository, record the source URL and retrieval time. Their skill_document and resources are a snapshot of the remote skill, which is refreshed when the plugin manifest is applied.

PluginDataSkill is a concrete subclass of PluginDataBase, and is referenced by PluginMeta to provide the data payload for skill-type plugins.

See also

PluginDataBase
PluginMeta
smarter.apps.plugin.manifest.models.skill_plugin.document
Agent Skills specification: https://agentskills.io/specification

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 verbatim SKILL.md document (frontmatter + Markdown body).
metadata (Unknown) –
Metadata. Parsed YAML frontmatter from skill_document (name, description, license, allowed-tools, and any additional custom keys).

The complete parsed frontmatter of skill_document.

Derived 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.

The frontmatter’s allowed-tools, normalized to a list.

Derived on every save().
resources (Unknown) –
Resources. The skill’s bundled files (e.g. scripts/, references/, assets/), keyed by path relative to the skill root. A null value denotes a file whose contents are unavailable, such as a binary asset.

The skill’s bundled files, keyed by normalized path relative to the skill root.
source_url (Unknown) –
Source url. The URL from which this skill was retrieved, if it was sourced remotely, e.g. from a GitHub repository.

The skill source URL, as written in the plugin manifest, for remotely sourced skills.
source_retrieved_at (Unknown) –
Source retrieved at. When this skill was last retrieved from its source_url.

When a remotely sourced skill was last retrieved.

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.

The frontmatter’s allowed-tools, normalized to a list.

Derived on every save().

Type:: Type

data(params=None)[source]

Return the skill as a structured dictionary of frontmatter, instructions and bundled files.

Parameters:: params (dict[str, Any] | None) – Optional parameters for future extensibility (currently unused).
Returns:: A dict with frontmatter, instructions and resources keys, or None if skill_document is invalid.
Return type:: dict[str, Any] | None

property document: SkillDocument

The parsed SKILL.md document.

Raises:: SkillDocumentError – If skill_document is invalid.

find_resource(path)[source]

Find a bundled file by the path that the LLM requested.

The LLM may refer to a file exactly as SKILL.md does, which is not always its actual path. For example, Anthropic’s pdf skill refers to FORMS.md, which is bundled as forms.md. So, in order of precedence, this matches the normalized path, then the path ignoring case, then a unique file name ignoring case.

Parameters:: path (str) – The requested path, relative to the skill root.
Return type:: tuple[str, str | None]
Returns:: A tuple of the file’s path and its contents. The contents are None if unavailable.
Raises:: SmarterValueError – If no bundled file, or more than one, matches the path.

Example:

plugin_data.find_resource("./FORMS.md")
# ('forms.md', '# PDF form filling guide ...')

classmethod get_cached_data_by_plugin(plugin, invalidate=False)[source]

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:: PluginDataSkill | None

classmethod get_cached_object(*args, invalidate=False, pk=None, plugin=None, **kwargs)[source]

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 (bool | None) – If True, invalidate the cache for this query before retrieving the object.
pk (int | None) – The primary key of the model instance to retrieve.
plugin (PluginMeta | None) – The PluginMeta instance associated with the data to retrieve.

Returns:

The model instance if found, otherwise None.

Return type:

PluginDataBase | None

property instructions: str

the body of SKILL.md.

Type:: The Markdown instructions of the skill

manifest_data()[source]

Return the spec.skillData section of the plugin manifest, as the author wrote it.

Returns:: {"source": {"url": ...}} for a remotely sourced skill, otherwise {"skill": ..., "resources": ...}.
Return type:: dict[str, Any]

metadata

JSONField

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

The complete parsed frontmatter of skill_document.

Derived on every save().

Type:: Type

plugindatabase_ptr

OneToOneField to PluginDataBase

Primary key: Plugindatabase ptr (related name: plugindataskill)

Type:: Type

plugindatabase_ptr_id: Internal field, use plugindatabase_ptr instead.

property resource_paths: list[str]: The paths of the skill’s bundled files, relative to the skill root.

resources

JSONField

Resources. The skill’s bundled files (e.g. scripts/, references/, assets/), keyed by path relative to the skill root. A null value denotes a file whose contents are unavailable, such as a binary asset.

The skill’s bundled files, keyed by normalized path relative to the skill root.

Type:: Type

property return_data_keys: list[str]

Return the paths of the skill’s bundled files, which the LLM can request by name.

Returns:: The paths of the bundled files, e.g. ['references/FORMS.md', 'scripts/fill_form.py'].
Return type:: list[str]

sanitized_return_data(params=None)[source]

Return the skill, or one of its bundled files, for the LLM.

This implements the progressive disclosure of the Agent Skills specification. The skill’s name and description are presented to the LLM as the tool description. When the LLM invokes the tool, it receives the skill’s instructions, along with the paths of its bundled files. The LLM then invokes the tool again, with resource set to a path, to read a bundled file only when the instructions call for it.

Parameters:: params (dict[str, Any] | None) – The tool call arguments. If resource is present, the bundled file at that path is returned instead of the instructions.
Returns:: The skill instructions, or the bundled file.
Return type:: dict[str, Any]
Raises:: SmarterValueError – If the requested resource does not exist.

Example:

plugin_data.sanitized_return_data()
# {'name': 'pdf', 'description': '...', 'instructions': '# PDF processing ...', 'resources': ['forms.md', ...], ...}

plugin_data.sanitized_return_data({"resource": "forms.md"})
# {'name': 'pdf', 'resource': 'forms.md', 'content': '# PDF form filling ...'}

save(*args, **kwargs)[source]

Validate the skill, derive the frontmatter fields from skill_document, and save.

The tool description presented to the LLM defaults to the skill’s description, which, per the specification, describes what the skill does and when to use it.

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 verbatim SKILL.md document (frontmatter + Markdown body).

Type:: Type

source_retrieved_at

DateTimeField

Source retrieved at. When this skill was last retrieved from its source_url.

When a remotely sourced skill was last retrieved.

Type:: Type

source_url

URLField

Source url. The URL from which this skill was retrieved, if it was sourced remotely, e.g. from a GitHub repository.

The skill source URL, as written in the plugin manifest, for remotely sourced skills.

Type:: Type

validate()[source]

Validate the skill document and bundled files.

Raises:: SmarterValueError – If skill_document is not a valid SKILL.md document, or a bundled file path or its contents are invalid.
Return type:: bool