How skills work¶

A skill is what one person learnt the hard way, written down so that everyone's AI can follow it. This page explains how a skill gets from finished work to the Skill Store and back to the people using it, why skills load live instead of being installed up front, where the skills you see come from, and what the safety scan, search and feedback do. For the commands, see Discover and load skills.

A loop, not a library¶

A folder of markdown files stays as good as the day someone wrote it. A skill is meant to improve each time it is used, so its life is a loop of six steps, and the last step leads back to the first.

%%{init: {"flowchart": {"rankSpacing": 24}}}%%
flowchart LR
  C[Capture] --> P[Publish] --> D[Discover] --> L[Load] --> S[Share] --> F[Feedback]
  F -->|improve, publish again| P

Capture. Most skills start from work that already succeeded. Right after an agent session solves something, alis skills capture turns the decisions, checks and examples into a draft, so nobody has to rebuild the workflow from memory a week later. In a coding session, saying "capture this as a skill" is enough: the agent runs the command. A draft is private to you until you publish it.
Publish. Publishing puts a version of the draft in the Skill Store. Who can reach it is set per skill by its sharing, not by where it is stored. Every publish is also scanned for safety (see below).
Discover. Search ranks the skills you are allowed to see by what they actually teach, so you find a skill by describing the task rather than by knowing its name.
Load. Loading prints the published instructions into the session that needs them, at the moment it needs them.
Share. A skill reaches exactly as far as its owner chooses: one colleague, everyone at your email domain, another build environment's domain, or, for platform skills the Alis team maintains, everyone. A share can also make someone an editor, so a team maintains one skill together, or a co-owner.
Feedback. A rating, or a message, goes to the people who maintain the skill as a conversation. They turn it into the next version with alis skills improve, evaluate it, and publish again. Every later load gets the better version.

Why skills load live¶

Every skill installed in a coding agent costs context before the first prompt: the agent reads each skill's description up front so it knows what it has. Past a certain number, the agent starts shortening those descriptions to fit its budget, and discovery gets worse exactly as the collection gets more useful.

The Alis plugin avoids this by giving the agent one entry, the way to discover skills, rather than one entry per skill. Search runs in the Skill Store, and only the chosen skill's instructions enter the session. Ten thousand skills cost the agent no more context than one, and nothing is spent on a skill until the agent actually needs it.

Loading live has a second effect: a skill loaded from the Skill Store is always its latest published version. When you do want a copy on disk (alis skills install), that copy stays as it is until you upgrade it on purpose, so an update never overwrites it behind your back. alis skills sync refreshes only the small local list behind the agent's ambient suggestions; it installs nothing.

Where skills come from¶

The skills you see have five origins.

Platform skills are written and maintained by the Alis team as a shared baseline for working with Alis Ideate and Alis Build. Only the Alis team can share a skill with everyone, and feedback on one reaches them.
Your skills are the ones you author, from scratch, captured from work just done or drafted from a past agent session. You own them: editing, publishing again, sharing and deleting are yours, and feedback reaches you.
Skills shared with you come from colleagues, directly or through your domain. You can search, load and install them and send their owners feedback, but not edit them unless you were made an editor.
Block skills are the manuals of published code blocks. See below.
External skills are synchronised from a curated list of public skill repositories and open to everyone. Each keeps its upstream id under a source prefix, with its repository as its origin, and retires on its own when it leaves that repository.

How a block becomes a skill¶

A code block can carry its own manual: a .skill/SKILL.md in its build files, scaffolded by alis blocks create, with optional references/, scripts/ and assets/ beside it. When the block is published, that folder becomes the skill block-<block-id>.

The skill is taken from the block's most stable available release (GA, then RC, beta, alpha, experimental), and its version is the block's version.
Its name is set to block-<block-id>; the description is the author's. The block's generated agent docs and release notes ride along as references.
Values the block fills in when it is installed, such as the service it is installed into, appear in the Skill Store's copy as placeholders like <pkg>. An install still receives the real values.
Access follows the block both ways: the block's admins administer the skill and everyone else with a role on the block can read it, and sharing the skill gives the same people read access to the block.
Removing .skill/SKILL.md, or the block, retires the skill, and a daily check keeps every block skill in step with its block.

This is why buildable code goes in a block rather than in a skill: the instructions ship with the code they describe and cannot drift from it. See How code blocks work.

The safety scan is advice, not a gate¶

A skill is instructions an agent will follow, so a bad one is a real risk. Every publish starts an automated scan for skill poisoning, prompt injection, embedded secrets, malicious scripts and descriptions that misrepresent what the skill does. Its verdict and score appear as a badge (vetted 92, flagged 55, failed 10), with the findings behind it.

The badge informs; it never silently blocks a skill. Findings appear even on a skill that passed, because a low-severity note can still be worth knowing about. A badge also only shows while the scan covers the skill's current content: publish a new version and the badge disappears until the new content has been scanned, rather than showing a verdict about text that is no longer there.

Separately, alis skills publish refuses to publish when it finds a secret in your files. That check runs before anything leaves your machine; the scan runs after.

Search sees only what you may see¶

Search reads a skill's name, description, keywords and the body of its SKILL.md, so a skill with a short or imperfect description is still found by what it teaches. Each skill's sharing travels with it into the search index, searches run as you, and every result is checked again against the skill's current sharing before it is returned. A skill that was shared with you yesterday and unshared today does not appear, even if the index has not caught up.

Feedback carries its context¶

A rating up or down records a quick signal. A message opens a conversation with the skill's maintainers (the Alis team for platform skills); more feedback on the same skill lands on the same open conversation. When you share the agent session that hit the problem with a specialist, the skills that session used are found in it and attached to the conversation, so the maintainer sees the real run, not a summary of it. That concrete context is what makes the next version sharper, and usage is also what ranks skills in discovery: the loop compounds.