Is it safe to let an agent run skills?

Studio's skills can change your app's code and the content in your stack. Read this before you point an agent at a real stack. It covers what each kind of skill changes, what the agent waits for you to approve, and how to recover when a run stops partway.

The example is the team blog. Its Blog post content type has the UID blog_post. Its team asks an agent to build the Blog post template, import the posts from an old blog, and rename the title field to headline.

What does the agent do before it builds?

It writes a plan and stops. plan-studio-architecture lists the sections, such as Post hero, and the components in each one. It also lists the content types and the build order. Nothing is created until you approve the plan.

The skills that build won't start without a plan you approved: build-section, build-repeating-section, build-connected-template, build-freeform-template, migrate-page-to-studio and author-composition-via-api.

• Partial approval isn't approval. A reply such as "the sections look right" doesn't approve the plan, so the agent doesn't go on to create the template.
• The plan is written for whoever approves it. It says in plain words what authors can change once it's built and what stays fixed, so the approver doesn't have to be a developer.

What does each kind of skill change?

Kind of skill	What it changes	Examples
Checks and plans	Nothing in your app or stack. Some write a plan or build sheet into your repo.	analyze-project-fit, plan-studio-architecture, decompose-design
Concepts	Nothing. They explain.	understand-sections, understand-templates
Setup and registration	Your app's files: packages, SDK setup, routes and component registrations.	install-studio, setup-section-preview, register-component
Building and authoring	Compositions in your stack.	build-section, build-connected-template, author-composition-via-api
Provisioning and content	Content types, global fields, entries and assets in your stack.	provision-studio-stack, import-content, migrate-ct-schema
Shipping	What your site serves: publishing and Deploying compositions, and your host's settings.	deploy-studio-site

Changes to your app's files land in your working copy like any other edit. Review them before you commit them.

Can you re-run or undo a skill?

Two skills record their progress in a state file in your repo, so you can run them again after they stop partway. No other skill does.

Re-running an import

import-content imports the old blog's posts into Blog post:

1. It can try a sample first. Ask for a preview, and it runs against a small bundled sample without writing to your stack.
2. It waits for you to approve the plan: the field mapping, the assets and the target content type.
3. It records each post as it goes, in docs/_import-state/blog_post-import-state.json. Each post ends as imported, updated, skipped because it already exists, or failed with a reason.
4. It asks before it publishes to production.

Blog post needs a single-line text field called source_uid before the first import. Each imported entry keeps the old post's ID there, so a second run skips the posts it already imported and creates no duplicates. If Blog post doesn't have the field, add it first. provision-studio-stack can add it.

Undoing a schema change

migrate-ct-schema renames title to headline:

1. It saves the current schema to docs/_migration-state/blog_post-before.json, before it changes anything.
2. It rates the risk. Adding an optional field is safe. A rename, a removal or a change to an incompatible type is high risk.
3. It shows you a dry run and waits for your approval.
4. It makes a high-risk change in stages. It adds headline and copies each entry's title into it. It lists the sections bound to title for you to confirm, then binds them to headline. It removes title only after a cool-off period, 14 days by default, and only when you ask. It records each stage in docs/_migration-state/blog_post-migration.json.

To undo the change, ask the agent to roll back the migration. It points the bindings back to title and removes headline. Once title has been removed, its values are gone, and a rollback can't bring them back.

Both state folders sit under docs/ in your repo. Commit them to keep a record of what ran, or add them to .gitignore.

What if another skill stops partway?

Nothing records what it had already done. Before you run it again, look in Studio's Templates and Sections tabs to see what it created, so the agent doesn't build something twice.

If it doesn't work

• An import stopped partway. Run import-content again with the same inputs. It skips every post the state file records as done and tries the rest. Posts that failed keep their reason in the state file.
• A second import created duplicate posts. Blog post has no source_uid field, so the skill couldn't tell which posts it had already imported. Add the field, then delete the duplicates.