How to Write AI Skills: A Complete Step-by-Step Guide

If you use an AI assistant to progress everyday workplace tasks, then it's likely you have run the same cut-and-paste prompting more than once. You told it what you wanted, gave it some steps, decided on the output, and got a decent outcome with which you could work. You may have even connected your apps and completed a complex process. But a couple of days later, you forgot how you got there and have to explain the whole thing again. You realised that the model didn't remember your context, created its own output format, and didn't include your branding this time. Maybe AI is not all it's cracked up to be... or maybe you're missing something important.

Every time you use the AI, it's a copy, paste, and re-explain exercise and you don't even know where to find the prompt you used before. Skills fix this problem, and the AI can write them for you once you know what you want. AI Skills operationalise your tasks, and are pretty much universal in that it doesn't matter what AI you use, Skills will function. You detail your process once in a file the AI reads, and from then on it can run the task on command or by matching to your natural language request. Something like the following can trigger a Skill titled report-writer.

"Here, last week we ran a process to produce a progress report for a client but I can't remember what it was where I put it. I need to run this again for Joe Bloggs Incorporated"

Skills started life as a Claude-only feature but have now become an open standard. That's good news because now pretty much any AI tool can read and execute your skills. However, you should take care to make each skill as unambiguous as possible and to avoid redundancy across your set of skills, a point this guide returns to later.

This comprehensive Skills guide covers what a skill is and what it is not, when to build one, how to write each part, how to test it, and how to keep data safe when using skills built by other people. That last point comes first, in fact, because it is the one that can cause serious harm if you are not eyes wide open on the risks. A bundle of seven working resources accompanies the guide, templates, checklists, and worksheets you can use directly, and each section below points to the one that applies.

Important

A skill is only as trustworthy as the person who wrote it. There are hundreds of thousands of skills you can download in a single command, and reuse is the point of an open standard, but a skill is not just a prompt. It can carry scripts and web links alongside its instructions, and a script can run on your machine with your permissions yet unbeknownst to you. So installing skills made by someone else is closer to installing software than copying text. Treat every skill you did not write as unreviewed code. Read it before you run it, prefer sources that scan what they publish, and never grant a skill access unless fully vetted. Section 2 covers the data security piece.

Contents

1. What Is an AI Skill?

2. Before You Download Someone Else's Skill, a Word on Trust and Safety

3. When to Build and When Not to Build Skills

4. The Anatomy of an AI Skill Folder

5. The Skill Frontmatter, Field by Field

6. Writing the Skill Description

7. Writing the Body of an AI Skill

8. Skill Reference Files

9. Skills That Use Scripts

10. Controlling How a Skill Gets Invoked

11. Testing Your AI Skills

12. The Do and Do-Not Checklist

13. Three Worked Examples

14. Where to Start

What Is an AI Skill?

A skill is a prompt, a set of instructions operationalised for repeated use. It is your workflow, or a defined portion of a workflow, captured once in a markdown file and other supporting files that the agent runs the same way every time. A skill is not a model and it is not an app. It is the knowledge layer and operating procedure that your AI tool calls upon, and it works with any agent that reads the standard.

The folder is small and is titled to reflect what the skill does. In other words, the skill title is action-oriented. For example, Social Media Writer writes social media posts. At minimum it holds a single file called SKILL.md, which may be sufficient for a simple repetitive task, but it can also carry a few more folders alongside it such as references, examples, and scripts.

social-media-writer/
├── SKILL.md          # required, the instructions plus a short frontmatter block
├── references/       # optional, detailed docs the agent opens only when needed
├── scripts/          # optional, code the skill runs
├── examples/         # optional, sample outputs that show the expected shape
└── assets/           # optional, templates, images, anything else it needs

None of this works unless the folder sits where your agent can find it, because skills are not loose files you point the model at, they live in a location the tool scans when a session starts. In Claude Code that location is the .claude/skills/ folder inside your project, so the example above would sit at .claude/skills/social-media-writer/, and placing a copy in ~/.claude/skills/ in your home directory instead makes the skill available in every project you open. Other tools that read the standard have their own equivalents with ChatGPT, for example, taking the skill as an upload rather than a folder on disk, so check where your tool expects skills to live before concluding that one is broken.

