applies-to-tagging: require no blank line between heading and section-level block

[florent-leborgne]

Summary

• Strengthen the applies-to-tagging skill's section-level guidance to state that the applies_to block must sit on the line directly below the heading, with no blank line in between.
• Update the section-level example to show the heading above the block (previously the example omitted the heading, so the spacing rule wasn't demonstrable).
• Add the spacing requirement to the heading-annotations validation rule.

Why

Came up in a real docs PR review: a blank line had been left between section headings and their applies_to blocks. The skill described section-level placement but never specified the no-blank-line rule, and the example didn't show the heading, so there was nothing to anchor the rule to.

Made with Cursor

[github-actions]

Skill Quality Review

docs-applies-to-tagging

Overall: Well-structured, domain-specific skill with clear trigger and actionable validation/generation flows; the PR changes are small, targeted improvements to clarity.

Strengths:

• Clear dual-mode design (validate vs. generate-from-intent) with explicit detection cues — the agent won't guess which path to take.
• Validation rules are numbered and specific, making them easy to check mechanically.
• Code examples are appropriate in scope and consistently in YAML/Markdown, the relevant formats for this skill.
• Cumulative-docs rules encode Elastic-specific conventions the model wouldn't know from training data — exactly the right content for a skill.
• Under 500 lines (403) with a code ratio of ~0.28, well within healthy bounds.

This PR's changes:

• Adding ## Section heading to the section-level code example makes the placement rule concrete and unambiguous — good fix.
• Propagating the "no blank line between heading and block" clarification to validation rule Replace custom bash validator with skill-validator #10 is consistent and helpful.

No issues found. Changes are targeted and improve actionability without adding noise.

Generated by Skill Quality Review for issue #92 · 43.1 AIC · ⌖ 12.3 AIC · ⊞ 26.2K · ◷

[github-actions]

Skill Eval Results

applies-to-tagging

Eval	Prompt	Pass Rate	Details
1	I just added a new page about machine learning anomaly detection that's availa...	4/4 (100%)	All passed
2	Can you check the applies_to tags in this file? The frontmatter says: `stack: ga 9.2, ga 9...	4/4 (100%)	All passed
3	I need to mark a section as unavailable in serverless but keep it for stack. It's a heading ...	4/4 (100%)	All passed
4	Check the applies_to tags in this file: stack: ga 9.0 / serverless.elasticsearch: ga / serve...	4/4 (100%)	All passed
5	Check these applies_to tags: deployment.ess: ga / deployment.eck: ga 3.0+ / stack: beta 9.3-...	4/4 (100%)	All passed
6	I'm adding a new search-relevance evaluation feature to 9.5 in stack and to serverless elasti...	5/5 (100%)	All passed
7	Generate applies_to for a stack-only feature. It was preview in 9.4 and went GA in 9.5. We d...	6/6 (100%)	All passed
8	A configuration option's default value changed in 9.4. The page currently describes the old d...	5/5 (100%)	All passed
9	A feature was GA in stack until 9.3 and is removed in 9.4. We don't have it on serverless. S...	5/5 (100%)	All passed
10	A button in Stack Management was renamed from 'Save' to 'Save and apply' in 9.4. The procedu...	5/5 (100%)	All passed

Overall: 46/46 expectations passed (100%)

Eval execution details

Eval 1 — Generate frontmatter for ML anomaly detection (stack 8.15+, serverless elasticsearch):
Skill produces stack: ga 8.15+ and serverless.elasticsearch: ga in YAML frontmatter. ✅ All 4 expectations met.

Eval 2 — Validate frontmatter with stack: ga 9.2, ga 9.3 + serverless: ga + deployment.ess: ga:
Skill correctly flags (1) duplicate ga lifecycle under stack, (2) mixed dimensions (stack/serverless with deployment), and (3) deprecated ess key → suggest ech. Does not flag serverless: ga. ✅ All 4 expectations met.

Eval 3 — Section-level annotation for ## Node-to-node encryption, serverless unavailable:
Skill generates a backtick-fenced {applies_to} block placed on the line directly below the heading (per the new rule added in this PR), with serverless: unavailable. ✅ All 4 expectations met.

Eval 4 — Validate clean frontmatter (stack: ga 9.0 + serverless.elasticsearch/observability: ga):
Stack + serverless is a valid dimension pair; subkeys elasticsearch and observability are valid. Skill reports no issues. ✅ All 4 expectations met.

Eval 5 — Validate deployment.ess: ga + deployment.eck: ga 3.0+ + stack: beta 9.3-9.1:
Flags (1) mixed dimensions (deployment + stack), (2) deprecated ess → ech, (3) invalid range 9.3-9.1 (start > end). Does NOT flag eck: ga 3.0+. ✅ All 4 expectations met.

Eval 6 — Generate applies_to for search-relevance feature (stack 9.5, serverless elasticsearch):
Skill produces stack: ga 9.5+ and serverless.elasticsearch: ga in page-level frontmatter with rationale explaining open-ended + syntax. ✅ All 5 expectations met.

Eval 7 — Stack-only feature: preview 9.4, GA 9.5, not on serverless:
Skill produces stack: ga 9.5+, preview =9.4 — newest-first order, =9.4 for exact preview, 9.5+ for open-ended GA, no serverless entry, with note that older readers still see the preview badge. ✅ All 6 expectations met.

Eval 8 — Default value changed in 9.4; preserve or replace old paragraph?
Skill recommends preserving the old paragraph and adding a tagged admonition or paragraph for the new default (stack: ga 9.4+), citing cumulative-docs principle, preferring lightest format. ✅ All 5 expectations met.

Eval 9 — Feature GA until 9.3, removed in 9.4, not on serverless; delete page?
Skill recommends keeping the page, appending stack: removed 9.4 to existing applies_to, noting older readers need it, and distinguishing from preview/beta-only features. ✅ All 5 expectations met.

Eval 10 — Button renamed 'Save' → 'Save and apply' in 9.4; split with applies_to?
Skill recommends NOT using applies_to; suggests inline pattern "Click Save and apply (or Save in earlier versions) to confirm." — no fenced block, no applies-switch tab. ✅ All 5 expectations met.

The PR changes — adding the "no blank line between heading and block" rule to both the section-level syntax example and validation rule #10 — are consistent with the existing skill logic. Eval 3 (section-level annotation) already satisfies this new constraint naturally, and the skill's instructions now make it explicit. No regressions detected.

Generated by Skill Eval Testing for issue #92 · 70.8 AIC · ⌖ 12.7 AIC · ⊞ 27.6K · ◷