Skills

What a skill is#

A skill is a markdown file with instructions for Claude Code. It describes one project operation: create a section, change a piece of text, publish a draft, roll a version back. It lives at .claude/skills/<skill-name>/SKILL.md. The source is the @agntcms/skills npm package, synced into the project on pnpm create agntcms-app and on update.

A skill is not code you invoke. It is an instruction Claude Code loads into context and follows when working on your files. The actual file changes are made by the agent's native tools — Read, Write, Edit, Bash. The skill is a policy on top of those tools: when you change a section, take these steps in this order, otherwise the contract breaks.

The main rule#

If there is a skill for the operation, use the skill. Do not edit content/ by hand, do not touch config.ts without agntcms-section-new (when creating a new section), do not publish drafts by moving files. Skills know the details you do not: the snapshot format, the consistency rules between config and folders, the sequence of admin API calls, the commit conventions.

This is not a prohibition — nothing stops you. It is a recommendation: the path through a skill is always cheaper than the path through hand edits, because the skill already knows how to avoid the common failures.

How to use them#

Two ways, both work.

Name the skill directly:

run /agntcms-section-new — Testimonials with quote, author, avatar.

Useful when you know exactly which skill you want and prefer to invoke it explicitly.

State the task:

create a Testimonials section with quote, author, and avatar.

Claude Code picks the skill (here, agntcms-section-new). This is the preferred path — you do not memorise skill names. Memorise tasks.

The full list#

v0.5.8 of @agntcms/skills ships 17 skills, grouped by purpose.

Project setup

• agntcms-init-from-artifact — first-run onboarding from a Claude artifact app (React/Vue/HTML with real CSS): copy source styles verbatim, map blocks to section types, populate pages.
• agntcms-structure — canonical project layout and zone rules.

Section development

• agntcms-sections — the two-step workflow for creating and registering a section.
• agntcms-section-new — scaffolding a new section from a name and field list.
• agntcms-section-validate — validating a section's structure and config registration.

Content operations
- agntcms-content-fs — working with content through native file tools; the draft/published rules.

Page lifecycle

• agntcms-create-page — creating an empty page draft.
• agntcms-delete-page — deleting a published page after explicit confirmation.
• agntcms-publish-draft — publishing a draft through the framework endpoint.
• agntcms-unpublish-page — taking a published page offline while preserving it as a draft.
• agntcms-rollback — rolling a published page or global back to a previous version.
• agntcms-rename-slug — atomically renaming a page slug across every file (pages, drafts, history).
• agntcms-reorder-sections — changing the section order in a draft.

Site-wide content
- agntcms-globals — site-wide blocks: header, footer, announcement bar.

Infrastructure

• agntcms-frozen-guard — detecting and recovering frozen-zone files.
• agntcms-git-publish — commit conventions for agent-driven edits.
• agntcms-update-skills — syncing skills with an updated @agntcms/skills version.

Skill lifecycle#

On pnpm create agntcms-app, the skills are synced from the installed @agntcms/skills version into .claude/skills/. That is a one-time copy — from there the skills live in your repository and are committed to git.

To update:

pnpm update @agntcms/skills
pnpm agntcms-skills-sync

Or say update the skills in Claude Code. The agntcms-update-skills skill walks .claude/skills/, replaces files with the new ones, shows a diff.

Skills version in lockstep with @agntcms/next — one package version covers everything. Update both at the same time, not separately.

Anti-patterns#

What not to do by hand, even when it seems faster.

• Editing JSON in content/ directly. Use agntcms-text-edit, agntcms-section-edit, agntcms-page-edit — or just state the task in plain text.
• Creating a section by editing config.ts without the section folder. TypeScript will not compile. Use agntcms-section-new.
• Publishing by moving files from drafts/ to pages/. No snapshot lands in history/; rollback becomes impossible. Use agntcms-publish-draft.
• Deleting a page with rm content/pages/<slug>.json. The history desyncs. Use agntcms-delete-page.
• Renaming a slug by renaming the file. Drafts, the published version, and history must rename atomically. Use agntcms-rename-slug.
• Hand-committing content without agntcms-git-publish. Not banned, but the skill follows the commit-message format and the snapshot order — useful for tracking through git log.

When no skill exists#

If there is no matching skill for your task, Claude Code says so explicitly. From there:

1. Rephrase. Often what you want is a combination of existing skills. State the task at a higher level; the agent will break it down.
2. Do it by hand. Genuinely non-standard work goes through plain code. Do not touch the frozen zone; user zone and content zone are yours.

Extending the skill set with your own skills is not supported in v0.5. A deliberate constraint to avoid diverging practices before v0.5 settles.