A skill app is an app whose version carries a SKILL.md. When a merchant installs it, the skill is added to their PlatformDTC agent: it is projected live into the agent’s workspace, with no restart and nothing for the merchant to set up. Uninstalling removes it. Build a skill app when what you are selling is know-how the agent should apply — a procedure, a playbook, a way of using the store’s data — rather than a service you host.

​
How a skill runs

The skill runs inside the merchant’s agent, with the agent’s own tools. Nothing runs on your servers: the skill works through what the agent can already do on that store. Your version still declares scopes with a justification for each, exactly like any other app. Review checks that the skill only relies on the capabilities those scopes justify: a skill that reads orders needs orders:read; a skill that edits products needs write_products. A skill whose instructions reach beyond its declared scopes is sent back.

​
Write the SKILL.md

The frontmatter must declare name and description. The description is how the agent decides when to use the skill, so say what it does and when it applies.
SKILL.md

​
Configure the app

platformdtc.app.toml
See App configuration for every key.

​
Publish

config push reads the file at [skill] path and sends its contents as the version’s skill_md; --submit sends the version to review. A public skill app also needs a complete App Store listing. To test before review, install the draft on one of your development stores and use the skill from that store’s agent.

​
How merchants install it

The merchant clicks Install and sees the consent screen: your app, the scopes it asks for and your justification for each. When they approve, the skill is added to their agent. There is no redirect to your site, because there is nothing to hand back to you.

​
Updates

When a new version is approved, installs whose granted scopes already cover the new version’s required scopes move to it straight away, and their agent gets the new SKILL.md. If the version adds a required scope, those installs move to pending_reauth instead. Until a merchant re-authorizes, their agent keeps the version they consented to; once they do, it gets the new SKILL.md. In the agent, each version is loaded as the skill app-<handle>-v<version> (the platform sets the frontmatter name to that id, so a skill app can never replace one of PlatformDTC’s own skills). Keep the handle of a skill app to 54 characters or fewer so the id fits. If the version changes scopes, the merchant sees the new scopes and justifications when they re-authorize.

​
Uninstall

Uninstalling removes the skill from the merchant’s agent.