[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6ACE7HZNK305VJGV3WN4P5N":3,"skill-same:01M6ACE7HZNK305VJGV3WN4P5N":47},{"skillNo":4,"name":5,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":20,"linkOnly":21,"markdownContent":22,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":29,"ownerHtmlUrl":30,"ownerBlogUrl":31,"ownerDescription":6,"updatedAt":32,"install":33,"resources":46},"01M6ACE7HZNK305VJGV3WN4P5N","groovy-skills",null,"apache\u002Fgroovy","apache","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F47359?v=4","01M6AC83E6K4FDKK7HZ8WNMQKE","The Apache Software Foundation","01M6ACDPCXGWGWJN1KV90SHDQB",5482,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fapache\u002Fgroovy\u002Fblob\u002Fmaster\u002F.agents\u002Fskills\u002Fgroovy-skills\u002FSKILL.md",[],[18,19],"groovy","groovy skills","2026-11-10 10:12:30",false,"\u003C!--\n  Licensed to the Apache Software Foundation (ASF) under one\n  or more contributor license agreements.  See the NOTICE file\n  distributed with this work for additional information\n  regarding copyright ownership.  The ASF licenses this file\n  to you under the Apache License, Version 2.0 (the\n  \"License\"); you may not use this file except in compliance\n  with the License.  You may obtain a copy of the License at\n\n    http:\u002F\u002Fwww.apache.org\u002Flicenses\u002FLICENSE-2.0\n\n  Unless required by applicable law or agreed to in writing,\n  software distributed under the License is distributed on an\n  \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY\n  KIND, either express or implied.  See the License for the\n  specific language governing permissions and limitations\n  under the License.\n-->\n---\nname: groovy-skills\ndescription: Conventions for authoring or refactoring a SKILL.md under .agents\u002Fskills\u002F in the Apache Groovy repository — directory layout, required frontmatter, the standard section order (When to use \u002F Read first \u002F Top failure modes \u002F Procedure \u002F Validation checklist \u002F References), the \"failure modes are observed mistakes not aphorisms\" rule, granularity heuristics for whether a topic deserves its own skill or belongs in an existing one, and the cross-skill linking and `AGENTS.md` table maintenance that keep the skill graph load-bearing. Use when adding a new skill, splitting an existing one, or reviewing a skill PR.\nlicense: Apache-2.0\ncompatibility: claude, codex, copilot, cursor, gemini, aider\nmetadata:\n  audience: contributors to apache\u002Fgroovy\n  scope: meta-skill-authoring\n---\n\n# Groovy skills\n\nThis is the meta-skill: it describes the conventions the other skills\nunder [`.agents\u002Fskills\u002F`](..\u002F) follow. Load it when adding a new\n`SKILL.md`, splitting an existing one (as\n[`groovy-jira`](..\u002Fgroovy-jira\u002FSKILL.md) was split out of\n[`groovy-triage`](..\u002Fgroovy-triage\u002FSKILL.md)), or reviewing a skill PR.\n\nThe other skills are the corpus this one describes. They are also the\ncanonical source — if anything in this skill conflicts with the\npractice visible across the existing skills, the corpus wins and this\nskill is out of date.\n\nWorked examples in the corpus, when authoring a new skill:\n\n- [`groovy-tests`](..\u002Fgroovy-tests\u002FSKILL.md) — exemplar for the multiple-procedures shape (`## Procedure for X` \u002F `## Procedure for Y`).\n- [`groovy-fix-workflow`](..\u002Fgroovy-fix-workflow\u002FSKILL.md) — exemplar for the single-procedure shape (plain `## Procedure`).\n- [`groovy-triage`](..\u002Fgroovy-triage\u002FSKILL.md) and [`groovy-jira`](..\u002Fgroovy-jira\u002FSKILL.md) — exemplar for the deferral split (workflow skill that defers mechanics to a sister skill).\n- [`groovy-reproducer`](..\u002Fgroovy-reproducer\u002FSKILL.md) and [`groovy-reassess`](..\u002Fgroovy-reassess\u002FSKILL.md) — exemplar for a load-bearing piece plus the campaign skill that loops over it.\n\n## When to use this skill\n\n**Use it for:**\n\n- Adding a new `SKILL.md` under `.agents\u002Fskills\u002F\u003Cname>\u002F`.\n- Refactoring or splitting an existing skill (extracting a deferral target, merging overlapping scopes, repositioning a skill against its neighbours).\n- Reviewing a PR that adds or modifies a skill.\n- Deciding whether a topic deserves its own skill or belongs as a section of an existing one.\n\n**Don't use it for:**\n\n- Editing the *content* of a specific area's skill — for build conventions, load [`groovy-build`](..\u002Fgroovy-build\u002FSKILL.md) and edit there; this skill is about *how skills are written*, not their subject matter.\n- Project-wide AI-contributor policy (licensing, `Assisted-by:`, the \"what *not* to do\" list) — that lives in [`AGENTS.md`](..\u002F..\u002F..\u002FAGENTS.md). This skill points at it, doesn't restate it.\n- Authoring tooling outside `.agents\u002Fskills\u002F` — `MEMORY.md`, `CLAUDE.md`, `copilot-instructions.md`, etc. — they follow different conventions.\n\n## Read first\n\nThere is no separate convention document; **the existing skills are the convention.** Before writing or refactoring, read at least:\n\n- [`groovy-build`](..\u002Fgroovy-build\u002FSKILL.md) — long-running procedural skill, dense failure-mode list.\n- [`groovy-tests`](..\u002Fgroovy-tests\u002FSKILL.md) — paired procedures (regression test, AsciiDoc example), good template for multi-flow skills.\n- [`groovy-triage`](..\u002Fgroovy-triage\u002FSKILL.md) and [`groovy-jira`](..\u002Fgroovy-jira\u002FSKILL.md) — worked example of a deferral split (workflow skill that defers mechanics to a sister skill).\n- [`AGENTS.md`](..\u002F..\u002F..\u002FAGENTS.md) — the project's AI-contributor policy and the `## Skills` table this skill's procedure mutates.\n\nIf a question about conventions isn't answered by reading those, the convention probably hasn't been established yet — propose it on `dev@groovy.apache.org` rather than inventing it in a new skill.\n\n## Top failure modes\n\nRecurring mistakes when authoring or reviewing skills:\n\n1. **Aphorisms instead of observed failure modes.** \"Be careful with concurrency\" is a style guide, not a failure mode. Each entry under `## Top failure modes` should name a *specific* mistake an LLM or contributor has actually made (or would plausibly make) in this area, with a short explanation of what's specifically wrong and what to do instead. If you can't think of a concrete instance, leave the entry out — five real failure modes beat ten generic ones.\n2. **Inventing project conventions to fill a section.** If the rule the skill wants to encode isn't backed by [`CONTRIBUTING.md`](..\u002F..\u002F..\u002FCONTRIBUTING.md), [`GOVERNANCE.md`](..\u002F..\u002F..\u002FGOVERNANCE.md), [`ARCHITECTURE.md`](..\u002F..\u002F..\u002FARCHITECTURE.md), [`COMPATIBILITY.md`](..\u002F..\u002F..\u002FCOMPATIBILITY.md), [`AGENTS.md`](..\u002F..\u002F..\u002FAGENTS.md), or visible practice in the corpus, it's something the author made up. Either find the authoritative anchor or surface the gap (the human docs need a section) — don't fabricate one in the skill.\n3. **Overlapping an existing skill.** Skills drift toward each other if the author hasn't read the existing surface. Before drafting, scan every `When to use this skill` block — both `Use it for` and `Don't use it for` — and decide whether your scope fits inside an existing skill, extends one, or needs its own (see \"Granularity heuristics\" below).\n4. **Frontmatter `description:` that doesn't include the natural-language trigger phrases.** The `description:` is the discovery surface a loader \u002F agent matches against. If the skill covers \"first-pass triage of JIRA issues,\" that phrase should appear verbatim. Don't be cute — match the language a user would type.\n5. **Missing or vague `Don't use it for` list.** Every existing skill has one and it is load-bearing — it tells the loader to stop here and *also* names the adjacent skill that should be loaded instead. A skill without explicit out-of-scope items drifts into being loaded for tasks it doesn't fit.\n6. **Cross-links to skills that don't exist.** Every `[label](..\u002F\u003Cname>\u002FSKILL.md)` must resolve to a real file. If you find yourself about to write \"see `groovy-foo`\" and `groovy-foo` doesn't exist yet, either author `groovy-foo` first or rephrase to a non-link.\n7. **Validation checklist that re-summarises the procedure.** The checklist should be a *test* the skill applies to its own output — outcomes phrased as yes\u002Fno questions — not a recap of the steps. If \"run `.\u002Fgradlew test`\" is procedure step 5, the checklist item is \"targeted test run is green,\" not \"ran the test.\"\n8. **Mandates without an anchor citation.** \"Always use X\" with no link to where X is documented as the project norm leaves a future author with no way to defend or update the rule. Cite the authoritative source so the next person knows where the rule lives.\n9. **Drafting a skill before the convention exists in the codebase.** A skill is the *working surface* — it describes what the project does, not what it should do. If the procedure you're encoding isn't actually project practice yet, propose the change first (on `dev@`), get it adopted, *then* write the skill. Skills are not a vehicle for unilateral policy changes.\n10. **Granularity drift.** \"How to rename a Groovy method\" is too narrow (it's a section of [`groovy-internals`](..\u002Fgroovy-internals\u002FSKILL.md)); \"all of Groovy contribution\" is too broad (that's [`AGENTS.md`](..\u002F..\u002F..\u002FAGENTS.md)). See \"Granularity heuristics.\"\n11. **Forgetting `AGENTS.md`.** A new skill that isn't listed in [`AGENTS.md`](..\u002F..\u002F..\u002FAGENTS.md)'s `## Skills` table is invisible to the loader and to humans browsing the repo. Removed skills mean removed rows. Updates to scope description happen there too.\n12. **Skills that aren't an example of themselves.** Especially this one: if a meta-skill can't be read as an example of the conventions it claims, the conventions are weaker than it says. Same trap for any procedural skill — a `groovy-tests` that doesn't itself follow the test conventions it teaches is a tell.\n13. **Marketing tone, emojis, hype.** None of the existing skills use them. The voice is terse, opinionated, cites paths and commands. \"? Welcome to the X skill!\" is a tell the convention has been broken.\n14. **Verbose introductions.** Existing skills open with one short paragraph that *positions the skill against its neighbours* — what it is, what to pair with, what to hand off to. Anything longer than ~5 lines before `## When to use this skill` is over-introduced.\n15. **Putting universal contributor content in a skill instead of a human-facing doc.** If a rule applies equally to a human contributor making the same change — TDD ordering, scope discipline, JIRA conventions, codebase-specific gotchas, build mechanics — its canonical home is `CONTRIBUTING.md`, `ARCHITECTURE.md`, or another human-facing doc (or a subproject-local `ARCHITECTURE.md` for subproject-specific complexity). The skill cites the convention and adds the AI-specific guardrails on top. Trapping universal content in skill-only form makes the project's conventions invisible to humans browsing the repo and creates an AI-mediated literacy requirement for contributing — see *Skills are the AI layer over canonical docs* below.\n\n## Skills are the AI layer over canonical docs\n\n**Conventions are written for humans. Skills operationalise them\nfor AI.**\n\nA convention's canonical home is a human-facing document at the\nrepository root or — for subproject-local complexity — alongside\nthe subproject's source. Skills cite the convention, sequence it\ninto AI-suitable procedures, and add the AI-specific guardrails\n(hand-back contracts, autonomy limits, no-fabrication rules). If\na rule could equally apply to a human contributor making the\nsame change, the rule belongs in a human doc — the skill is its\noperational shadow, not its origin.\n\nHuman-facing canonical docs in this project:\n\n- [`CONTRIBUTING.md`](..\u002F..\u002F..\u002FCONTRIBUTING.md) — workflow,\n  tests, JIRA conventions, triage methodology, fix workflow,\n  test-writing pitfalls.\n- [`ARCHITECTURE.md`](..\u002F..\u002F..\u002FARCHITECTURE.md) — compilation\n  pipeline, compiler\u002Fruntime conventions, build infrastructure,\n  public API boundaries.\n- [`COMPATIBILITY.md`](..\u002F..\u002F..\u002FCOMPATIBILITY.md) — stability\n  tiers, deprecation policy, binary-compatibility check.\n- [`GOVERNANCE.md`](..\u002F..\u002F..\u002FGOVERNANCE.md) — project\n  governance, mailing lists, JIRA's role.\n- [`AGENTS.md`](..\u002F..\u002F..\u002FAGENTS.md) — AI-contributor policy,\n  `Assisted-by:` convention, the \"what *not* to do\" list.\n- Subproject-local `ARCHITECTURE.md` when a subproject has\n  significant local complexity — e.g.\n  [`subprojects\u002Fgroovy-groovysh\u002FARCHITECTURE.md`](..\u002F..\u002F..\u002Fsubprojects\u002Fgroovy-groovysh\u002FARCHITECTURE.md)\n  for the vendored JLine forks and terminal-aware tests.\n\n**The test for any rule you're considering writing into a\nskill:** would a human contributor making the same change\nbenefit from this rule? If yes, find or create its canonical\nhome in a human doc; the skill should cite the rule, not\nrestate it. AI-specific constraints (autonomy limits, hand-back\ncontracts, no autonomous JIRA comments, no autonomous PRs) are\ndifferent — they belong in skills because they don't apply to\nhumans, who can't take those actions on autopilot anyway.\n\nThis split keeps conventions discoverable to humans (no\nAI-mediated literacy requirement), keeps skills focused on\nAI-specific concerns, and means the project's docs remain\nauthoritative if the AI tooling ecosystem changes.\n\nWorked examples in the corpus, each demonstrating the pattern:\n\n- **JIRA mechanics:** canonical in\n  [`CONTRIBUTING.md`'s \"Working with JIRA\" section](..\u002F..\u002F..\u002FCONTRIBUTING.md#working-with-jira);\n  AI guardrails in [`groovy-jira`](..\u002Fgroovy-jira\u002FSKILL.md).\n- **Triage methodology:** canonical in\n  [`CONTRIBUTING.md`'s \"Triaging\" section](..\u002F..\u002F..\u002FCONTRIBUTING.md#triaging-issues-and-pull-requests);\n  AI guardrails in [`groovy-triage`](..\u002Fgroovy-triage\u002FSKILL.md).\n- **Fix workflow:** canonical in\n  [`CONTRIBUTING.md`'s \"Fix workflow\" section](..\u002F..\u002F..\u002FCONTRIBUTING.md#fix-workflow);\n  AI guardrails in\n  [`groovy-fix-workflow`](..\u002Fgroovy-fix-workflow\u002FSKILL.md).\n- **Test conventions and pitfalls:** canonical in\n  [`CONTRIBUTING.md`'s \"Tests\" section](..\u002F..\u002F..\u002FCONTRIBUTING.md#tests);\n  AI guardrails in [`groovy-tests`](..\u002Fgroovy-tests\u002FSKILL.md).\n- **Build infrastructure:** canonical in\n  [`ARCHITECTURE.md`'s \"Build infrastructure\" section](..\u002F..\u002F..\u002FARCHITECTURE.md#build-infrastructure);\n  AI guardrails in [`groovy-build`](..\u002Fgroovy-build\u002FSKILL.md).\n- **Compiler\u002Fruntime conventions:** canonical in\n  [`ARCHITECTURE.md`'s \"Compiler and runtime conventions\" section](..\u002F..\u002F..\u002FARCHITECTURE.md#compiler-and-runtime-conventions);\n  AI guardrails in\n  [`groovy-internals`](..\u002Fgroovy-internals\u002FSKILL.md).\n- **Subproject-local (groovysh):** canonical in\n  [`subprojects\u002Fgroovy-groovysh\u002FARCHITECTURE.md`](..\u002F..\u002F..\u002Fsubprojects\u002Fgroovy-groovysh\u002FARCHITECTURE.md);\n  AI guardrails in [`groovysh`](..\u002Fgroovysh\u002FSKILL.md).\n\nTwo skills in the corpus have no canonical-doc analog because\nthey're AI-procedural-only:\n[`groovy-reproducer`](..\u002Fgroovy-reproducer\u002FSKILL.md) (reproducer\nextraction shape taxonomy, evidence packages, batch state\ncleanup) and [`groovy-reassess`](..\u002Fgroovy-reassess\u002FSKILL.md)\n(bulk-reassessment campaign mechanics, classification taxonomy,\nresumable session state). Humans don't formalise these as\ndiscrete activities; the skills exist because AI makes them\ntractable at scale. That's the legitimate \"skill is the home\"\ncase — when the activity itself has no human-side analog, not\nwhen the convention does but you skipped promoting it.\n\n## Conventions\n\n### Directory layout\n\n```\n.agents\u002Fskills\u002F\n├── \u003Cskill-name>\u002F\n│   └── SKILL.md\n```\n\nOne directory per skill, even when `SKILL.md` is the only file. The directory leaves room for examples, scripts, or supporting documents the skill links to. The skill name is kebab-case and usually follows the `groovy-\u003Carea>` pattern, except for single-word names that are already canonical project terms (e.g. `groovysh`).\n\n### License header\n\nEvery `SKILL.md` opens with the ASF license header as an HTML comment, identical in wording to the existing skills. Copy from any existing skill — do not paraphrase.\n\n### Frontmatter\n\n```yaml\n---\nname: \u003Ckebab-case, matches directory name>\ndescription: \u003Cone or more sentences naming the scope, with the natural-language trigger phrases a loader would match against. Mention the files\u002Fpaths the skill applies to. Use when ... is a common closing pattern.>\nlicense: Apache-2.0\ncompatibility: claude, codex, copilot, cursor, gemini, aider\nmetadata:\n  audience: contributors to apache\u002Fgroovy\n  scope: \u003Cshort identifier of the skill's subject area>\n---\n```\n\nThe `compatibility` list is the set of CLIs the skill is intended to work with. The Groovy corpus declares all six; if a skill is known *not* to work with one, drop it (and note the reason in a comment outside the frontmatter).\n\n### Section order\n\nThe canonical order is:\n\n1. `# \u003CTitle>` — the skill name rendered as words (e.g. `Groovy tests`, not `groovy-tests`).\n2. **Opening paragraph (≤5 lines).** What this skill is, what to pair with, what to hand off to. Not a marketing intro — a positional one.\n3. *Optional but encouraged for workflow \u002F mechanics skills:* **a short bullet list of related-skill pointers**, each naming the relationship (*pair with* \u002F *defers to … for mechanics* \u002F *hand off to* \u002F *sister skill* \u002F *exemplar for*). The newer corpus members (`groovy-triage`, `groovy-jira`, `groovy-fix-workflow`, `groovy-reproducer`, `groovy-reassess`, and this skill) open this way; older skills predate the pattern and would benefit from being retrofitted. Skip the list if the skill is fully self-contained and has no meaningful relationships to surface.\n4. `## When to use this skill` with **Use it for:** and **Don't use it for:** bullet lists.\n5. `## Read first` — pointers to authoritative docs (root or subproject `AGENTS.md`, `CONTRIBUTING.md`, `GOVERNANCE.md`, `ARCHITECTURE.md`, `COMPATIBILITY.md`, external specs). Frames the skill as the working surface and those documents as the map.\n6. `## Top failure modes` — numbered, each with a **bold one-line name** followed by an explanation.\n7. *Optional* **reference sections** — zero or more named sections (e.g. `## Conventions`, `## Granularity heuristics`, a field-ownership table) that define the rules the procedures will defer to. Use when the rules don't fit inline in the procedure steps without bloating them. Skip if the procedures can carry the rules directly.\n8. `## Procedure` (single flow) or one or more `## Procedure for …` sections (when the skill has more than one distinct flow) — step-by-step, with commands and file references. Use the `for …` suffix only when disambiguation between flows matters.\n9. `## Validation checklist` — literal `- [ ]` checkboxes; outcomes phrased as yes\u002Fno.\n10. `## References` — cross-links to other skills (with relationship described: \"sister skill,\" \"pair with,\" \"hand off to,\" \"defers to this skill for X\") and external docs.\n\nA section may be omitted only when it would be empty after honest filling — e.g. a deeply niche skill might have no separate `Procedure` section because the entire skill is failure-modes-and-checklist. Don't pad sections to keep the order, and don't insert reference sections that just restate the procedure.\n\n### Cross-linking\n\nEvery cross-skill reference names the relationship. Patterns the corpus uses:\n\n- \"**sister skill**\" — peer in scope; pair when both apply.\n- \"**pair with**\" — load alongside this one for the typical workflow.\n- \"**hand off to**\" — finish this skill's role here, switch to the other.\n- \"**defers to … for mechanics**\" — this skill's procedure uses the other's vocabulary.\n\nA bare hyperlink with no relationship hint is a smell.\n\nFailure-mode references — within a skill or across skills — cite the failure mode's **italicised bold lead-in name**, never the position number. The number is unstable: renumbering a skill's failure-mode list silently breaks every numeric citation, here and elsewhere in the corpus. The name is the failure mode's identity, survives reordering, and lets a reader `Ctrl-F` to the entry. Example: \"See *Inventing `Fix Version\u002Fs`* in [`groovy-jira`](..\u002Fgroovy-jira\u002FSKILL.md)\" — not \"see failure mode 2 in groovy-jira\".\n\n### Voice\n\nProcedure and instruction text uses imperative \u002F infinitive form — verb-first (\"Run the targeted test\", \"To classify an issue, …\"), not second person (\"You should run …\"). A `SKILL.md` is read by another agent, not a human reader; the imperative form is terser and generalises better across models and prompt styles. The corpus already follows this; match it.\n\n## Granularity heuristics\n\nWhen deciding whether a topic is its own skill or a section of an existing one:\n\n**Make it its own skill if** (any of):\n\n- Other skills will want to defer to it from inside their procedure (the deferral test — this is what motivated splitting [`groovy-jira`](..\u002Fgroovy-jira\u002FSKILL.md) out of [`groovy-triage`](..\u002Fgroovy-triage\u002FSKILL.md)).\n- The failure modes are distinct from neighbouring skills' (different mistakes, different anchor docs).\n- The procedure is self-contained enough that loading it alone is useful.\n- The scope corresponds to a directory or subsystem with its own conventions ([`groovysh`](..\u002Fgroovysh\u002FSKILL.md) is the worked example — a single subproject with enough internal weirdness to warrant its own skill).\n\n**Make it a section of an existing skill if** (any of):\n\n- It only ever runs as part of the parent skill's workflow.\n- The failure modes are intermixed with the parent's.\n- It's mostly mechanical with no judgement calls.\n- Splitting would force readers to load both skills together in practice — that's a hint the split is artificial.\n\n**Don't make it a skill if:**\n\n- The convention it describes doesn't yet exist in project practice (see *Drafting a skill before the convention exists in the codebase* above).\n- It's project-wide policy ([`AGENTS.md`](..\u002F..\u002F..\u002FAGENTS.md) territory) rather than area-specific procedure.\n\n## Procedure for adding a new skill\n\n1. **Read the corpus.** Open every existing skill's frontmatter and `When to use this skill` block. Confirm your scope doesn't already belong to one of them.\n2. **Apply the granularity heuristics.** Decide skill vs. section. If section: stop here and edit the parent skill instead.\n3. **Identify anchor docs.** Apply the *Skills are the AI layer over canonical docs* principle above: for each rule you'd put in the skill, decide whether its canonical home is `CONTRIBUTING.md`, `GOVERNANCE.md`, `AGENTS.md`, `ARCHITECTURE.md`, `COMPATIBILITY.md`, a subproject-local `ARCHITECTURE.md`, or an external spec. If a rule applies to a human contributor equally, its canonical home is a human-facing doc — promote it there first, and have the skill cite it. If a rule is genuinely AI-specific (autonomy limits, hand-back contracts, no-fabrication rules), it lives in the skill. If there's no anchor for a universal rule and no obvious place to put one, surface the gap (see *Drafting a skill before the convention exists in the codebase*) rather than fabricating one in the skill.\n4. **Anchor on three to five concrete invocation examples.** Before drafting any prose, write down how the skill will actually be invoked: what the user says, what the agent does in response, and what the apply\u002Fhand-back step is. Underspecified skills generate generic boilerplate; the examples are also where the `description:` trigger phrases come from (see *Frontmatter `description:` that doesn't include the natural-language trigger phrases* in the failure modes). Don't start writing without them.\n5. **Draft the frontmatter.** Include the natural-language trigger phrases in `description:` (derived from step 4's examples); match the existing `compatibility` and `metadata` shape.\n6. **Draft the failure-mode list.** Aim for 5+ concrete entries. If you can't reach 5 genuine ones, the skill is probably too narrow.\n7. **Draft the procedure(s).** Step-by-step with commands and file references. Match the surrounding skills' density — terse and opinionated.\n8. **Draft the validation checklist.** Outcomes, not steps. Each item answerable yes\u002Fno.\n9. **Cross-link.**\n   - Outbound: name the relationship at every link.\n   - Inbound: update the neighbouring skills that should mention this one in their `Don't use it for`, `References`, or failure-mode list. A new skill nobody points at is invisible.\n10. **Update [`AGENTS.md`](..\u002F..\u002F..\u002FAGENTS.md).** Add a row to the `## Skills` table, alphabetically. The table is whitespace-aligned for monospace readability; preserve the column padding when inserting the new row.\n11. **Self-consistency pass.** Read your skill as if you'd never seen it. Does it explain when to load it, what it's *not* for, and what to do? Does the validation checklist actually test the output, or just recap the steps?\n\n## Procedure for splitting an existing skill\n\nThe [`groovy-triage`](..\u002Fgroovy-triage\u002FSKILL.md) → [`groovy-jira`](..\u002Fgroovy-jira\u002FSKILL.md) extraction is the worked example.\n\n1. **Identify the deferral candidate.** A self-contained body of mechanics that other skills (current or anticipated) will want to defer to. If only one skill cares about it, it's probably a section, not a split.\n2. **Create the new skill.** Follow \"adding a new skill\" above.\n3. **Prune the source skill.**\n   - Replace the extracted procedure with a one-line pointer to the new skill.\n   - Remove failure modes now covered by the new skill, with a one-line \"see `\u003Cnew-skill>` for the rest.\"\n   - Update the source skill's `## References` to list the new skill.\n   - Update the source skill's validation checklist to defer where appropriate.\n4. **Add inbound link.** The new skill's `## References` points back at the source.\n5. **Update [`AGENTS.md`](..\u002F..\u002F..\u002FAGENTS.md).** Add the new row; revise the source row only if its scope description is now misleading.\n6. **Re-read both skills together.** A correct split reads naturally when loaded together; if it reads as redundant or as if something is missing, the split line is wrong.\n\n## Validation checklist\n\nBefore declaring a new or refactored skill ready:\n\n- [ ] ASF license header is present, copied (not paraphrased) from an existing skill.\n- [ ] License header closes with `-->` immediately before the `---` frontmatter delimiter (the common transcription typo is closing it with `---`).\n- [ ] Frontmatter has `name`, `description`, `license`, `compatibility`, `metadata.audience`, `metadata.scope`.\n- [ ] `name` matches the directory name.\n- [ ] `description` contains the natural-language trigger phrases an agent or loader would match against, derived from concrete invocation examples (not invented after the fact).\n- [ ] Procedure \u002F instruction text is in imperative \u002F infinitive voice, not second person.\n- [ ] Standard section order: opening paragraph, *(optional related-skill bullet list)*, `When to use`, `Read first`, `Top failure modes`, *(optional reference sections)*, `Procedure(s)`, `Validation checklist`, `References`.\n- [ ] Both **Use it for** and **Don't use it for** lists are populated, with at least one entry each.\n- [ ] Every failure mode names a specific observed or plausible mistake (not an aphorism).\n- [ ] Every internal `[label](..\u002F\u003Cname>\u002FSKILL.md)` link resolves to an actual file.\n- [ ] Failure-mode cross-references (within or across skills) cite the italicised lead-in name, not a position number.\n- [ ] Every mandate cites or links the authoritative source.\n- [ ] For each rule in the skill: would a human contributor making the same change benefit from it? If yes, the rule's canonical home is a human-facing doc (`CONTRIBUTING.md`, `ARCHITECTURE.md`, a subproject-local `ARCHITECTURE.md`, etc.); the skill cites it rather than restating it. AI-specific constraints (autonomy limits, hand-back contracts) stay in the skill.\n- [ ] Validation checklist tests outcomes, not steps.\n- [ ] Neighbouring skills that should reference this one have been updated (failure modes \u002F `Don't use it for` \u002F `References`).\n- [ ] Row added to (or removed from) the `## Skills` table in [`AGENTS.md`](..\u002F..\u002F..\u002FAGENTS.md), alphabetically.\n- [ ] No emojis, no marketing tone, no padding.\n- [ ] The skill is an example of itself — read cold, it would pass its own checklist.\n\n## References\n\n- [`AGENTS.md`](..\u002F..\u002F..\u002FAGENTS.md) — project-wide AI-contributor policy and the `## Skills` table this skill mutates.\n- [`groovy-build`](..\u002Fgroovy-build\u002FSKILL.md), [`groovy-fix-workflow`](..\u002Fgroovy-fix-workflow\u002FSKILL.md), [`groovy-internals`](..\u002Fgroovy-internals\u002FSKILL.md), [`groovy-jira`](..\u002Fgroovy-jira\u002FSKILL.md), [`groovy-reassess`](..\u002Fgroovy-reassess\u002FSKILL.md), [`groovy-reproducer`](..\u002Fgroovy-reproducer\u002FSKILL.md), [`groovy-tests`](..\u002Fgroovy-tests\u002FSKILL.md), [`groovy-triage`](..\u002Fgroovy-triage\u002FSKILL.md), [`groovysh`](..\u002Fgroovysh\u002FSKILL.md) — the corpus this skill describes and the canonical source for any convention it leaves under-specified.\n- The `groovy-triage` ↔ `groovy-jira` split — worked example of the \"Procedure for splitting an existing skill\" above.\n",{},"master","4ab67ec26055b11dc3c98a4a350020b99fecd8bd",".agents\u002Fskills\u002Fgroovy-skills",1914,"https:\u002F\u002Fgithub.com\u002Fapache\u002Fgroovy","https:\u002F\u002Fgroovy-lang.org","https:\u002F\u002Fgithub.com\u002Fapache","https:\u002F\u002Fwww.apache.org\u002F","2026-11-15 01:42:11",{"source":7,"skillName":5,"commands":34,"prompt":44,"zipAvailable":45},[35,38,41],{"tool":36,"command":37},"npx","npx skills add apache\u002Fgroovy --skill groovy-skills",{"tool":39,"command":40},"bunx","bunx skills add apache\u002Fgroovy --skill groovy-skills",{"tool":42,"command":43},"pnpm","pnpm dlx skills add apache\u002Fgroovy --skill groovy-skills","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fapache\u002Fgroovy\u002Fblob\u002Fmaster\u002F.agents\u002Fskills\u002Fgroovy-skills\u002FSKILL.md",true,[],[48,54,62,70,78,86],{"skillNo":49,"name":50,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":51,"categories":52,"keywords":53,"publishedAt":20},"01M6ACEDS969D6ZXE8SGZSPR3B","groovysh","https:\u002F\u002Fgithub.com\u002Fapache\u002Fgroovy\u002Fblob\u002Fmaster\u002F.agents\u002Fskills\u002Fgroovysh\u002FSKILL.md",[],[50],{"skillNo":55,"name":56,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":57,"categories":58,"keywords":59,"publishedAt":20},"01M6ACEBR5V55F0X8YS9EJGRW2","groovy-triage","https:\u002F\u002Fgithub.com\u002Fapache\u002Fgroovy\u002Fblob\u002Fmaster\u002F.agents\u002Fskills\u002Fgroovy-triage\u002FSKILL.md",[],[60,18,61],"triage","groovy triage",{"skillNo":63,"name":64,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":65,"categories":66,"keywords":67,"publishedAt":20},"01M6ACE9Y7AFJV4ZERD6WPF8QS","groovy-tests","https:\u002F\u002Fgithub.com\u002Fapache\u002Fgroovy\u002Fblob\u002Fmaster\u002F.agents\u002Fskills\u002Fgroovy-tests\u002FSKILL.md",[],[18,68,69],"groovy tests","tests",{"skillNo":71,"name":72,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":73,"categories":74,"keywords":75,"publishedAt":20},"01M6ACE5BJCXWJPMZD0M12H3D5","groovy-reproducer","https:\u002F\u002Fgithub.com\u002Fapache\u002Fgroovy\u002Fblob\u002Fmaster\u002F.agents\u002Fskills\u002Fgroovy-reproducer\u002FSKILL.md",[],[18,76,77],"groovy reproducer","reproducer",{"skillNo":79,"name":80,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":81,"categories":82,"keywords":83,"publishedAt":20},"01M6ACE2M14SX17HE4JKR57DCC","groovy-reassess","https:\u002F\u002Fgithub.com\u002Fapache\u002Fgroovy\u002Fblob\u002Fmaster\u002F.agents\u002Fskills\u002Fgroovy-reassess\u002FSKILL.md",[],[18,84,85],"groovy reassess","reassess",{"skillNo":87,"name":88,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":89,"categories":90,"keywords":91,"publishedAt":20},"01M6ACDZWW85YHH8R4CMK1P5G3","groovy-jira","https:\u002F\u002Fgithub.com\u002Fapache\u002Fgroovy\u002Fblob\u002Fmaster\u002F.agents\u002Fskills\u002Fgroovy-jira\u002FSKILL.md",[],[92,18,93],"jira","groovy jira"]