Build an AI Assistant skill

Prerequisites: Magneto Agent / AI Assistant

A skill teaches the AI Assistant your app: how it's put together, where its data lives and how to look after it. Without one, the assistant has only general knowledge to go on. With one, it can run your app's real admin tasks, such as backups, upgrades and diagnostics, the way you would.

This guide covers what a skill is, how to package and connect one, and how to write and test it. Clouve's own skills are public, so you can start from a working example.

Why build one

Customers on a paid plan who add the AI Assistant pay for it every month: Clouve's AI Assistant fee plus yours. How well the assistant knows your app is what makes it worth paying for. With a good skill, a customer can ask for a backup, an upgrade or a fix in plain words and get it done safely.

You earn your AI Assistant fee every month from each customer who pays for the AI Assistant, and it's paid out with your Developer Monthly Fee. You set the fee on Step 3 (Infrastructure & Pricing) of the submission wizard. See Pricing for how the price is put together.

What a skill is

A skill is a folder of Markdown files and shell scripts. Its entry point is SKILL.md: YAML frontmatter, then the instructions the AI Assistant follows.

---
name: blog
description: Safely operate a Blog install deployed on Clouve, including backups and restores, upgrades, user access and error diagnosis. Use when the user is running Blog or mentions blog.conf or the blog_* tables. Do not use for general PHP or MySQL questions that aren't about a Blog install.
---

# Blog skill

You look after a live Blog site with real posts and user accounts...

The frontmatter needs two fields:

• name is the skill's name, in lowercase letters, digits and hyphens. It must match the plugin's name (see Packaging).
• description says what the skill is for. The AI Assistant reads it to decide when to use the skill, so say exactly when to use it and when not to.

Clouve's own skills also set type, version and authoredAgainst, the app version the skill was written for. These are optional, but authoredAgainst helps you keep the skill current.

After the frontmatter come the instructions: what the AI Assistant is looking after, the rules it must never break, and pointers to the rest of the skill. Keep SKILL.md short and put the detail in these files and folders:

Packaging

Skills live in a Git repository with a catalog file at the root and one plugin per skill under plugins/:

blog-skills/
├── .claude-plugin/
│   └── marketplace.json        # catalog of every plugin in the repository
└── plugins/
    └── blog/
        ├── .claude-plugin/
        │   └── plugin.json     # plugin manifest
        ├── install.sh          # optional runtime hook
        └── skills/
            └── blog/
                ├── SKILL.md
                ├── learnings.md
                ├── playbooks/
                ├── reference/
                └── scripts/

The names .claude-plugin/, marketplace.json, plugins/, plugin.json and skills/ are part of the format, so use them exactly. The plugin's directory, the name in plugin.json, the name in SKILL.md and the plugin's name in the catalog must all be the same.

The catalog lists every plugin in the repository:

{
  "name": "acme",
  "description": "Acme's AI Assistant skills.",
  "owner": { "name": "Acme", "url": "https://acme.example" },
  "version": "1.0.0",
  "plugins": [
    {
      "name": "blog",
      "source": "./plugins/blog",
      "description": "Safely operate a Blog install deployed on Clouve, including backups and restores, upgrades, user access and error diagnosis. Use when ...",
      "version": "0.1.0",
      "category": "DevOps",
      "tags": ["blog", "php", "mysql"],
      "author": { "name": "Acme", "url": "https://acme.example" }
    }
  ]
}

The plugin manifest needs only the basics:

{
  "name": "blog",
  "version": "0.1.0",
  "description": "Safely operate a Blog install deployed on Clouve, including backups and restores, upgrades, user access and error diagnosis. Use when ...",
  "author": { "name": "Acme", "url": "https://acme.example" }
}

Use the same description in the catalog, the manifest and SKILL.md, and raise the plugin's version whenever you change the skill.

The optional install.sh hook

If your scripts need tools the AI Assistant doesn't come with, such as a database client, add an install.sh at the plugin's root. The AI Assistant runs it right after it fetches the plugin, each time it starts, not just the first time. The hook runs as root, with no arguments, from the plugin's own directory.

• Make it safe to run again. Check before installing anything (with dpkg-query, command -v, or a marker file under /var/lib/clouve/), so a restart is quick.
• A failing hook is logged, and the plugin and any others still load. Exit with an error when something fails, so the failure shows in the logs.
• Packages installed under /usr and /var survive restarts. Changes to /etc may not, so don't rely on them.
• Install only what the skill's scripts and playbooks need. Don't use the hook to change the skill's own files.

