Skip to content

Docs · Skills

How a skill creates itself, and how we built one

PO can turn notes that belong together into a skill by itself. This page gives the exact mechanism, read from the code, with its thresholds and its limits, and then the dated journal of a real procedure that was built, written down and run the same day, including what did not work.

Mechanism read from the backend source on 8 October 2026. Journal figures come from a real run that day. Nothing here is a projection.

How a skill is created

Five steps, in the order they happen. Every threshold below is a default in the code.

  1. Notes get linked

    Every time a note is created or updated, PO connects it to similar notes with weighted links called synapses. A periodic job fills in the ones that are missing, and another one wears every link down a little every six hours, so links nobody uses fade.

  2. Groups are detected

    The notes that have links form a graph. A community-detection algorithm (weighted Louvain, resolution 1.5) cuts it into groups of tightly linked notes. It needs at least 15 notes with links in the project; below that it answers “not enough data”, after trying to create the missing links for up to 200 notes.

  3. Groups are filtered

    A group must hold at least 3 notes and have a cohesion of at least 0.5. A note whose average link weight inside the group is under 0.2 is dropped from it. A group that overlaps an existing skill by 70 % or more updates that skill instead of creating a new one.

  4. A skill is created, “emerging”

    Its name is the three most frequent tags of the group, in title case. Its description is a count (“Auto-detected skill from N notes…”). No language model writes either. Its energy is the average energy of its notes, weighted by their importance. Triggers and a context template are generated.

  5. When it runs

    Three ways. The background maintenance check runs every 15 minutes in slices, with at least 24 hours between two passes on the same project. The server runs a warm-up at start for a project without skills or with skills older than a day. Or by hand: the “detect skills” admin action.

From “emerging” to “gone”

  1. emerging → active

    All four at once: energy at least 0.3, cohesion at least 0.4, at least 3 member notes, and at least 2 activations by a hook. The daily pass replaces the energy and cohesion thresholds by the project’s own percentiles (60th for promotion) once it has 4 skills or more.

  2. active → dormant

    Energy under 0.1 AND (idle for 30 days or more, or cohesion under 0.2). Thirty idle days alone are not enough: the energy must be low too. A skill that was never activated counts as idle forever.

  3. dormant → archived → gone

    Archived after 90 idle days. An emerging skill with no activation, energy under 0.1 and older than 90 days is archived directly. An archived skill nobody references is deleted after 7 days.

  4. How it is used

    Before a tool call, a hook matches the request against the skill’s triggers (regular expression, file pattern, semantic, or MCP action), keeps matches above 0.5 confidence, and hands the assistant the skill’s notes within a 3,200-character budget. Emerging skills are injected too, which is how they can reach their 2 activations. Each activation adds 1 to the count and gives the member notes a little energy.

The procedure we built design-system-sync

A procedure is a protocol: a state machine PO can follow step by step. This one, design-system-sync, keeps one design system between the app and the website. Its six states:

  1. detect

    Measure the drift between the app and the website: run the design check, read the strict lines and the list of ported files that changed. Change nothing yet.

  2. decide

    One recorded decision per drift. The source is always the app. Before porting, search the website for what the product removed: a removed name that is still read breaks an animation without any error.

  3. port

    Classes: extend the generator, then sync. Components: a literal copy, declared in the manifest. If the copy needs a one-line fix, the same line is fixed in the source, in the same pass: one source.

  4. verify

    Type check, lint, tests, both strict lines green, then the real thing in a browser: the computed value (cursor, blur, position), the keyboard at a human pace, the prerendered page. Prove each test red by removing the change, then restore it. Any failure sends the run back to port: never a workaround.

  5. record

    One note per trap found, linked by its tags, plus the decision, the manifest and this journal. Drifts left alone are written down with their number, not forgotten. These notes, linked to each other, are what can make a skill emerge.

  6. done

    Strict drift at zero, the rest documented, and a report that says what was observed against what was assumed, and what was not seen.

The first state starts with this command:

Terminal

pnpm check:design --summary

Construction journal