Your AI uses progressive disclosure when deciding if a skill is appropriate in any given circumstance, meaning the agent does not load the whole skill at once. It reads the name and description always, but it reads the full instructions only when it decides the skill is relevant to the request you've made. It then opens the reference files and scripts only when the instructions in the skill file reference them. This is what keeps skills cheap to use (once you stick to limits), and it shapes almost every decision that follows in this guide.

LevelWhat loadsWhen1Name and descriptionAlways, so the agent knows the skill exists2The SKILL.md instructionsWhen the agent judges the skill relevant3Reference files and scriptsOnly when a task needs them

A skill is a living document, rather than a once-off set-and-forget. Skills grow with your work and can sometimes become bloated and confused, so revise them as your ways of working change. You may also notice your AI is not using them as you initially designed, so review them, say, quarterly. This is also the first reason not to run a downloaded skill straight out of the packet. It was written for someone else's workflow and standards, not yours, so treat anything you pull off the internet as a starting point to adapt. For anything central to how you work, writing your own from scratch usually beats retrofitting a random file.

Before You Download Someone Else's Skill, a Word on Trust and Safety

With hundreds of thousands skills available online, there's s strong incentive to just grab one that seems to fit your needs. Directories like skills.sh and agentskill.sh are free and most a single command away. The reason to be careful is that a skill is executable material, not just text, and that changes who you should trust and how much.

A skill can bundle scripts and web links alongside its instructions. A script runs locally, on your machine, with your permissions, and a web link can pull in whatever sits behind it. So when you install a skill from a stranger, you are not reading a well scripted prompt, you are potentially running their code. An untrusted skill can carry malicious instructions, quietly read data it has no business touching, or leave the front door to your system files wide open to malicious entities.

Note that the risk does not end the day you install it, which is the part careful people still miss. What you read and trusted is not necessarily what you keep. The author can change the files afterwards, so if you track a cloned repository and pull updates, for example, a future change can introduce malicious code, or a careless mistake that lands unbeknownst to you. A skill vetted in January can turn against you in March without a dickie bird.

So the danger is not necessarily downloading generic skills but treating a stranger's code as safe because it arrived as a tidy folder with a friendly name. OpenAI's own help pages tell users to review uploaded skills and trust the source before running them, and scan uploads for risky behaviour while stating clearly that the scan does not replace the user's own judgement.

A short routine before you install generic skills.

• Read the whole SKILL.md, and open every file in scripts/. Anything you do not understand is a reason to stop rather than skim over.

• Search the skill for web links, and ask what each one is for.

• Check what it reads and writes, and refuse anything that asks for database or broad system access without a clear reason.

• Prefer directories that scan submissions, such as skillsdirectory.com, over a raw, unvetted repository.

• Pin to a version you have reviewed, and read the diff before accepting any update rather than pulling changes blind.

The rule is simply to apply the same care to a downloaded skill that you would give any code you did not write, because that is what it is. The same scrutiny goes for any third-party plugin or connector you add, for the same reason. Resource 05 in the bundle turns this routine into a checklist, one pass for first install and a second for every update.

When to Build and When Not to Build Skills

Not every task deserves a skill, and wrapping everything in one is a fast way to end up with functionality you didn't need and a workspace that feels out of control. The useful habit is to reach for the cheapest option that fits, and only move up when you have to.

• A plain prompt handles a one-off or a single instruction. Do not build a skill for something you will ask once.

• A skill is the right choice when the task is a repeatable method you apply more than once and want done the same way each time.

• A script is for deterministic work, a calculation or statistical output, validation, or a batch operation.

• A subagent suits an independent chunk of work whose raw material would otherwise clog up the main context.

