Hermiq skills tutorial series — Part 2: Qualifying a skill (L1–L7)

Every skill row in the Hermiq catalog carries a badge of seven dots. In this part you learn what the dots mean, run the Qualify action to earn them mechanically, read the scorecard that explains every failure, and attest level 4 as a human curator. You also learn why the ladder deliberately gets harder to climb from level 5 on.

The ladder, briefly

The maturity model comes from the fleet-wide skill-writing practice (ADR-068) and has seven levels. Each level stacks on the previous one: level n only counts when levels 1 through n minus 1 also pass.

Three honest observations before you touch anything:

• L1 to L3 are mechanical. Hermiq computes them from the skill's content. No judgement involved.
• L4 is human, always. No heuristic can verify that a skill encodes your organisation's actual way of working. A curator attests it, on the record.
• L5 to L7 are evidence-based. Hermiq never grants them from the skill's text. The evidence is written by other subsystems: paired eval runs (Part 3), the learnings loop (Part 4), and executed orchestration chains. No evidence, no level, with the reason spelled out on the scorecard.

Maturity is also strictly separate from the lifecycle state you saw in Part 1. A quarantined skill keeps its maturity; qualifying never changes state. And none of the maturity fields ever enter the exported agentskills.io package, which stays byte-identical before and after qualification.

Step 1: Read the dots on the catalog

Open Skills. The three example seeds ship at a deliberate spread:

Verify: the badges on the three rows show 1, 2, and 4 filled dots, each with a textual level for screen readers.

Step 2: Qualify a skill and read the scorecard

Qualification recomputes L1 to L3 from the current content, persists the result, and returns a scorecard for all seven levels.

1. On the meeting-notes-cleanup row, open the row actions and choose Qualify.
2. The scorecard opens: seven rows, each with pass or fail and readable reasons.

Expect this picture:

• L1 pass. Frontmatter parses, name and description present, body non-empty.
• L2 fail, with a triggering reason. The description Meeting notes helper names a topic but not a trigger. It does not start with a verb, and it never says when an agent should use it.
• Everything above L2 fails by the contiguity rule, whatever else the skill has.

The L2 check tests three things at once: trigger quality of the description (a verb-shaped phrase plus when-to-use phrasing), a body under 500 lines, and progressive disclosure (a large body must be accompanied by references/ files rather than being one monolith).

Verify: the scorecard shows L1 passed and L2 failed with a reason that mentions the description's trigger quality.

Step 3: Fix the failing level and re-qualify

The scorecard is a to-do list. Fix the one thing it names.

1. Edit meeting-notes-cleanup (the authoring form from Part 1).
2. Replace the description with a trigger-quality one: Clean up raw meeting notes — use when the user pastes meeting notes and wants tidy headings, grouped action items, and decisions kept verbatim.
3. Update the frontmatter's description: line to match, and save.
4. Run Qualify again.

Verify: the skill now reports level 2, and the scorecard's first failure has moved to L3 with a missing references/examples reason.

To reach L3 you would add at least one references/* or examples/* entry in the files editor. Try it on your own pet-store-order-summary skill from Part 1: add examples/order-summary-example.md with one worked example, re-qualify, and watch L3 pass.

Step 4: Attest L4 as a curator

L4 says: this skill encodes business-specific knowledge, and a person checked. Hermiq refuses to guess this. The attest action is gated by action authorization: your group must be mapped to the skill.attest-maturity action in Hermiq's admin settings.

1. As an admin, confirm your group is mapped to skill.attest-maturity (Hermiq admin settings, action authorization section). Admins pass by default.
2. Open the woo-request-triage detail page. After step 3-style fixes it sits at the level its content earns.
3. Use the Attest L4 action on the maturity scorecard and add a short note, for example: Checked against our WOO intake procedure, routing table is ours.
4. The attestation records who attested, when, and the note, then recomputes the level.

An unauthorized user gets a plain 403 and the skill stays unchanged. And attesting a skill that still fails L2 or L3 does not skip anything: levels stay contiguous, so the attestation waits in the evidence until the lower levels pass.

Verify: the detail scorecard shows the attestation with your user id and timestamp under L4.

Step 5: Read why the ladder stops here for now

Open tender-summary. It ships at L4 with targetLevel: 5, so the scorecard shows exactly the situation most real skills live in:

• L1 to L3 pass mechanically.
• L4 carries a seeded attestation.
• L5 fails with an eval-evidence reason. No paired eval run has written evidence for this skill yet.

You cannot fix that from this page, and that is the point. L5 evidence has exactly one writer: a completed paired eval run. Hand-editing maturityLevel does not work either; the write paths silently ignore client-supplied maturity fields and carry the stored values forward. The only way up is real measurement, which is Part 3.

Verify: the tender-summary scorecard reports L5 failed with a reason pointing at missing eval evidence.

Why most skills plateau at L4

The ladder is not a grade to maximise. L5 costs eval datasets and roughly double the tokens per run. L6 costs a capture and consolidation loop. L7 costs an orchestrated chain that actually executes. For a skill you use weekly, L4 with a fresh attestation is a healthy resting place. Push to L5 and beyond for the skills that carry daily workflows or steer other skills, where "feels right" stops being good enough.

Test yourself

Question 1: A skill has excellent references/ files but a description that is a bare noun phrase. What level does Qualify report, and why?

Question 2: Why can an admin edit a skill's targetLevel but not its maturityLevel?

Where to go from here

Your skills now have honest badges and one named gap: eval evidence. Part 3 links an eval dataset to a skill, runs a paired with-and-without baseline, and watches the L5 evidence arrive on the scorecard.