Connecting it

In the submission wizard, open Step 2 (Container Configuration), choose the AI Assistant tab and turn the AI Assistant on. Enter your repository in Skills source URL:

https://github.com/acme/blog-skills.git?plugins=blog

• The URL must start with https:// and include ?plugins= with at least one plugin name. Separate several names with commas: ?plugins=blog,shop.
• To use a branch other than the repository's default one, add it after #: https://github.com/acme/blog-skills.git?plugins=blog#release.
• For a private repository, enter a Git token with read access. Clouve stores it as a secret. A Git username field appears once you enter a token. Leave it blank to use the host's default (x-access-token on GitHub).
• If you leave the URL blank, the AI Assistant runs with its base context only and no skills.

The AI Assistant fetches your skills each time it starts. A change you push to that branch reaches customers' deployments the next time their AI Assistant restarts, so test changes on another branch before you merge them.

Writing a good skill

Customers will ask the AI Assistant to change a live system that holds their data. Write the skill so the assistant works like a careful operator.

• Ask before anything destructive. Before it deletes, overwrites or restores anything, the AI Assistant should say exactly what will change, such as how many rows a query will touch, and wait for the customer to say yes. Put this rule near the top of SKILL.md and repeat it in each playbook that needs it.
• Probe before acting. The AI Assistant should check what it's working with before it plans: the app's version, which containers it can reach, and which tools and access it actually has. Have it read host names and credentials from the environment instead of hard-coding them.
• Keep scripts scoped to the instance. A script should work on this deployment's app and data and nothing else. It takes its connection details from the environment and never prints a password or key. Keep secrets out of the repository, and never let a script send the AI Assistant's own access key anywhere.
• Cover the app's real admin tasks: backups and restores, upgrades, diagnosing errors and slow pages, user access, and the settings customers ask to change. Write a playbook for each one and try it on a real install.
• Leave capacity alone. CPU, memory and storage come with the customer's Clouve plan. When a resource limit is the problem, the AI Assistant should say so and point the customer to a bigger plan instead of changing the limits.
• Say when it can't help. When a problem is beyond the skill, the AI Assistant should explain what it found, so the customer can take it to you or to Clouve support.

Keep the skill current with your app. When you ship a new version of the app, check the playbooks against it, update authoredAgainst and raise the plugin's version. Clouve's skills also ask the AI Assistant to write down what it learns, usually in learnings.md, and to mention each new note in the chat. Changes the AI Assistant makes to a skill last only until it restarts, so copy the useful notes back into your repository.

Testing before you publish

Try the skill on a real deployment before customers do:

1. Submit your app with the AI Assistant on and Private visibility, so only you can see and deploy it once it's published.
2. Deploy it with the AI Assistant added. A free trial includes the AI Assistant at no charge but with no AI usage, so you sign in with your own Claude subscription to use it. A paid plan comes with a monthly usage allowance instead.
3. Open the AI Assistant and run every playbook against the app, including a restore from a backup. Ask for something destructive and check that the assistant asks you first.
4. Stop the deployment, start it again and check that the skill still works. install.sh runs on every start, so this shows it's safe to run twice.
5. When everything works, change the listing's visibility to Public.

Reviewers check the AI Assistant along with the rest of your submission. They look for:

• a skills source URL that loads, with a token if the repository is private;
• matching names, and a description that says when to use the skill and when not to;
• a confirmation step before everything destructive;
• scripts that stay inside the deployment, and no secrets in the repository;
• no changes to CPU, memory or storage.

Examples

Clouve publishes its own skills in its public skills repository, Clouve/magneto-skills. They all use the layout this guide describes, so start from the one closest to your app.

• WordPress handles backups that keep the database and wp-content/ together, plugin installs, core updates and site URL changes. It checks which access it has before each task.
• Moodle handles upgrades, plugin installs, cron, cache purges, backups and restores, and maintenance mode.
• Odoo handles module installs and upgrades, and backups and restores that include the filestore.
• Gibbon handles upgrades, module installs, backups and restores, and the academic-year rollover. Its install.sh adds the MySQL client and SSH tools its scripts use.

Related documentation

• Magneto Agent / AI Assistant
• Container configuration
• Publishing