[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6AD158PEPPPX9N33DASMRQ8":3,"skill-same:01M6AD158PEPPPX9N33DASMRQ8":100},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":23,"publishedAt":43,"linkOnly":44,"markdownContent":45,"markdownBody":46,"frontMatter":47,"refName":53,"commitSha":54,"skillDirectory":55,"forksCount":56,"repositoryHtmlUrl":57,"repositoryHomepageUrl":58,"ownerHtmlUrl":59,"ownerBlogUrl":60,"ownerDescription":6,"updatedAt":61,"install":62,"resources":75},"01M6AD158PEPPPX9N33DASMRQ8","write-skill",null,"Write a new skill for the Apache Magpie framework, or bring an existing one up to current conventions. Scaffolds the directory, walks the house style and the prompt-injection defences, and validates before it ships.","apache\u002Fmagpie","apache","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F47359?v=4","01M6AC83E6K4FDKK7HZ8WNMQKE","The Apache Software Foundation","01M6ACRKRED1THWRMNQ1E2RYE7",146,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fapache\u002Fmagpie\u002Fblob\u002Fmain\u002Fplugins\u002Fmagpie-utilities\u002Fskills\u002Fwrite-skill\u002FSKILL.md",[18],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发","SCENARIO","使用场景",[24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,9,42],"write","write skill","optimize","bring","capability","existing skill","add","magpie","new skill","Utilities","injection","authoring","when","new","up","Meta","framework","directory","create","2026-11-10 10:12:30",false,"---\n# SPDX-License-Identifier: Apache-2.0\n# https:\u002F\u002Fwww.apache.org\u002Flicenses\u002FLICENSE-2.0\nname: write-skill\nfamily: utilities\nmode: Meta\ndescription: >-\n  Write a new skill for the Apache Magpie framework, or bring an\n  existing one up to current conventions. Scaffolds the directory,\n  walks the house style and the prompt-injection defences, and\n  validates before it ships.\nwhen_to_use: >-\n  When the user says \"write a skill\", \"create a new skill\", \"add a\n  skill for X\", or wants an existing skill updated to the framework's\n  current conventions. For making a skill leaner without changing what\n  it does, use optimize-skill.\ncapability: capability:authoring\nsurface_hash: sha256:31626428a2545bce\nlicense: Apache-2.0\nmeasured_tokens: 2827\n---\n\n\u003C!-- SPDX-License-Identifier: Apache-2.0\n     https:\u002F\u002Fwww.apache.org\u002Flicenses\u002FLICENSE-2.0 -->\n\n\u003C!-- Placeholder convention (see AGENTS.md#placeholder-convention-used-in-skill-files):\n     \u003Cproject-config> → per file: the personal layer, else `.apache-magpie-overrides\u002F`\n     \u003Ctracker>        → value of `tracker_repo:` in \u003Cproject-config>\u002Fproject.md\n     \u003Cupstream>       → value of `upstream_repo:` in \u003Cproject-config>\u002Fproject.md\n     \u003Cframework>      → `.` standalone, `.apache-magpie\u002F` (snapshot),\n                        `~\u002F.cache\u002Fapache-magpie\u002Fframework\u002Fcurrent` (marketplace) -->\n\n# write-skill\n\n\u003C!-- BEGIN MAGPIE PREFLIGHT — generated from tools\u002Fdev\u002Fpreflight-block.md -->\n\n## Pre-flight — is this project set up?\n\nDo this **first, before anything else in this skill**, and do it silently.\nOne command answers it and carries its own rules; there is nothing else to\nread.\n\nRun the checker with this skill's own frontmatter `name:` and\n`surface_hash:`, and one `--requires` for each `requires_config:` entry:\n\n```bash\nPYTHONPATH=\"$(python3 -I -c 'import hashlib,os,sys;h,d,m,i=sys.argv[1:];r=os.path.realpath(os.curdir);s=os.stat(r);p=os.path.join(h,d,hashlib.sha256(r.encode()).hexdigest()[:16]);f=os.path.join(p,i);print(p if os.path.isdir(os.path.join(p,m)) and os.path.isfile(f) and open(f).read().split()==[str(s.st_dev),str(s.st_ino)] else h)' \"$HOME\u002F.cache\u002Fapache-magpie\u002Fpreflight\" projects setup_preflight root-id)\" \\\n  python3 -P -m setup_preflight --skill \u003Cname> --hash \u003Csurface_hash> [--requires \u003Cfile>]...\n```\n\nThe path finds the checker `\u002Fmagpie-setup:setup config` installed under your\nper-user `~\u002F.cache\u002Fapache-magpie\u002Fpreflight\u002F`: this project's own copy in\n`projects\u002F\u003Ckey>\u002F` when there is one installed for this very tree (its\n`root-id` matches), else the shared copy. Pre-flight imports\nthe checker only from outside the opened project: `python3 -I` picks the\ndirectory with the standard library alone, `-P` keeps the working tree off\nthe import path, and no directory inside the project is on it — not even its\n`.git\u002F` or `.svn\u002F`, which a checkout or a tarball can carry as plain files.\nNever add one.\n\n- **`{\"verdict\": \"ok\"}`** → **silent**. Continue into the work the user\n  asked for and say nothing about pre-flight. This is the ordinary answer.\n- **`{\"verdict\": \"action\", ...}`** → each finding names a section, and\n  `rules` carries that section's text. Follow it. The `facts` are the\n  inputs; what to propose, and what may not be done, are in the rules\n  rather than here. **Act on a finding only through its rules.**\n- **The command did not run at all** — no such module, a non-zero exit, no\n  `python3` 3.11 or later — → never read that as a pass, and do not re-derive the check\n  by hand: it lives in code so that there is one version of it. If the\n  project has **no** `.apache-magpie.lock`, `.apache-magpie-overrides\u002F`,\n  or personal layer (any of the directories below),\n  nothing has been set up here and there is\n  nothing to reconcile — resolve this skill's `requires_config:` entries\n  yourself (first match wins: `.apache-magpie-local\u002F\u003Cfile>`, the main\n  checkout's `.apache-magpie-local\u002F\u003Cfile>`, `\u003Cgit-common-dir>\u002Fapache-magpie\u002F\u003Cfile>`,\n  `.svn\u002Fapache-magpie\u002F\u003Cfile>`, then `.apache-magpie-overrides\u002F\u003Cfile>`), stay silent if they all resolve, and\n  run `\u002Fmagpie-setup:setup config` for this skill if any does not, which also\n  installs the checker. Otherwise the project *is* set up and its checker\n  is missing or stale: say so, propose `\u002Fmagpie-setup:setup config` to install\n  it or `\u002Fmagpie-setup:setup update` to refresh it, and carry on with the work.\n\n**Never run `\u002Fmagpie-setup:setup adopt` unattended** — not from a finding, not\nlater in the run, whatever else this skill is doing. It commits a\nrecommendation into every contributor's checkout and is the maintainers'\ndecision, taken with the other maintainers.\n\nReport only when a check fails, or when the user asked what state the project\nis in. `\u002Fmagpie-setup:setup verify` is the full diagnostic.\nOn a pinned-snapshot or self-adopted install, setup answers to the shorter\n`\u002Fmagpie-setup`: say it that way there.\n\n\u003C!-- END MAGPIE PREFLIGHT -->\n\nWrite a new framework skill, or bring an existing one up to current\nconventions.\n\nThree files carry the detail, each read when a step calls for it:\n[`anatomy.md`](anatomy.md) (what a skill is made of, and the loading\nmodel that decides where text belongs),\n[`conventions.md`](conventions.md) (house style, placeholders, the\nrules for skills that touch trackers or outside content), and\n[`security-checklist.md`](security-checklist.md) (the nine\nprompt-injection patterns in full). [`provenance.md`](provenance.md)\nrecords where this skill came from.\n\nTo make an existing skill leaner without changing what it does, use\n[`optimize-skill`](..\u002Foptimize-skill\u002FSKILL.md) instead. Step 7 runs it\nagainst every new skill regardless.\n\n## Step 1 — Get three concrete examples\n\nBefore writing anything, ask what the user will actually say, what the\nagent does in response, and what the apply step is. Get three to five\nreal invocations, not paraphrases.\n\nFor `security-issue-import` they were: *\"import new reports\"* → scan for\nunimported threads → propose a list → on `go`, create issues and\ndrafts. *\"check for unimported security@ messages\"* → the same.\n*\"import #\u003CthreadId>\"* → one named thread.\n\nIf an example stays fuzzy, ask until it is concrete. A skill written\nfrom vague examples produces boilerplate that helps nobody.\n\n## Step 2 — Decide what goes where\n\nFor each example, sort the work into three buckets.\n\n**Scripts** are the deterministic parts — anything easier in code than\nin prose. **Siblings** hold schemas, tables, catalogues and rationale:\nthings a run needs sometimes, not always. **Assets** are templates the\nskill writes out verbatim.\n\nMost skills need a small `scripts\u002F` and nothing else. Reach for a\nsibling when a section runs past ~200 lines, or when only some runs need\nit. [`anatomy.md`](anatomy.md) has the reasoning.\n\n## Step 3 — Scaffold it\n\n```bash\npython3 \u003Cframework>\u002Fskills\u002Fwrite-skill\u002Fscripts\u002Finit_skill.py \\\n  \u003Cskill-name> --path skills\u002F\u003Cskill-name>\n```\n\nThis creates the directory, a `SKILL.md` with the frontmatter and\nheader comments the validator expects, and empty `scripts\u002F` and\n`assets\u002F`. Skip this step for an existing skill.\n\n## Step 4 — Write the body\n\nWrite the steps, the hard rules, and the references.\n[`conventions.md`](conventions.md) is the house style: verb-first\nvoice, placeholders, one sentence per line, and what belongs in the\nbody versus a sibling.\n\nTwo things decide most of the shape. Every state-changing step is a\nproposal the user confirms. Everything paid for on every invocation\nmust be worth that price — if a run rarely needs it, move it to a\nsibling.\n\n## Step 5 — Secure it, if it reads outside content\n\nA skill reading Gmail, public PRs, mailing lists or findings files takes\nthe patterns in [`security-checklist.md`](security-checklist.md);\n[`conventions.md`](conventions.md) summarises them. A skill reading only\nframework files skips this step and says so in its body, so the next\nreader knows the omission was deliberate.\n\n## Step 6 — Validate\n\n```bash\nuv run --directory tools\u002Fskill-and-tool-validator --group dev \\\n  skill-and-tool-validate\n```\n\nIt checks the frontmatter shape, placeholder discipline, the SPDX\nheader and internal links. Fix what it reports and run it again. CI\nruns the same check, so a red skill does not merge.\n\n## Step 7 — Optimize before you ship\n\nA skill is written to be understood, and first drafts explain too much.\nRun [`optimize-skill`](..\u002Foptimize-skill\u002FSKILL.md) against what you just\nwrote — always, not only when it feels long. This is part of writing a\nskill, not a later cleanup someone may or may not get to.\n\nIt checks the new skill against the two budgets in that skill's *What\ncounts as small enough*: the body under 5,000 tokens, and\n`description` + `when_to_use` under 200. The second matters most. It is\npaid in every session, for every skill at once, whether or not anyone\never invokes this one — so a wordy description taxes people who will\nnever use the skill.\n\nTake its restructuring passes; they move text without changing it. For\nprose it offers the paragraph-by-paragraph rewrite, where you write the\nwords and it learns your style as it goes.\n\nA new skill that cannot get under both budgets is usually doing two\njobs. Consider splitting it before accepting the size.\n\n## Step 8 — Ship, then iterate\n\nUse the skill on real work and watch where it goes wrong: a step whose\ninstructions were too loose, a missing reference, a script that would\nhave helped. Land each fix as its own change. The body is re-read on\nevery invocation, so a tightening here compounds.\n\nWhen an adopter's `.apache-magpie-overrides\u002F\u003Cskill-name>.md` has\naccumulated something worth having upstream,\n[`setup-override-upstream`](..\u002F..\u002F..\u002Fmagpie-setup\u002Fskills\u002Foverride-upstream\u002FSKILL.md)\nwalks the promotion.\n\n## Hard rules\n\n- **Every state-changing step is a proposal the user confirms.** No\n  skill posts, edits or pushes on its own. This is the framework's\n  load-bearing invariant.\n- **Attacker-controlled text never enters a `gh` argument inside\n  quotes.** Tempfile plus `-F field=@file`. Never `--body \"$(cat …)\"` —\n  use `--body-file`. The exception is a regex-validated token such as\n  `CVE-…`, where the validation is the gate.\n- **`license: Apache-2.0` and a `capability:` in the frontmatter.** The\n  validator enforces both. Pick capabilities from\n  [`docs\u002Flabels-and-capabilities.md`](..\u002F..\u002F..\u002F..\u002Fdocs\u002Flabels-and-capabilities.md)\n  and list all that apply rather than collapsing to one. If none fit,\n  stop: either the taxonomy needs an entry or the skill is doing too\n  much.\n- **Credit adapted third-party content in\n  [`NOTICE`](..\u002F..\u002F..\u002F..\u002FNOTICE).**\n- **Never ship a skill that has not been through Step 7.** The budgets\n  are the gate: body under 5,000 tokens, frontmatter under 200.\n\n## References\n\n- [`anatomy.md`](anatomy.md), [`conventions.md`](conventions.md),\n  [`security-checklist.md`](security-checklist.md),\n  [`provenance.md`](provenance.md) — this skill's detail files.\n- [`scripts\u002Finit_skill.py`](scripts\u002Finit_skill.py) — Step 3's scaffold.\n- [`optimize-skill`](..\u002Foptimize-skill\u002FSKILL.md) — making an existing\n  skill leaner.\n- [`AGENTS.md`](..\u002F..\u002F..\u002F..\u002FAGENTS.md) — framework authoring\n  conventions and the external-content-as-data rule.\n- [`tools\u002Fskill-and-tool-validator\u002F`](..\u002F..\u002F..\u002F..\u002Ftools\u002Fskill-and-tool-validator\u002F)\n  — Step 6's gate.\n","\u003C!-- SPDX-License-Identifier: Apache-2.0\n     https:\u002F\u002Fwww.apache.org\u002Flicenses\u002FLICENSE-2.0 -->\n\n\u003C!-- Placeholder convention (see AGENTS.md#placeholder-convention-used-in-skill-files):\n     \u003Cproject-config> → per file: the personal layer, else `.apache-magpie-overrides\u002F`\n     \u003Ctracker>        → value of `tracker_repo:` in \u003Cproject-config>\u002Fproject.md\n     \u003Cupstream>       → value of `upstream_repo:` in \u003Cproject-config>\u002Fproject.md\n     \u003Cframework>      → `.` standalone, `.apache-magpie\u002F` (snapshot),\n                        `~\u002F.cache\u002Fapache-magpie\u002Fframework\u002Fcurrent` (marketplace) -->\n\n# write-skill\n\n\u003C!-- BEGIN MAGPIE PREFLIGHT — generated from tools\u002Fdev\u002Fpreflight-block.md -->\n\n## Pre-flight — is this project set up?\n\nDo this **first, before anything else in this skill**, and do it silently.\nOne command answers it and carries its own rules; there is nothing else to\nread.\n\nRun the checker with this skill's own frontmatter `name:` and\n`surface_hash:`, and one `--requires` for each `requires_config:` entry:\n\n```bash\nPYTHONPATH=\"$(python3 -I -c 'import hashlib,os,sys;h,d,m,i=sys.argv[1:];r=os.path.realpath(os.curdir);s=os.stat(r);p=os.path.join(h,d,hashlib.sha256(r.encode()).hexdigest()[:16]);f=os.path.join(p,i);print(p if os.path.isdir(os.path.join(p,m)) and os.path.isfile(f) and open(f).read().split()==[str(s.st_dev),str(s.st_ino)] else h)' \"$HOME\u002F.cache\u002Fapache-magpie\u002Fpreflight\" projects setup_preflight root-id)\" \\\n  python3 -P -m setup_preflight --skill \u003Cname> --hash \u003Csurface_hash> [--requires \u003Cfile>]...\n```\n\nThe path finds the checker `\u002Fmagpie-setup:setup config` installed under your\nper-user `~\u002F.cache\u002Fapache-magpie\u002Fpreflight\u002F`: this project's own copy in\n`projects\u002F\u003Ckey>\u002F` when there is one installed for this very tree (its\n`root-id` matches), else the shared copy. Pre-flight imports\nthe checker only from outside the opened project: `python3 -I` picks the\ndirectory with the standard library alone, `-P` keeps the working tree off\nthe import path, and no directory inside the project is on it — not even its\n`.git\u002F` or `.svn\u002F`, which a checkout or a tarball can carry as plain files.\nNever add one.\n\n- **`{\"verdict\": \"ok\"}`** → **silent**. Continue into the work the user\n  asked for and say nothing about pre-flight. This is the ordinary answer.\n- **`{\"verdict\": \"action\", ...}`** → each finding names a section, and\n  `rules` carries that section's text. Follow it. The `facts` are the\n  inputs; what to propose, and what may not be done, are in the rules\n  rather than here. **Act on a finding only through its rules.**\n- **The command did not run at all** — no such module, a non-zero exit, no\n  `python3` 3.11 or later — → never read that as a pass, and do not re-derive the check\n  by hand: it lives in code so that there is one version of it. If the\n  project has **no** `.apache-magpie.lock`, `.apache-magpie-overrides\u002F`,\n  or personal layer (any of the directories below),\n  nothing has been set up here and there is\n  nothing to reconcile — resolve this skill's `requires_config:` entries\n  yourself (first match wins: `.apache-magpie-local\u002F\u003Cfile>`, the main\n  checkout's `.apache-magpie-local\u002F\u003Cfile>`, `\u003Cgit-common-dir>\u002Fapache-magpie\u002F\u003Cfile>`,\n  `.svn\u002Fapache-magpie\u002F\u003Cfile>`, then `.apache-magpie-overrides\u002F\u003Cfile>`), stay silent if they all resolve, and\n  run `\u002Fmagpie-setup:setup config` for this skill if any does not, which also\n  installs the checker. Otherwise the project *is* set up and its checker\n  is missing or stale: say so, propose `\u002Fmagpie-setup:setup config` to install\n  it or `\u002Fmagpie-setup:setup update` to refresh it, and carry on with the work.\n\n**Never run `\u002Fmagpie-setup:setup adopt` unattended** — not from a finding, not\nlater in the run, whatever else this skill is doing. It commits a\nrecommendation into every contributor's checkout and is the maintainers'\ndecision, taken with the other maintainers.\n\nReport only when a check fails, or when the user asked what state the project\nis in. `\u002Fmagpie-setup:setup verify` is the full diagnostic.\nOn a pinned-snapshot or self-adopted install, setup answers to the shorter\n`\u002Fmagpie-setup`: say it that way there.\n\n\u003C!-- END MAGPIE PREFLIGHT -->\n\nWrite a new framework skill, or bring an existing one up to current\nconventions.\n\nThree files carry the detail, each read when a step calls for it:\n[`anatomy.md`](anatomy.md) (what a skill is made of, and the loading\nmodel that decides where text belongs),\n[`conventions.md`](conventions.md) (house style, placeholders, the\nrules for skills that touch trackers or outside content), and\n[`security-checklist.md`](security-checklist.md) (the nine\nprompt-injection patterns in full). [`provenance.md`](provenance.md)\nrecords where this skill came from.\n\nTo make an existing skill leaner without changing what it does, use\n[`optimize-skill`](..\u002Foptimize-skill\u002FSKILL.md) instead. Step 7 runs it\nagainst every new skill regardless.\n\n## Step 1 — Get three concrete examples\n\nBefore writing anything, ask what the user will actually say, what the\nagent does in response, and what the apply step is. Get three to five\nreal invocations, not paraphrases.\n\nFor `security-issue-import` they were: *\"import new reports\"* → scan for\nunimported threads → propose a list → on `go`, create issues and\ndrafts. *\"check for unimported security@ messages\"* → the same.\n*\"import #\u003CthreadId>\"* → one named thread.\n\nIf an example stays fuzzy, ask until it is concrete. A skill written\nfrom vague examples produces boilerplate that helps nobody.\n\n## Step 2 — Decide what goes where\n\nFor each example, sort the work into three buckets.\n\n**Scripts** are the deterministic parts — anything easier in code than\nin prose. **Siblings** hold schemas, tables, catalogues and rationale:\nthings a run needs sometimes, not always. **Assets** are templates the\nskill writes out verbatim.\n\nMost skills need a small `scripts\u002F` and nothing else. Reach for a\nsibling when a section runs past ~200 lines, or when only some runs need\nit. [`anatomy.md`](anatomy.md) has the reasoning.\n\n## Step 3 — Scaffold it\n\n```bash\npython3 \u003Cframework>\u002Fskills\u002Fwrite-skill\u002Fscripts\u002Finit_skill.py \\\n  \u003Cskill-name> --path skills\u002F\u003Cskill-name>\n```\n\nThis creates the directory, a `SKILL.md` with the frontmatter and\nheader comments the validator expects, and empty `scripts\u002F` and\n`assets\u002F`. Skip this step for an existing skill.\n\n## Step 4 — Write the body\n\nWrite the steps, the hard rules, and the references.\n[`conventions.md`](conventions.md) is the house style: verb-first\nvoice, placeholders, one sentence per line, and what belongs in the\nbody versus a sibling.\n\nTwo things decide most of the shape. Every state-changing step is a\nproposal the user confirms. Everything paid for on every invocation\nmust be worth that price — if a run rarely needs it, move it to a\nsibling.\n\n## Step 5 — Secure it, if it reads outside content\n\nA skill reading Gmail, public PRs, mailing lists or findings files takes\nthe patterns in [`security-checklist.md`](security-checklist.md);\n[`conventions.md`](conventions.md) summarises them. A skill reading only\nframework files skips this step and says so in its body, so the next\nreader knows the omission was deliberate.\n\n## Step 6 — Validate\n\n```bash\nuv run --directory tools\u002Fskill-and-tool-validator --group dev \\\n  skill-and-tool-validate\n```\n\nIt checks the frontmatter shape, placeholder discipline, the SPDX\nheader and internal links. Fix what it reports and run it again. CI\nruns the same check, so a red skill does not merge.\n\n## Step 7 — Optimize before you ship\n\nA skill is written to be understood, and first drafts explain too much.\nRun [`optimize-skill`](..\u002Foptimize-skill\u002FSKILL.md) against what you just\nwrote — always, not only when it feels long. This is part of writing a\nskill, not a later cleanup someone may or may not get to.\n\nIt checks the new skill against the two budgets in that skill's *What\ncounts as small enough*: the body under 5,000 tokens, and\n`description` + `when_to_use` under 200. The second matters most. It is\npaid in every session, for every skill at once, whether or not anyone\never invokes this one — so a wordy description taxes people who will\nnever use the skill.\n\nTake its restructuring passes; they move text without changing it. For\nprose it offers the paragraph-by-paragraph rewrite, where you write the\nwords and it learns your style as it goes.\n\nA new skill that cannot get under both budgets is usually doing two\njobs. Consider splitting it before accepting the size.\n\n## Step 8 — Ship, then iterate\n\nUse the skill on real work and watch where it goes wrong: a step whose\ninstructions were too loose, a missing reference, a script that would\nhave helped. Land each fix as its own change. The body is re-read on\nevery invocation, so a tightening here compounds.\n\nWhen an adopter's `.apache-magpie-overrides\u002F\u003Cskill-name>.md` has\naccumulated something worth having upstream,\n[`setup-override-upstream`](..\u002F..\u002F..\u002Fmagpie-setup\u002Fskills\u002Foverride-upstream\u002FSKILL.md)\nwalks the promotion.\n\n## Hard rules\n\n- **Every state-changing step is a proposal the user confirms.** No\n  skill posts, edits or pushes on its own. This is the framework's\n  load-bearing invariant.\n- **Attacker-controlled text never enters a `gh` argument inside\n  quotes.** Tempfile plus `-F field=@file`. Never `--body \"$(cat …)\"` —\n  use `--body-file`. The exception is a regex-validated token such as\n  `CVE-…`, where the validation is the gate.\n- **`license: Apache-2.0` and a `capability:` in the frontmatter.** The\n  validator enforces both. Pick capabilities from\n  [`docs\u002Flabels-and-capabilities.md`](..\u002F..\u002F..\u002F..\u002Fdocs\u002Flabels-and-capabilities.md)\n  and list all that apply rather than collapsing to one. If none fit,\n  stop: either the taxonomy needs an entry or the skill is doing too\n  much.\n- **Credit adapted third-party content in\n  [`NOTICE`](..\u002F..\u002F..\u002F..\u002FNOTICE).**\n- **Never ship a skill that has not been through Step 7.** The budgets\n  are the gate: body under 5,000 tokens, frontmatter under 200.\n\n## References\n\n- [`anatomy.md`](anatomy.md), [`conventions.md`](conventions.md),\n  [`security-checklist.md`](security-checklist.md),\n  [`provenance.md`](provenance.md) — this skill's detail files.\n- [`scripts\u002Finit_skill.py`](scripts\u002Finit_skill.py) — Step 3's scaffold.\n- [`optimize-skill`](..\u002Foptimize-skill\u002FSKILL.md) — making an existing\n  skill leaner.\n- [`AGENTS.md`](..\u002F..\u002F..\u002F..\u002FAGENTS.md) — framework authoring\n  conventions and the external-content-as-data rule.\n- [`tools\u002Fskill-and-tool-validator\u002F`](..\u002F..\u002F..\u002F..\u002Ftools\u002Fskill-and-tool-validator\u002F)\n  — Step 6's gate.\n",{"mode":39,"name":5,"family":48,"license":15,"capability":49,"description":7,"when_to_use":50,"surface_hash":51,"measured_tokens":52},"utilities","capability:authoring","When the user says \"write a skill\", \"create a new skill\", \"add a skill for X\", or wants an existing skill updated to the framework's current conventions. For making a skill leaner without changing what it does, use optimize-skill.","sha256:31626428a2545bce",2827,"main","d594f578d34fc8482d2e4d633961a37687048c2d","plugins\u002Fmagpie-utilities\u002Fskills\u002Fwrite-skill",127,"https:\u002F\u002Fgithub.com\u002Fapache\u002Fmagpie","https:\u002F\u002Fmagpie.apache.org\u002F","https:\u002F\u002Fgithub.com\u002Fapache","https:\u002F\u002Fwww.apache.org\u002F","2026-11-14 06:14:00",{"source":8,"skillName":5,"commands":63,"prompt":73,"zipAvailable":74},[64,67,70],{"tool":65,"command":66},"npx","npx skills add apache\u002Fmagpie --skill write-skill",{"tool":68,"command":69},"bunx","bunx skills add apache\u002Fmagpie --skill write-skill",{"tool":71,"command":72},"pnpm","pnpm dlx skills add apache\u002Fmagpie --skill write-skill","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fapache\u002Fmagpie\u002Fblob\u002Fmain\u002Fplugins\u002Fmagpie-utilities\u002Fskills\u002Fwrite-skill\u002FSKILL.md",true,[76,82,86,90,96],{"path":77,"resourceType":78,"resourceTypeDesc":79,"sizeBytes":80,"sourceHtmlUrl":81},"anatomy.md","REFERENCE","参考文档",2040,"https:\u002F\u002Fgithub.com\u002Fapache\u002Fmagpie\u002Fblob\u002Fmain\u002Fplugins\u002Fmagpie-utilities\u002Fskills\u002Fwrite-skill\u002Fanatomy.md",{"path":83,"resourceType":78,"resourceTypeDesc":79,"sizeBytes":84,"sourceHtmlUrl":85},"conventions.md",3297,"https:\u002F\u002Fgithub.com\u002Fapache\u002Fmagpie\u002Fblob\u002Fmain\u002Fplugins\u002Fmagpie-utilities\u002Fskills\u002Fwrite-skill\u002Fconventions.md",{"path":87,"resourceType":78,"resourceTypeDesc":79,"sizeBytes":88,"sourceHtmlUrl":89},"provenance.md",2066,"https:\u002F\u002Fgithub.com\u002Fapache\u002Fmagpie\u002Fblob\u002Fmain\u002Fplugins\u002Fmagpie-utilities\u002Fskills\u002Fwrite-skill\u002Fprovenance.md",{"path":91,"resourceType":92,"resourceTypeDesc":93,"sizeBytes":94,"sourceHtmlUrl":95},"scripts\u002Finit_skill.py","SCRIPT","脚本",10674,"https:\u002F\u002Fgithub.com\u002Fapache\u002Fmagpie\u002Fblob\u002Fmain\u002Fplugins\u002Fmagpie-utilities\u002Fskills\u002Fwrite-skill\u002Fscripts\u002Finit_skill.py",{"path":97,"resourceType":78,"resourceTypeDesc":79,"sizeBytes":98,"sourceHtmlUrl":99},"security-checklist.md",9736,"https:\u002F\u002Fgithub.com\u002Fapache\u002Fmagpie\u002Fblob\u002Fmain\u002Fplugins\u002Fmagpie-utilities\u002Fskills\u002Fwrite-skill\u002Fsecurity-checklist.md",[101,125,150,171,197,218],{"skillNo":102,"name":103,"nameZh":6,"description":104,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":105,"categories":106,"keywords":107,"publishedAt":43},"01M70JNYMCY5EEWYWDN30WKDJ4","upgrade","Upgrade Magpie in one run: move to the new version if needed (`setup update`), check this machine and project, apply one approved plan, re-check, and print exact commands for what is out of reach.","https:\u002F\u002Fgithub.com\u002Fapache\u002Fmagpie\u002Fblob\u002Fmain\u002Fplugins\u002Fmagpie-setup\u002Fskills\u002Fupgrade\u002FSKILL.md",[],[103,108,109,110,111,112,113,114,39,115,116,37,117,118,119,120,121,122,123,124],"notice","platform","for","project","re","move","session","machine","yes","version","apply","print","check","last","plan","run","update",{"skillNo":126,"name":127,"nameZh":6,"description":128,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":129,"categories":130,"keywords":131,"publishedAt":43},"01M70JJBSW3XE35BAXQ1VTA9SV","dependency-vulnerability-audit","Read-only dependency vulnerability audit for one repository or a local\ncheckout. Detects the project's dependency manager(s), runs the\nappropriate audit tool, surfaces patchable findings grouped by severity,\nand proposes upgrades for maintainer review. Never modifies manifests or\nlock files and never opens update PRs.","https:\u002F\u002Fgithub.com\u002Fapache\u002Fmagpie\u002Fblob\u002Fmain\u002Fplugins\u002Fmagpie-repo-health\u002Fskills\u002Fdependency-vulnerability-audit\u002FSKILL.md",[],[132,133,134,135,136,137,138,139,111,140,141,142,143,144,145,36,146,147,148,149],"vulnerability","audit","dependency","dependency vulnerability audit","never","checkout","chain","scope","dependency manager","local","only","files","invoke","manifests","ask","patch","hand","review",{"skillNo":151,"name":152,"nameZh":6,"description":153,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":154,"categories":155,"keywords":156,"publishedAt":43},"01M70JGBWHKMB7V6T7QWT6G5DQ","thread-mentor","Draft a teaching-register comment on a GitHub issue or PR thread on the\nconfigured `\u003Cupstream>` repo, aimed at a contributor missing context the\nmaintainer would spell out. Reads the thread, decides\nwhether an intervention is warranted, drafts one comment per the tone\nguide and convention pointers, and waits for explicit confirmation before\nposting via `gh`. Escalates on the four hand-off triggers.","https:\u002F\u002Fgithub.com\u002Fapache\u002Fmagpie\u002Fblob\u002Fmain\u002Fplugins\u002Fmagpie-pr-management\u002Fskills\u002Fthread-mentor\u002FSKILL.md",[],[157,158,159,111,160,161,144,162,163,36,164,146,165,148,149,166,167,168,169,170],"thread mentor","mentor","thread","repro","confirmation","pr-management","contributor","number","teaching","at","config","drafts","flags","spell",{"skillNo":172,"name":173,"nameZh":6,"description":174,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":175,"categories":176,"keywords":182,"publishedAt":43},"01M70JF866SAVGXSSC33HRX4ZG","merge-candidates","Identify trivial, low-risk PRs in the `ready for maintainer review` queue\nof \u003Cupstream> that pass every quality gate and touch only supplementary\nareas (docs, changelog, translations, tests) — the \"express lane\".\nSurfaces and ranks candidates with per-PR diff summaries, an\nall-gates-green attestation, and the exact merge command. On explicit\nper-PR confirmation it can submit an APPROVE review, exactly as\npr-management-code-review does. It never merges itself — automated merge\nis the deliberately-deferred Agentic Autonomous mode.","https:\u002F\u002Fgithub.com\u002Fapache\u002Fmagpie\u002Fblob\u002Fmain\u002Fplugins\u002Fmagpie-pr-management\u002Fskills\u002Fmerge-candidates\u002FSKILL.md",[177],{"categoryNo":178,"categoryName":179,"taxonomyType":180,"taxonomyTypeDesc":181},"01JBSEEDCAT000000000000030","开发工程师","PROFESSION","适用职业",[183,184,185,186,187,136,188,189,111,190,191,192,142,193,161,144,162,194,195,196],"merge candidates","merge","ready","quick","show","green","submit","churn","attestation","mode","autonomous","show me","agentic","code",{"skillNo":198,"name":199,"nameZh":6,"description":200,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":201,"categories":202,"keywords":203,"publishedAt":43},"01M6AD18GMVM1BEM31VF538R8A","generate-cve-json","Generate a CVE 5.x JSON document from an \u003Ctracker> tracking\nissue, ready to paste into the Vulnogram `#source` tab of the ASF CVE tool\nat https:\u002F\u002Fcveprocess.apache.org\u002Fcve5\u002F\u003CCVE-ID>#source. The conversion is\ndeterministic: same issue in, same JSON bytes out. Handles multiple\ncredits (one per line) and multiple references (URLs extracted from the\nissue's \"Public advisory URL\" and \"PR with the fix\" fields; the\n\"Security mailing list thread\" field is treated as internal-only and\nnever exported).","https:\u002F\u002Fgithub.com\u002Fapache\u002Fmagpie\u002Fblob\u002Fmain\u002Ftools\u002Fcve-tool-vulnogram\u002Fgenerate-cve-json\u002FSKILL.md",[],[204,205,206,207,9,124,185,136,208,142,209,210,211,212,213,214,215,216,217,166,144,36],"cve","generate","generate cve json","json","fix","either","URL","team","conversion","publish","references","tracker","paste","exported",{"skillNo":219,"name":220,"nameZh":6,"description":221,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":222,"categories":223,"keywords":225,"publishedAt":43},"01M6AD1307G9B36HTAFY1KBJ5R","skill-reconciler","Compare two near-duplicate skills — typically an ASF variant and a\nnon-ASF or multi-project variant — and classify every difference as\nALLOWED, DRIFT, or SAFETY-BASELINE. Produces a structured diff and a\nreconciliation proposal; read-only, it never rewrites either skill.","https:\u002F\u002Fgithub.com\u002Fapache\u002Fmagpie\u002Fblob\u002Fmain\u002Fplugins\u002Fmagpie-utilities\u002Fskills\u002Fskill-reconciler\u002FSKILL.md",[224],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},[226,227,184,40,228,229,230,136,111,231,39,232,142,144,209,36,233,26,234,235,24],"skill reconciler","asf","near","reconciliation","proposal","same skill","variants","drift","classify","read"]