Consider a prompt you have used more than once. This is something that you might find more value as a skill. Anthropic's own advice makes the same point from the opposite direction, warning against building skills for tasks you only think you might need. Run the model on your everyday tasks first, watch where it falls short, then write a skill to close that specific gap. You end up with a handful of skills that each fix a problem rather than a drawer full of tidy files you never trigger.

There is a cost argument too, because every skill you keep enabled shares the context window with your conversation, your files, and every other skill, so each one must justify the space it takes. When not to build is therefore just as important, and the answer is most of the time. Skip the skill for one-time tasks, for anything a single clear instruction already handles, and for knowledge the model already has. Ask yourself, will I need to run this again? And if the answer is yes, operationalise it in a skill.

One more reason to pause before you build matters most in teams. The agent chooses a skill by reading the descriptions loaded at the start of the conversation, so when two skills do nearly the same job it has no reliable way to pick between them. The result is usually different output to what you wanted and a feeling that this AI is not as good as you thought. As such, each skill should own one distinct job with a boundary you can state in a single sentence. This gets harder on a Teams or Enterprise plan, where skills are shared across the organisation.

Imagine three colleagues independently building three versions of the same report writer, each with its own slight nuance. Now this may not be a problem, but becomes a problem where the skills are applied organisation wide. So before you write anything new, check what shared skills already exist. Then extend or use an existing skill, and merge or retire duplicates when you find them. The description section later in this guide shows how a negative trigger keeps two neighbouring skills out of each other's way, but that is a patch, and distinct scope decided at design time beats disambiguation bolted on afterwards.

The Anatomy of an AI Skill Folder

The folder tree above is the whole structure, however, it can vary depending upon for what the skill is written. A few rules keep it valid across tools, and getting them wrong is the most common reason a skill might fail to load.

• The instruction file must be named exactly SKILL.md, with capitals as shown. skill.md or Skill.md will likely not be recognised by the AI.

• The folder name must be kebab-case (lowercase hyphenated) and match the skill name in the frontmatter, so a weekly-report skill folder will have name of weekly-reportin the skill frontmatter.

• Do not put a README inside the skill folder. A README is for sharing a skill in a public repository and is not for the skill itself.

• Do not use "claude" or "anthropic" in the skill name. Anthropic reserves both words for its own official skills, so a name containing either can be rejected outright. A vendor's name is a poor label anyway for a skill that may run in any harness and with any model.

Everything else follows the progressive disclosure idea, with your core instructions in SKILL.md, while long tables, detailed documentation, and exhaustive examples go in references/ so they load only when needed. Code required by the workflow goes in scripts/, and sample outputs that show the expected shape go in examples/. Keep the root clean, with nothing there except the SKILL.md and those folders.

One optional extra is the exception I make to the clean-root rule, and it is most useful in organisations. Nothing in the standard tracks how a skill changes over time, so I add a small metadata.json file to the folder root carrying the skill name, a version number, a one-line description, and the author. Anyone on the team can then see who built a skill and which version they are running, and updating it becomes part of the editing habit built into the workspace OS. Agents ignore the file, so it adds nothing to the context window. Treat it as optional housekeeping rather than part of the spec, most useful once several people share the same skill library.

The Skill Frontmatter, Field by Field

Every SKILL.md opens with a short block of metadata between two --- lines. This is the frontmatter, and it is where the agent looks first. Only the description is strictly required, but you should always include a name too. The character count limit on the description is 1,024, which equates to about 150 words. Go over this and the host may reject the skill as invalid rather than load it at all.

---
name: weekly-report
description: Draft a weekly client update from the project log. Use when asked for a client update, weekly report, or progress note for a named client. Writes in the house voice and saves to the client's folder.
model: haiku                      # optional, pin a cheap fast model for mechanical work
allowed-tools: Read, Write        # optional, tools the skill may use without asking you
disable-model-invocation: true    # optional, manual only, you trigger it by command
user-invocable: false             # optional, the opposite switch, model only, hidden from your menu
license: MIT                      # optional, from the open standard
compatibility: requires python3   # optional, from the open standard
---

