Skills and agent profiles

The PopCraft agent ships with a set of skills — short instruction sheets it pulls in when a job matches one — and a set of agent profiles, the personas it hands work to when it splits a job up. You can add your own.

There are two ways to do that:

• In the app. The agent panel has an editor for both. Whatever you write there is stored in the browser and follows you around that browser or desktop install.
• As files. In the desktop app, drop a markdown file into the skills/ or agents/ folder. This is the one to reach for when you want to keep them in a git repo, share them with a team, or edit them in your own editor.

1. 1.Open the agent panel, then Manage0:00
2. 2.Skills and profiles: duplicate one to make it yours0:03

Description

A launch post in the editor. The Agent rail button opens the agent panel, and Manage opens the editor for skills and agent profiles: the built-in skills are listed (Fill content, Auto layout, Recolor, Motion design…), each an instruction sheet the agent pulls in when a job matches, with Duplicate to make your own version; Agent profiles is the other tab.

This section is about the files. The format is the same on both sides, so anything you write in the panel can be moved into a file and back.

• File format — the frontmatter, the body, and a complete example of each.
• Tool names — every name a tools: allowlist may use.

Where the folders live

The desktop app keeps them beside the plugins, fonts and themes folders, under its app data directory:

Inside it:

skills/
  brand-audit.md
  export-checklist.md
agents/
  proofreader.md
  spacing-critic.md

Both folders are created for you the first time the app starts, and both are flat — files in a subfolder are ignored, which is what makes "the file name is the id" a rule you can rely on. Only .md and .mdx files are read, and a file whose name starts with . is skipped, so .notes.md is a good place to park something you don't want loaded.

The app watches both folders. Save a file and the change is picked up within a moment, with no restart: the skill list in the panel updates, and the next thing you ask the agent uses the new version.

In a browser

A web page can't read a folder on your machine, so the file-based path simply isn't there — PopCraft on the web falls back to the built-in skills and profiles plus whatever you wrote in the panel. Nothing errors and nothing is missing except the files. If you want the same skill in both places, write it in the panel; if you want it in version control, use a file and open that document in the desktop app.

Which one wins

Skills and profiles are matched by id, and when two have the same id only one survives:

built-in   <   file   <   written in the panel

So a file called recolor.md with id: recolor replaces the built-in recolor skill everywhere — in the agent's index, in read_skill, in the panel. And if you then write a skill with that same id in the panel, the panel one wins over the file.

Shadowing is never silent: the surviving item is labelled in the panel with where it came from and what it pushed aside ("file · shadows built-in"), so you are never left wondering which copy is running. If you want a variant rather than a replacement, give it a different id.

If two files claim the same id, the later one alphabetically wins — that is a mistake rather than a feature, so the panel shows it the same way.

What a file can't do

A file on disk is not a permission. This matters if you ever pull someone else's skills into your folder:

• A tools: allowlist only ever narrows what the agent may call. It cannot add a tool, and a name that isn't a real tool is a load error rather than a silent grant.
• The tools that ask you to confirm before they run — deleting a file, publishing to a library, running a plugin — cannot be named in an allowlist at all. They aren't in the tool name list, so a file that names one fails to load.
• readOnly on an agent profile only tightens. Setting readOnly: true forces a profile to look and never touch; setting readOnly: false does not let it edit a document that is open read-only (a version-history preview, or a file you're in as a viewer), or override a run the agent already decided to keep read-only.
• A profile can never spawn further profiles, whatever its instructions say.

When a file doesn't load

Every failure is reported as a toast naming the file and what was wrong with it, for example:

Could not load skills/brand-audit.md: tools names "get_nodes", which is not a tool. Valid names: align, apply_auto_layout, …

A few things worth knowing when you're chasing one down:

• One bad file never takes the folder down. The other files load normally; only the broken one is missing.
• A broken file is reported once. It isn't retried until you change it, so if you fix it and see no new toast, that's the fix landing. If you want to force a re-read of everything, switch away from the PopCraft window and back — it re-syncs on focus.
• A file that used to work and now doesn't is dropped, not left running on its last good version. If a skill vanishes from the panel after an edit, look for the toast.
• Check the id. If your file loaded but the agent is still doing the old thing, you may have collided with a built-in id — the panel's source label will say so.
• Check the frontmatter. Unknown fields are an error, not a shrug: a typo like whenUse: is reported rather than ignored, which is usually how a "why is this being skipped?" turns out.
• Make sure you're editing the file the app is reading — the paths in the table above are the only ones it looks at, and a copy in your Documents folder will never load.