Writing a good skill
Four fields, one of which decides whether the skill ever gets used.
Skills, then Create Skill. Four things to fill in.
Or just ask in a chat. Describe the skill you want ("write down how we format case studies: headline, then the problem in one sentence, then the numbers") and Asteria drafts it for you. You get a card showing the instructions it wrote, the description that decides when the skill fires, and whether it will load on its own or wait for /, and nothing is created until you approve that card. What you get is an ordinary skill: open it here afterwards to edit it, share it, or turn Auto-load off.
Name
What it is, in a couple of words. Case Study Format, Meeting Notes, Expense Policy Answers.
It is what you see in the / list, so make it scannable.
Description
Two hundred characters, and the most important field on the page.
The box asks "When should your assistant reach for this skill?" and means it literally. With Auto-load on, this text is what Asteria reads to decide whether the skill applies. It is a trigger, not a summary.
Write it as a condition, not a description.
Weak, because it describes rather than triggers:
Our house format for customer case studies.
Strong, because it says when:
Formatting a customer case study or success story. Covers section order, length and the required pull quote. Load before drafting any case study.
The built-in skills are all written this way, and they are worth copying. One of them reads:
Diagram requests (flowchart, architecture, pipeline, state machine). Use create_diagram, not generate_image. Load before any "draw / diagram / chart the flow" request.
Notice what it does: names the situations, lists the words a user would actually type, and ends with an explicit "load before X". That last clause is doing a lot of work.
If your skill never seems to fire, the description is almost always why. Add the vocabulary your colleagues would use, including the informal words.
Auto-load
On means Asteria can pick the skill up by itself. Right for anything that should apply whenever the situation arises, which is most skills.
Off means / only. Right when:
- The skill is opinionated and should apply only when asked
- It applies to a narrow case you would rather decide yourself
- It contradicts another skill, and you want to choose between them
Start with Auto-load on. A skill that only fires when someone remembers to type / is a skill that mostly does not fire.
Instructions
The skill itself, in Markdown, with an Edit and a Preview tab.
Write it as a procedure for somebody capable who has not done this particular task here before. What works:
Be concrete about the shape. Number the sections, say how long each runs, give the order.
Give an example. One short worked example is worth three paragraphs of description.
Say what not to do, especially where the obvious approach is wrong. "Do not open with the client's company history. Start with the problem."
Say what to do when it does not fit. "If there is no measurable result, say so plainly rather than inventing a soft one, and flag it for the writer."
What does not work:
Restating good practice. "Be clear and concise" is already in force and wastes the space.
Making it enormous. A skill is loaded into the conversation when it fires, and a sprawling one crowds out your actual question. If yours is running long, it is probably two skills.
Duplicating an agent's instructions. If it only ever applies inside one agent, and that agent already says it, you do not need the skill.
Testing it
Start a chat and describe the situation without naming the skill:
Draft a case study about the Acme rollout.
If Auto-load is on and the description is good, it fires. If it does not, the description needs the words you just used.
Then check it with / to confirm the instructions produce what you wanted. Two separate tests, because they fail for different reasons: a skill that fires but produces the wrong shape is an instructions problem, and a skill that never fires is a description problem.
Remember to remove the pill afterwards, or it stays in force for the rest of that conversation.
Sharing
The ordinary sharing dialog, or Publish to put it in your organisation's marketplace where anyone can add it to their library.
When publishing you can allow or forbid duplication. Allow it if you would rather people adapt your skill than start from nothing. Forbid it if the whole point is that everyone follows one version.
Unpublishing removes the skill from the marketplace and revokes everyone's library entry, so anything they duplicated stays with them and anything they merely added disappears.