One caveat on the example, the two invocation switches are shown together so you can see the syntax, but you would set one or the other, never both, because a skill that neither you nor the model can trigger will never run.

The name is kebab-case (lowercase hyphenated), matches the folder name and should be no more than 64 characters. The description is an important component in the skill, so it gets its own section. Beyond those two, a handful of optional fields can be completed if required.

• model names the model the AI should use for a given skill. A simple, mechanical skill can pin a cheaper, faster model while a heavy one reaches for the strongest, so the AI makes the efficient choice for you every time it runs. Across hundreds of runs, that can be a significant saving in tokens and cost.

• allowed-tools lists the tools the skill may use without prompting you each time.

• disable-model-invocation: true makes the skill manual only, triggered by command rather than chosen by the model. Use it for anything with side effects.

• user-invocable: false hides the skill from the menu, for background knowledge the model draws on rather than a command you call by name.

Two of the fields, license and compatibility, come from the open standard rather than any single vendor's core spec, so do not assume every host reads every field the same way. Two safety rules are not optional. Never put angle brackets in the frontmatter, because it sits inside the system prompt and is a place instructions could be injected. Keep the description on a single line rather than a multi-line block. Get either wrong and the skill can break in ways that are hard to spot. Resource 02 in the bundle puts every frontmatter field on one page, required and optional, with these hard rules alongside.

Writing the Skill Description

The description decides whether your skill ever runs, because it is the one piece always sitting in the model's context window in any given session. If it does not fire at the right moment, the finest instructions behind it are never read. A strong skill with a vague description does nothing.

Write it in the third person, keep it under the character limit, and aim for a sentence or two rather than a paragraph. A strong description covers three things in that line or two.

1. What the skill does

2. When to use it (phrased as a person would say)

3. What makes it different from anything nearby.

Most people write descriptions that are too narrow, and because the model errs on the side of not using a skill, a narrow description means the skill sits unused even when it would have helped. Write the description broadly and spell out every situation where it should run, including when the user asks for the outcome without naming the skill.

• Weak, and it will barely ever trigger. description: Helps you build dashboards.

• Strong, and it fires when it should. description: Build dashboards to display data. Use whenever the user mentions dashboards, data visualisation, internal metrics, or wants to display any kind of data, even if they do not say the word dashboard.

If two of your skills could collide, add a negative trigger that points to the right one, such as "Do NOT use for simple data exploration, use the data-viz skill instead." There is also a quick test that saves a lot of guesswork. Ask the agent, "when would you use the such-and-such skill?" It will quote the description back and expose what is missing, so adjust and ask again. Resource 03 in the bundle turns all of this into a fill-in-the-blanks formula with worked examples.

Writing the Body of an AI Skill

Plan before you write, and use a simple framework I call Goal, Context, Sources, Outcome (GCSO) to cover the four questions that stop you building something vague.

• Goal. What should this skill achieve, in one sentence?

• Context. When and where should it fire, and for whom? List the exact phrases a user would say.

• Sources. What reference material, data, tools, or scripts does it draw upon?

• Outcome. What exactly should come back, and what does a good result look like against a bad one?

Do a comprehensive brain-dump first and answer those four elements and most of the skill writes itself. Goal and Context become the description and the when-to-use lines, Sources become the reference files and scripts, and Outcome becomes the output section and the tests. Resource 04 in the bundle is a fill-in worksheet for exactly this, and resource 01 is a blank annotated SKILL.md to copy once your answers are down.

There is a shortcut most people miss at first, which is that you do not have to write the file by hand. Both Claude and ChatGPT will draft a skill from a plain-language description, and ChatGPT ships a "Create with Chat" option that does exactly this. Tell the AI, step by step, how you do the task and which tools you use, hand it your GCSO answers, and let it produce the first SKILL.md for you to refine. Describing your own workflow out loud is usually faster and more complete than starting from an empty file.