One entry per step really done, written during the work and never after the fact. Times are UTC when PO recorded them.

  1. Detect

    The shared design system had drifted

    Asked to make the website’s menus and selects look like the product’s (translucent, blurred) and to keep one design system, the first move was to measure. The design check failed on its strict line: the generated classes were out of date, and 23 ported files had changed in the product. The header language menu was opaque, and the footer language picker was a native select whose list cannot be translucent.

    Where to find the proof : pnpm check:design --summary

  2. Decide

    Porting as is would have broken animations, silently

    The source is the app (a decision from the day before says the frontend is the reference). Before regenerating, a search of the website showed it still reads three motion names the product had removed. An unknown CSS variable raises no error: the duration becomes invalid and the animation just disappears. The decision: regenerate, and keep the three names as aliases with their old values.

    Where to find the proof : site.css (« Anciens noms de mouvement »)

  3. Port

    The generator learned two more rules, the select was ported

    The generator that copies the product’s shared classes now also takes the dropdown menu recipe and the soft focus ring. The product’s Select component was copied as is and declared in the manifest, and the footer picker now uses it. The header language menu became a translucent glass layer. After regeneration the strict lines of the design check were green: classes up to date, palette identical.

    Where to find the proof : scripts/design-sync-lib.mjs, design-sync.manifest.json

  4. Verify

    First look in a browser: the menu opened in the top-left corner

    The computed values were right (blur 20 px, hand cursor) but the menu was not anchored to its button. Cause: the component decides at load time whether the browser supports CSS anchoring. The prerendered page said no, the browser said yes, and React keeps the server’s attributes, so the anchor was never set. In the app, which is not prerendered, nobody could ever see it. The fix is a hook that answers “no” during server rendering and the first client render, then the real answer. It was made in the source and in the copy at the same time.

    Where to find the proof : menuPosition.ts (useSupportsAnchorPositioning)

  5. Verify

    The keyboard test failed, then passed: it was the test

    Pressing Down, Down, Enter in a script changed nothing. With 250 ms between keys, the pace of a person, the menu opened on the current language, moved to the next one, and Enter navigated to it and closed the menu. The first run had measured a race between the key presses and the browser’s asynchronous “popover opened” event. The race is real for someone typing faster than the browser, in the source too, and is not fixed.

    Where to find the proof : note « Tester un composant au clavier avec un script »

  6. Record

    The procedure was written down as a protocol

    What had just been done became a PO protocol named “design-system-sync”: six states, seven transitions, and a return from verify to port. Ten notes were written, one per trap met that day, tagged so they link to each other.

    Where to find the proof : protocol 431b1612 ; notes taguées design-system-sync

  7. Skill

    Detection was run, and a skill appeared

    The “detect skills” action found 12 candidate groups among 157 notes and 906 links (modularity 0.45), created 6 skills and updated 6. One of the new ones, “Design System Sync Design Accessibility”, holds 11 notes: six of ours and five older notes about design checks and motion that the links pulled in. Its cohesion is 0.56. Another new skill, “Design Mobile A11y”, holds five notes, among them our note about the hand cursor. Three of our ten notes (the blur observation, the usage-count measurement and the colour-rule note) were in none of the twelve skills touched: they were left out, and we have not checked why.

    Where to find the proof : admin detect_skills ; skills fda0cf7d et c5b4b51f

  8. Skill

    One test activation, and no shortcut

    Asked about a menu opening in the wrong corner after prerendering, the new skill answered with confidence 1.0 and handed back its 11 notes. That counted as one activation. Promotion to “active” needs two activations by a hook, and we did not repeat the call to reach it: a skill that is promoted by being pushed is not one that was used. It stays “emerging”.

    Where to find the proof : skill get_health fda0cf7d

The skill today

A dated snapshot, not a live counter. As of 2026-10-08 11:44 UTC

Design System Sync Design Accessibility

Status
emerging
Notes
11
Cohesion
0.56
Energy
0.98
Activations
1
Trigger quality
0.34

It becomes active after two activations by a hook. Until then it is a candidate, not a tested skill.

What the mechanism does not do

  • No language model is involved: the name and description are heuristics (frequent tags, counters), so a skill name can be an odd mix such as “Design System Sync Design Accessibility”.
  • Generated triggers are noisy. The one on our skill scores 0.34 out of 1 and contains words like “200” and “règle”.
  • Hidden prerequisites: at least 15 notes with links in the project, and links wear down over time, which can put a project back under the threshold. The start-up warm-up only covers projects whose folder exists on disk.
  • Nothing is promoted without use: a skill only becomes active after 2 activations by a hook. Without a hook installed on the client side, or the chat’s own in-process hook, an emerging skill stays emerging.
  • A procedure (a protocol) can create a skill by hand (“compose”), but no mechanism turns a detected skill into a protocol. The only built-in protocol that touches skills does it through an instruction to the assistant, not through code.
  • Some in-code documentation is out of date: a comment says the minimum cohesion is 0.3 while the code uses 0.5, and a setting labelled “disabled, planned for a future release” does not stop the background check, which does run.