On 8 April 2026 I deleted thirteen skills in one afternoon. I had more than thirty of them between the terminal and the desktop app, with heavy overlap, and my Twin’s decision log says it in those words (entry of 2026-04-08).
1. Why a prompt is not enough
The problem was not tidiness. It was that I started from scratch every time, and the result followed the mood of the day.
Tidiness had little to do with it, though: the point was that every time I rewrote the same instructions from memory, forgot half the constraints, and the quality ended up depending on how I had got out of bed that morning. A prompt works beautifully on the day you write it, because that day you have the whole context in your head, and much worse three weeks later, when you can no longer find it and you write it again from memory.
Today my computer holds 29 skill folders: 17 written by me, 3 adapted from an outside repo and 9 from third parties. All 17 of mine carry a version number in the block of details at the top of the file, the front-matter, and a table that tracks their history, the changelog, 70 rows in total (counted on 15 September 2026, with the same recognition rule my audit script uses). The day before it was not so: two simply existed, with no version and no history, and chapter 7 tells how I found them.
2. What a skill actually is
The letdown is part of the point: there is nothing magic inside. There is, though, one line a prompt cannot have, and my design system skill has it written against itself.
It is a Markdown file, and that is the whole letdown. A front-matter at the top (name, triggers, version, author, date of the last change) and the body below it: philosophy, scope, operating steps, the section that says which other skills it interacts with, and the version and maintenance table. It is the same structure Anthropic describes for Agent Skills: metadata always loaded, instructions loaded only when the skill fires, resources loaded only when they are actually needed.
Anyone working with ChatGPT has the same thing in custom instructions, in GPTs and in Projects; anyone using Gemini has it in Gems. The name changes, not the principle: a written procedure the model loads when it is needed.
The difference from a prompt is all in there: a prompt says what you want, a skill also puts in writing when it does not apply. My design system skill, for one, has a changelog line that admits something uncomfortable: the site was already at 0.86 while the skill still had 0.78 written into it (skills/nick-brand-ui/SKILL.md, changelog v2.6 of 20 August 2026). A prompt cannot hold a sentence like that, because it has no yesterday.
3. The moment it fires
The most important piece of the system is not a procedure but a reminder: and nobody looks at it until it is missing.
A skill you have to remember to invoke is a dead skill, and for weeks I was the bottleneck of my own AI, the point everything had to pass through my memory. That is why the most useful piece of the system is not a skill at all: it is a hook, a piece of code Claude Code registers in the settings (settings.json) to run on every prompt and propose the skills when it recognises the case, staying silent on everything else. It is 150 lines of bash with 15 bilingual patterns, covering 10 of my skills (counted on 14 September 2026: unchanged since the 10th, except that it now covers design-agency in place of ux-ui-pro).
It imposes nothing: it reads the question, recognises that it is about valuing a startup, or about unit economics, or about a piece of visual work, and suggests the skills that apply, because the recognition is heuristic. The decision stays with the model, and in the end with me.
The best line in the whole system
Acceptable false positives (e.g. “should we go out for dinner”) → I ignore them. False negatives are the real problem: a manual skill you forget equals a dead one.
That is my own translation of lines 101-102 of hooks/skill-router.sh; the original is in Italian. Better one suggestion too many than silence on the very day it would have mattered.
And one rule sits above all the others: if problem-framing fires, the skill that forces me to frame the problem before solving it, it gets invoked first, because a domain framework applied to a badly posed problem produces elegant work on the wrong question (same file, line 140).
4. Skills reference each other
Two names collect almost a third of all the links, and it did not happen by chance: there is a commit made on purpose to create them.
Taken one by one they are procedures; put together they become a graph, and a graph can be counted: 77 cross-references from one skill to another and 22 pairs that reference each other back, extracted from the interaction section of every file with the same automatic reading rule check number 5 of my auditor uses (extraction of 15 September 2026; the graph file stays in the private repo, as I explain in chapter 9).
The version numbers painted on the nodes are the ones read in the files on 14 September 2026.
The two centres are problem-framing and critical-quality, the quality check: ten skills reference the first, thirteen reference the second. They are the two gateways through which 23 of the 77 cross-references pass, a little under a third, one before (what problem are we really solving) and one after (do these numbers hold). The other destinations drop off fast: nick-brand-voice at seven, professional-trader, startup-evaluator and vademecum at five each, design-agency at four, then llm-council, content and nick-brand-ui at three. My skills also look outside their own scope: seven cross-references towards third-party skills, dataviz, design-taste-frontend, docx, pdf, pptx, ui-ux-pro-max and webapp-testing, whenever a competency I have not written myself is needed.
The reciprocity did not happen on its own. There is a commit, a dated save of a change to the code, made on purpose to create it: it is titled cross-ref bidirezionali and names the three skills wired together in that round (configuration repo, commit a49904a). It is the kind of work nobody sees and that holds up everything else.
5. Skills get tested
A procedure with no test cases is a well-written opinion. Three skills have one, and the best written of the three is the one I have never run again.
This is the part where a stack of procedures stops being a collection of notes. Three skills have a suite of test cases, written the way you would write one for code.
The most rigorous is problem-framing’s: 17 cases written against version 1.3 of the skill, dated 16 June 2026 (the skill is at 1.5 today and the suite has not been run again), with the threshold written into the file, 14 out of 17 have to pass for the skill to count as operational (skills/problem-framing/evals/cases.yaml, line 358). The cases come from real situations, abstracted just enough to be written down, which is why the suite stays out of the downloadable files: here you get the structure and nothing else. The second is vademecum’s, 10 cases dated 17 July 2026 (skills/vademecum/evals/cases.yaml, lines 11-13); the third is professional-trader’s, a baseline of 2 July 2026, 10 out of 10 at design level.
Honesty: the most rigorous suite is also the only one with no result on record, and vademecum has the opposite flaw, eight cases out of ten validated and no threshold written down (commit dc17fe4).
6. The skill that audits the skills
The number I kept repeating was wrong, and I only noticed by doing the count again to write it here.
The answer is called skill-auditor, and its philosophy fits into one line.
A skill that is not verified is a skill that will break something sooner or later. The question is not whether, but when.
(skills/skill-auditor/SKILL.md, lines 23-24, my own translation of the Italian original). It is the same question I ask myself when I read the marketing around AI agents: what counts is what a system actually does, not what it says it does.
The documented checks are ten, each with its own card. Another three live in the script and appear in the document only in two changelog lines and one line about the next iteration: thirteen in all. Seven run on their own inside a Python script (skills/skill-auditor/scripts/audit.py, 455 lines) that writes nothing to disk.
| How they run | How many | What they check |
|---|---|---|
| On their own, every run | 7 | front-matter, agreement between version and title, minimum sections, changelog integrity, cross-references, content lost between two versions, trigger overlap |
| Only if I call them | 2 | drift from the original versions of the skills that are not mine |
| By hand | 4 | stay on me |
Thirteen checks defined, seven automatic in the standard run (audit.py, a count of the check_ functions). In the catalogue I had written for myself on 4 September 2026, I had them down as 13 automatic, and it was not true.
And it puts its own scope in writing: it does not operate by name on docx, pdf, pptx and xlsx, which follow different conventions. That line matters: it is why the count in the next chapter is over my 17 and not over the 29 folders.
7. The check, and what it finds in mine
The check is not there to look good: it is there to tell me where the system is weakest. And the spot where it passes without noticing anything is more instructive than the spot where it stops.
On 14 September 2026 at 15:31 I ran the auditor over my 17 skills, read-only (on the other twelve folders on the machine, third-party or adapted, the count makes no sense: see the methodology note).
| My 17 skills, at 15:31 | How many |
|---|---|
| Operational | 12 |
| Ready with a caveat | 1 |
| Stopped by the check | 4 |
The four were the design system, the publishing skill, the English one and the expense-report one. Three lacked a section or a version number (one, the English skill, had a stray character at the top of the file and the check stopped at the first line); none of the four was broken in use. But the fourth is the interesting story.
The gap that moved
At 15:31 the design system file declared version 2.13; the changelog had ten rows, but not the one for 2.10: a commit on 4 September, the exception for the NG monogram, had raised the number without writing the row. On 10 September the gap sat at the bottom of the table; on the 14th it sat in the middle, with three new rows above it. My Check 4 passed it regardless: it counts the rows, not the continuity, and that is the point of the whole chapter, a rule is worth as much as its check.
The error the auditor actually found is more instructive: the interactions with the other skills were there, but under a heading of my own, Rapporto con le altre skill, and the procedure is called Procedura, not Step. Stopped over the name of two sections, the proof that the person who wrote the convention is the first one not to follow it. One last detail, unchanged for two months: the script printed auditor skill-auditor v1.1 at the top of every report, while the skill that contains it declared 1.2. The auditor had exactly the flaw it goes looking for in everyone else.
The same evening
I fixed them that evening, one at a time, ten minutes each: the stray character in the English file, a version and a history for the two that had none, the missing sections in the publishing skill, the 2.10 row recovered from the commit that had skipped it. And I fixed the auditor: it now recognises Procedura and Workflow as names of an operational section (it was stopping two skills over the title, not the substance) and prints the right version. Second run at 22:11: 17 out of 17. The proof is not the final number, it is that every changelog row written that evening carries the date of 14 September 2026: the system tells on its own the day it was corrected.
8. What still does not work
The flaws you can see are the small ones. The big one is that the system cannot say how many times it actually helped.
Of the thirteen checks four stay manual and another two only run if I call them: they depend on me and on my memory. The 2.10 gap, on the other hand, it would see today: on 15 September I taught Check 4 to count the continuity of the versions (a row must follow the previous one, or open a new number), and tried on a copy of the file without the 2.10 row it stops and says which one is missing. One flaw fewer, found while writing this page. One test suite out of three has no result on record, and the two that do have one have no threshold. The router’s latency, declared at under 30 milliseconds, is a comment in the code and not a measurement (hooks/skill-router.sh, line 12).
The biggest hole is elsewhere: the system keeps no record of itself. I know the hook is registered, not how many times a skill it proposed was actually invoked. The sentence I would like to be able to say, that quality no longer depends on how I phrase the question, has no number behind it today: it remains a claim resting on a system, not a measured result, and I write it this way until it is one. The same caution applies to synchronisation: across the two environments, terminal and app, there is the same core of skills, not the same synchronised stack.
9. What you download
Two files, and not one line of my procedures is inside them: the mould, not the contents.
None of my skills leaves this page in full, not even a single line of the ones with personal data. What you download is two files.
The map of the stack, as SVG: the nodes are the skills with their version numbers, the edges are the 77 cross-references, a solid stroke for the 22 reciprocal pairs and a dashed one for the four skills of mine the check stopped at 15:31.
The skeleton of an empty SKILL.md: the names of the sections and the fields of the front-matter, with a comment explaining what each one is for. It is the mould, not the contents.
Three things I thought of attaching stay in the private repo: the JSON file of the graph (it lists, skill by skill, what references what, that is the map of how I work in more detail than I want to make public), the auditor’s reports (the reasons behind each verdict quote pieces of the skills’ descriptions, and two of them name companies and internal procedures) and audit.py, which is my own code running on my own stack. The numbers in this case come out of those files: I wrote them here so they can be compared with the map, not so they can be redone at home.
Sources: counts and cross-references measured on 15 September 2026 on the skills/ folder and on the skill-router.sh hook; verdicts from the audit.py runs of 14 September (15:31 and 22:11) and 15 September (11:18); the origin of the stack from the Twin’s decision log, entry of 8 April 2026.
How it was built
Not one of these numbers is an estimate: they come out of four steps that anyone with a skills folder can repeat.
The folder count
The 29 folders that contain a SKILL.md file, counted on 15 September 2026 with the same recognition rules as the audit script: so the text and the check count in the same way.
The graph, with check number 5’s rule
The cross-references are extracted from the INTERAZIONE CON ALTRE SKILL section of every file, with the same yardstick as check number 5. The result sits in a JSON file that stays in the private repo (chapter 9): the map draws it, the text quotes it.
The auditor, read-only
audit.py ran three times, on 14 September 2026 at 15:31 and 22:11 and on the 15th at 11:18, over all 29 folders: it writes nothing to disk and changed nothing of what it was measuring.
The map, drawn by hand
A layout algorithm on 29 nodes produces unreadable overlaps: the positions are written one by one in a Python script that reads the JSON and produces the SVG and the image in both languages together.
What the machine did not decide
The AI did the counting, the extraction of the graph and the code for the drawing. I am the one who chose the number that goes in the first line, and chapter 7 is the proof I did not soften it: at 15:31 four of mine did not pass the check, and one of them was the one that governs the way this page is laid out.
Four measurements, one single day, and not one estimated number: if the stack changes, you do not update a figure by hand, you run the script again.
Methodology note
Every source is a file on a computer, not a memory. Here is how they were read, and the points where the numbers say less than they seem to.
What was counted
The skills/ folder, in a private git repo, read on 15 September 2026. A skill is a folder with a SKILL.md file: there are 29. Adapted skills and third-party ones are recognisable because they have an author, a licence or an origin different from mine written into them.
What was run
One command only, audit.py --all, read-only, over all 29 folders, run three times: on 14 September at 15:31 and, after the fixes, at 22:11; on the 15th at 11:18 with the new Check 4. The report closes with a verdict among OPERATIVA, PRONTO CON CAVEAT and BLOCCANTI: the verdicts quoted in the text are those, not a summary of my own. Over all 29, the 15:31 run gave 12 operational, 2 with a caveat and 15 BLOCCANTI, but the 15 is not a number about my stack: the auditor skill declares it does not operate on docx, pdf, pptx and xlsx, and the --all script does not apply that scope, so eleven of the fifteen are third-party skills, or skills adapted from an outside repo, that never had my convention in the first place. The count that matters is over my 17: 12, 1 and 4 at 15:31; 17, 0 and 0 at 22:11 and again on the 15th. The other 12 folders give the same result in all three runs.
Where the numbers say less than they seem to
Two caveats. The first is that a BLOCCANTI verdict is not about whether something works but about convention: it says a file is missing a section, a version or a changelog row, not that the skill does not do its job. The second is that there is no log of the triggers: I know when the hook is registered to run, not how many times a skill it proposed was then actually invoked.
Five days, not one
This case is the snapshot of 10 September 2026, rewritten on the 14th with the same yardstick: in between design-agency was born, the three adapted QA skills came in and two changelogs moved up a version, with the folders and the cross-references growing accordingly (the numbers are in the chapters above). On the evening of the 14th, after the fixes of chapter 7, the cross-references went from 67 to 77 and the reciprocal pairs from 19 to 22: four skills that did not declare who they work with now write it down. On the 15th, the day this page goes out, the auditor is at 1.4 and counts continuity. The method, though, has not changed: you run the same command again and count again. It is the simplest demonstration of this case’s thesis: if the changelog is alive, today’s count is not the one from four days ago, and anyone who writes a skill instead of a prompt knows it because they see it written down, not because they remember it.
It is not a method I recommend to anyone, it is not a product and it is not advice. It is a description of how I keep the tools I use in order, on a computer of my own, with the flaws the check still finds inside it. Anyone tempted to copy it would do well to start from the boring part, the check, and not from the procedures.
In closing
A system of rules does not make you good, it makes you measurable.
The proof is not that my 17 skills are in order today: it is that on 14 September at 15:31 four of them were not, and I found out because I had written the check before I needed it. For the other cases of how I work with AI, the index is here. If you want to talk about it, write to me.