There is even a purpose-built tool for it, which is a neat demonstration of the whole idea. Anthropic ships a skill whose job is building other skills, called Skill Creator. You invoke it with /skill-creator or install it from the public anthropics/skills repository, and it walks you through defining the use case, writing the frontmatter, and validating the result. It has four modes, Create, Eval, Improve, and Benchmark, so it covers the whole life of a skill rather than just the first draft. ChatGPT does the same under the bonnet, using its own skill creator whenever you ask it to build or fix a skill.

Practical Steps

Here are a few principles that separate a skill that works reliably from one that misbehaves.

• Keep it concise. If the file runs past about 500 lines, move the extra detail into references/ where it loads only when needed, rather than leaving it in the main SKILL.md file.

• Explain, do not command. This is where most home-made skills go wrong. A file written wall-to-wall in capitalised ALWAYS and NEVER gives the AI no way to tell the rules that matter from the preferences, and it follows all of them to the letter and nothing more. Save the forceful command for the one or two rules that must never break, and give the reason behind everything else, because an AI that knows why an instruction exists applies it sensibly in situations you did not plan for. "Use British spelling because the audience is Irish and UK readers" beats "ALWAYS USE UK ENGLISH" every time.

• Match how strict you are to the step. Where a step must be done exactly one way, a format check or anything that deletes or overwrites, spell it out precisely. Where judgement helps, give the principle and let the AI work.

• Put the critical rules at the top, not buried in the middle, and repeat them if the file is long.

• Use a script whenever something must be exact. Code does the same thing every run, while written instructions always leave some room for interpretation.

A workable skeleton for the body is an overview line, a When to use section, a When NOT to use section that points at neighbouring skills, the workflow itself, the output format, an example or two written as user-says then actions then result, and a short troubleshooting list. Draft it, then read it back and cut anything the AI does not need to do the job.

Skill Reference Files

The moment your SKILL.md fills up with long tables, API detail, or a dozen worked examples, move that material into the references/ folder and link to it. This is progressive disclosure doing its job, as the reference loads only when a task reaches it, so the main file stays lean and the shared context stays uncluttered.

The trick is to link in a way that tells the model when to open the file, not just that it exists. A bare filename is easy to ignore, while a one-line pointer with the trigger built in is not.

For the full report structure and section order, see references/report-format.md

That sentence tells the agent both where to look and the condition under which looking is useful, which is the point.

Skills That Use Scripts

Some things should never be left to the model's interpretation, such as a format check, a calculation, a checksum, or a loop over five hundred rows. Anything with a single right answer belongs in code, which is what the scripts/ folder is for. You write the deterministic part as a script (or the AI writes it for you), and the skill calls it. Code is deterministic and language is not, and for anything that must be exact, that difference matters in terms of the result you want.

When the skill needs one of its scripts, the instructions simply tell the AI which command to run, and the command includes the location of the script. Rather than spelling out that location in full, you use a placeholder, a stand-in piece of text that gets swapped for the actual location at the moment it is needed. The placeholder here is ${CLAUDE_SKILL_DIR}, which simply means "wherever this skill folder happens to be on this computer". Writing the location that way means the skill keeps working when the folder moves to another machine or sits somewhere different on a colleague's laptop.

Run the collector, which writes the raw items to a working file.
`python ${CLAUDE_SKILL_DIR}/scripts/digest.py --out /tmp/digest-input.json`

If that second line looks intimidating, read it in plain words. It says run the script called digest.py that lives in this skill's scripts folder, and save what it produces to a working file. That is all these commands ever are, the name of a script plus where to put the result. And if you let the AI draft the skill for you, it writes these lines itself, so your job is only to recognise roughly what they say when you review them.

Python and Bash are the common pair, so keep the dependencies light, declare anything unusual in the compatibility field, and you have a skill that does the judgement in language and the exact work in code. That combination is what makes the more ambitious example below possible.

Privacy deserves its own rule here, and it has no exceptions. Never write an API key, a password, a username, or any other credential into a skill, and keep client and personal data out of it too. Everything in a skill folder can end up in places you do not control, the AI provider's servers when the file loads into context, a shared repository when you back the folder up, and a stranger's machine if you ever publish the skill. Have the script read credentials from an environment variable or your system's keychain at run time instead, so the skill refers to the key without ever containing it. The same goes for the examples folder, where client names and records should be swapped for invented ones.

Controlling How a Skill Is Called

By default, both you and the model can trigger a skill, and the model decides when it is relevant. That is right for most skills, but two frontmatter switches give you finer control, and they matter most for anything with consequences.

• Default, no switch set. Both you and the model can invoke the skill. This is right for most skills.

• disable-model-invocation: true. You can invoke it by command, but the model cannot. Use it for anything with side effects, deploys, commits, and messages sent.

• user-invocable: false. The model can invoke it, but you cannot, and it stays hidden from your menu. Use it for background knowledge the model draws on rather than a command you call by name.

The rule of thumb is that if a skill does something you would not want happening at a moment you did not choose, sending an email, pushing code, anything outward-facing or hard to undo, you lock it to manual invocation. If a skill is just context the model should absorb rather than a command you would call by name, hide it from the menu.

Testing Your AI Skills

As mentioned earlier, a skill is a small piece of software, so do not ship it on a hunch. There are two different things to test, and running them together teaches you little about either.

The first is function, whether the skill delivers what you designed, and this is quicker to check than it sounds because you already set the pass mark when you planned it. The Outcome line in your GCSO answers defines exactly what should come back, so run the skill on a real task and compare the result against it. A skill is built to deliver a predefined output, which means one run tells you most of what you need to know, and a second run on a different input confirms the result holds across contexts. When the output misses, the gap points at the instruction that left room for interpretation, so tighten that instruction and run it again.

The second is triggering, whether the skill loads when you ask in your own words and stays quiet when the request belongs elsewhere, and this is the part to hand to the AI rather than check by hand. Ask the model when it would use the skill and it will quote the description back and expose what is missing. Then have it go further, generating the phrasings you would be likely to use alongside near-misses that belong to neighbouring skills, and reporting which of them would load the skill. A phrasing that misses means the description is too narrow, so add the words that failed. A near-miss that fires means it is too broad, so tighten the scope or add a negative trigger. Resource 06 in the bundle is a paste-in prompt that has the AI run this whole check and report back with suggested fixes.

You do not have to build all that by hand. Anthropic's Skill Creator has Eval and Benchmark modes that run your skill against test cases and report the pass rate and how much it varies across runs, plus an Improve mode that rewrites the skill from the failures it finds. For any skill you rely on for daily work, that is the fast path to trusting it.

The Do and Do-Not Checklist

Do

• Write a broad, specific description with the exact phrases people say.

• Keep the SKILL.md under about 500 lines and push detail into references.

• Explain the reasoning behind an instruction rather than barking orders.

• Use a script for anything that has to be exact.

• Test both triggering and function before you rely on it.

• Match the folder name to the name, in kebab-case.

• Read any third-party skill in full, scripts included, before you run it.

Do not

• Run a downloaded skill as it comes, or accept its updates without reading the diff.

• Put credentials in a skill. No API keys, passwords, or usernames anywhere in the folder, and no client data in the examples.

• Bury the critical rules in the middle of a long file.

• Lean on capitalised ALWAYS and NEVER instead of explaining why.

• Put a README inside the skill folder.

• Use angle brackets or multi-line blocks in the frontmatter.

• Name a skill with "claude" or "anthropic" in it.

• Build a skill before you have watched the model fall short without one.

Three Worked Examples

The best way to see the shape of a skill is to look at three, from the simplest possible build to one that runs itself.

Beginner, a Single File

The simplest useful skill is one file and nothing else. A create-meeting-minutes skill takes the rough notes you typed during a meeting and turns them into tidy minutes, the same way every time. There is no script and no reference folder, just a SKILL.md with a sharp description and a short workflow.

---
name: create-meeting-minutes
description: Turn rough meeting notes into tidy minutes. Use when asked to write up minutes, tidy meeting notes, or summarise what was agreed in a meeting. Produces a summary, the decisions made, and an action list with owners.
---

# Meeting minutes
Read the notes provided, pull out the decisions made and the actions agreed,
and write minutes with three sections, a short summary, the decisions, and an
action list naming who owns each item and when it is due.

That is a complete, useful skill, and it shows that you do not need scripts or a folder of references to get value, only a clear description and a clear method.

Experienced, a Skill with References and Examples

A step up is a weekly-client-update skill that pulls the week's activity from a project log, structures it against a fixed format, and writes it in a set voice. This one carries a references/report-format.md for the structure and an examples/ folder with a sample so the model can see the shape you want.

weekly-client-update/
├── SKILL.md
├── references/
│   └── report-format.md
└── examples/
    └── sample-update.md

Two practical questions decide whether this skill will work day to day, and the skill answers both. The project log is whatever record you already keep, a running notes file in the project folder, a diary of session notes, or a project tool the AI reaches through a connector, and the SKILL.md names that location so the AI knows where to look. The output format is also yours to state, so if the skill says produce a Word document and save it to the client's folder, that is what arrives each week.

The SKILL.md stays short and points at the reference for detail, which is progressive disclosure working as intended. The main file loads every time the skill fires, and the format file loads only when a report is being written.

Expert, a Skill That Runs Itself

The full build is a daily-inbox-digest that reads your email inbox every morning with nobody at the keyboard, ranks the day's messages, and writes a short digest of what deserves your attention first. This is a skill with access to your email, so be deliberate about how you grant that. The connection runs through whatever route you already have, a connector (MCP) that links your AI to your email client, a mail provider's interface called from the bundled script, or a daily export file if you would rather keep the AI out of the inbox itself.

daily-inbox-digest/
├── SKILL.md              # the method, plus the frontmatter that locks it to manual and scheduled runs
├── scripts/
│   └── digest.py         # connects to the inbox and collects the day's messages
└── references/
    └── ranking-rules.md  # what counts as urgent, what can wait

The Python script does the collecting, the reference file holds the ranking rules, and the frontmatter carries disable-model-invocation: true, because a skill that acts on its own should not be triggered casually mid-conversation.

The piece that turns a skill you run into a skill that runs itself is your computer's own scheduler. Every operating system ships one, cron on Linux, cron or launchd on macOS, and Task Scheduler on Windows. On a Mac or Linux machine, a single cron line does it.

0 7 * * * cd /path/to/workspace && your-agent-cli -p "run the daily-inbox-digest skill" >> /tmp/digest.log 2>&1

That runs the skill at 07:00 every morning by calling your agent in headless mode (running a program without its visible interface), no window and no prompt, just the task. Windows users set up the same daily task in Task Scheduler, and the idea is identical whichever system you are on. Resource 07 in the bundle carries this full build, the SKILL.md, the script, and ready-made scheduler setups for all three operating systems. One practical point that applies everywhere is a scheduled task only runs if the machine is awake at the appointed time or is set to wake for it. Configuring wake behaviour differs by operating system and sits beyond the scope of this guide. Once a skill is reliable, you hand it to the machine and it becomes part of your day without you thinking about it. One caution, a scheduled skill runs unattended with your permissions, so keep it least-privilege, log what it does, and test anything that sends or posts before you let it loose. My advice is to avoid completely schedules that launch agents on the web without your supervision. This is significant risk.

Where to Start

A skill is your own workflow operationalised, written so a machine can run it back to you the same way every time, on the harness you or your team use. A year ago that file worked in Claude and nowhere else, whereas today the same skill runs on any agent that reads the standard, so what you build is not tied to one product.

Rather than starting with the inbox digest, start small by picking one task you explained to the AI in natural language. Write the four GCSO answers and let Claude or ChatGPT draft the SKILL.md from them. Refine it, test whether it triggers, and use it for a week, then write the next one. When you reach for someone else's skill to save time, and you will, read it first. The same care you would give any code you did not write is the care a skill deserves.

Need help? comment below or email me directly