@mmerterden/multi-agent-pipeline 20.5.0 → 20.7.0

package/pipeline/skills/shared/external/localization-reuse-map/scripts/verify-map.py

@@ -1,26 +1,9 @@
 #!/usr/bin/env python3
-"""Fidelity check  -  cross-verify a mapping against the REAL sources before publishing.
-
-The map can drift from reality (stale keys parsed from an old doc, hallucinated keys,
-a wired key that never made it into a row, an empty value). This script reconciles the
-mapping JSON against the live repos and reports what doesn't hold up  -  so the page you
-publish reflects the code, not a guess. Read-only.
-
-Checks (each reported, never auto-fixed):
-  1. newKey ∈ screen code  -  every row's `newKey` should appear as a wired
-     `LocalizationStringKey.<...>` call site (or `"Key".localized`, or a web
-     `t('Key')` / `$t('Key')` i18n call) in --screen-path.
-     Component-owned keys (`(owned by ...)` / `(DS bileşen...)`) are exempt (they live in the
-     component, not the screen file) and listed separately.
-  2. code keys ∉ map  -  `LocalizationStringKey.<...>` wired in the screen but with no
-     row → missing coverage (add a row or confirm it's out of scope).
-  3. value gaps  -  `new.tr` empty (verdict≠new), or legacy entirely empty where
-     the verdict claims reuse/review.
-  4. untranslated  -  a row whose `new.tr` == `new.en` (flag, as the renderer does).
-  5. resources (optional)  -  with --resources-root, the new key's Suggested/<Key>.json exists.
-
-Exit code 2 when any hard fidelity issue is found (unverified non-component key, code key
-missing from the map, or a reuse/review row with no legacy value), so it can gate a run.
+"""Fidelity gate: reconcile a reuse-map mapping against the implemented screen.
+
+Checks that every mapped newKey is wired in the screen code, that every key
+the code wires is mapped, and that no row carries an empty or invented value.
+Exit 2 when a hard issue is found (blocks publishing), 0 otherwise.
 """
 import argparse
 import json
@@ -28,145 +11,178 @@ import os
 import re
 import sys
 
-EXTS = (".swift", ".kt", ".kts", ".xml", ".ts", ".tsx", ".js", ".jsx", ".vue")
-RE_LSK = re.compile(r"LocalizationStringKey\.([A-Za-z0-9_]+(?:\.[A-Za-z0-9_]+)+)")
-RE_LITERAL = re.compile(r'"([A-Za-z0-9_.]+)"\s*\.\s*localized')
-# Web (react-i18next / next-intl `t('key')`; vue-i18n `$t('key')`)
-RE_WEB_T = re.compile(r"(?<!\$)\bt\(\s*['\"]([A-Za-z0-9_.\-]+)['\"]")
-RE_WEB_VUE_T = re.compile(r"\$t\(\s*['\"]([A-Za-z0-9_.\-]+)['\"]")
-# RE_LSK is greedy across dots, so `...StringKey.Ns.leaf.localized` captures the accessor
-# too. Strip it, or no call site ever matches its mapping row and every wired key is
-# reported unmapped.
-RE_ACCESSOR = re.compile(r"\.localized\w*$")
-MARKER = re.compile(r"\(.*(owned by|bileşen|component).*\)", re.I)
+EXTENSIONS = {".swift", ".kt", ".kts", ".xml", ".ts", ".tsx", ".js", ".jsx", ".vue"}
+SKIP_PARTS = ("/.git", "/Generated/")
 
+WORD = "A-Za-z0-9_"
+LSK = re.compile(rf"LocalizationStringKey((?:\.[A-Za-z_][{WORD}]*)+)")
+LITERAL_LOCALIZED = re.compile(rf"\"([{WORD}.]+)\"\.localized\b")
+WEB_T = re.compile(r"(?<![\w$])t\(\s*(['\"])([A-Za-z0-9_.\-]+)\1")
+WEB_DOLLAR_T = re.compile(r"\$t\(\s*(['\"])([A-Za-z0-9_.\-]+)\1")
+TRAILING_MARKER = re.compile(r"\s*\([^()]*\)\s*$")
+COMPONENT_MARKER = re.compile(r"\([^)]*(owned by|bile\u015fen|component)[^)]*\)", re.IGNORECASE)
+PLACEHOLDER = re.compile(r"<[^<>]+>")
 
-def clean_key(k):
-    """Strip a trailing '(owned by ...)' / '(DS bileşene ait)' marker → bare dotted key."""
-    return re.sub(r"\s*\(.*\)\s*$", "", (k or "")).strip()
 
+def strip_accessor(chain):
+    segments = chain.strip(".").split(".")
+    while segments and segments[-1].startswith("localized"):
+        segments.pop()
+    return ".".join(segments)
 
-def is_component(k):
-    return bool(MARKER.search(k or ""))
 
+def normalize_key(key):
+    return ".".join(seg[:1].upper() + seg[1:] for seg in key.split("."))
 
-def norm_key(k):
-    return clean_key(k).lower()
 
+def source_files(root):
+    if os.path.isfile(root):
+        yield root
+        return
+    for current, dirs, files in os.walk(root):
+        probe = current.replace(os.sep, "/") + "/"
+        if any(part in probe for part in SKIP_PARTS):
+            dirs[:] = []
+            continue
+        for name in sorted(files):
+            if os.path.splitext(name)[1] in EXTENSIONS:
+                yield os.path.join(current, name)
 
-def scan_code(screen_path):
-    """Return (set of wired dotted keys lowercased, full lowercased corpus text)."""
-    keys, corpus = set(), []
-    files = []
-    if os.path.isfile(screen_path):
-        files = [screen_path]
-    else:
-        for dp, _d, names in os.walk(screen_path):
-            if "/.git" in dp:
-                continue
-            files += [os.path.join(dp, n) for n in names if n.endswith(EXTS)]
-    for f in files:
+
+def scan_code(root):
+    keys = set()
+    corpus = []
+    scanned = 0
+    for path in source_files(root):
         try:
-            txt = open(f, encoding="utf-8", errors="replace").read()
-        except OSError:
+            with open(path, encoding="utf-8") as stream:
+                text = stream.read()
+        except (OSError, UnicodeDecodeError):
             continue
-        corpus.append(txt.lower())
-        for m in RE_LSK.finditer(txt):
-            keys.add(RE_ACCESSOR.sub("", m.group(1)).lower())
-        for m in RE_LITERAL.finditer(txt):
-            keys.add(m.group(1).lower())
-        for m in RE_WEB_T.finditer(txt):
-            keys.add(m.group(1).lower())
-        for m in RE_WEB_VUE_T.finditer(txt):
-            keys.add(m.group(1).lower())
-    return keys, "\n".join(corpus), len(files)
+        scanned += 1
+        corpus.append(text.lower())
+        chains = (strip_accessor(hit.group(1)) for hit in LSK.finditer(text))
+        keys.update(chain.lower() for chain in chains if chain)
+        for pattern, group in ((LITERAL_LOCALIZED, 1), (WEB_T, 2), (WEB_DOLLAR_T, 2)):
+            keys.update(hit.group(group).lower() for hit in pattern.finditer(text))
+    return keys, "\n".join(corpus), scanned
+
+
+def is_component(row):
+    text = " ".join(str(row.get(f) or "") for f in ("newKey", "element", "note"))
+    return bool(COMPONENT_MARKER.search(text))
 
 
-def leaf_in_corpus(key, corpus):
-    """Weak check: the key's last segment appears as a word in the code corpus."""
-    leaf = clean_key(key).split(".")[-1]
-    return bool(leaf) and re.search(r"\b" + re.escape(leaf.lower()) + r"\b", corpus) is not None
+def is_dynamic(row, key):
+    element = str(row.get("element") or "").lower()
+    note = str(row.get("note") or "").lower()
+    return (
+        key.startswith("(dynamic")
+        or bool(PLACEHOLDER.search(key))
+        or "dinamik" in element
+        or "dynamic" in element
+        or "enumerate at runtime" in note
+    )
+
+
+def suggested_exists(root, key):
+    name = normalize_key(key) + ".json"
+    candidates = [
+        os.path.join(root, "Localization", "Suggested", name),
+        os.path.join(root, "Resources", "Localization", "LocalizationStrings", "Sources", "Suggested", name),
+    ]
+    return any(os.path.isfile(p) for p in candidates)
 
 
 def main():
-    ap = argparse.ArgumentParser(description=__doc__,
-                                 formatter_class=argparse.RawDescriptionHelpFormatter)
-    ap.add_argument("--mapping", required=True)
-    ap.add_argument("--screen-path", required=True, help="implemented screen dir/file")
-    ap.add_argument("--resources-root", help="resources / snapshot root (checks Suggested/<Key>.json)")
-    ap.add_argument("--out", help="write the full report JSON here (default: stdout summary only)")
-    args = ap.parse_args()
-
-    m = json.load(open(args.mapping, encoding="utf-8"))
-    rows = m.get("rows", [])
-    code_keys, corpus, nfiles = scan_code(args.screen_path)
-
-    verified, weak, unverified, component = [], [], [], []
-    value_gaps, untranslated = [], []
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("--mapping", required=True, help="the reuse-map JSON")
+    parser.add_argument("--screen-path", required=True, help="folder or single file of the built screen")
+    parser.add_argument("--resources-root", help="resources checkout or snapshot; turns on the Suggested-file check")
+    parser.add_argument("--out", help="JSON report destination; stdout when omitted")
+    args = parser.parse_args()
+
+    with open(args.mapping, encoding="utf-8") as stream:
+        mapping = json.load(stream)
+    rows = mapping.get("rows") or []
+    code_keys, corpus, scanned = scan_code(args.screen_path)
+
+    verified = 0
+    exempt = 0
+    weak, unverified = [], []
+    gaps, untranslated = [], []
     map_keys = set()
 
-    for r in rows:
-        k = r.get("newKey", "")
-        ck = clean_key(k)
-        map_keys.add(norm_key(k))
-        # 1. newKey in code
-        if is_component(k) or k.startswith("(dynamic") or "dinamik" in (r.get("element", "").lower()):
-            component.append(k)
-        elif norm_key(k) in code_keys:
-            verified.append(k)
-        elif leaf_in_corpus(k, corpus):
-            weak.append(k)
+    for row in rows:
+        raw_key = str(row.get("newKey") or "").strip()
+        key = raw_key if raw_key.startswith("(dynamic") else TRAILING_MARKER.sub("", raw_key)
+        component = is_component(row)
+        dynamic = is_dynamic(row, key)
+        if key:
+            map_keys.add(key.lower())
+
+        if component or dynamic:
+            exempt += 1
+        elif key.lower() in code_keys:
+            verified += 1
         else:
-            unverified.append({"key": k, "element": r.get("element")})
-        # 3. value gaps
-        nw, lg, vd = r.get("new") or {}, r.get("legacy") or {}, r.get("verdict")
-        if vd != "new" and not (nw.get("tr") or "").strip() and not k.startswith("(dynamic"):
-            value_gaps.append({"key": k, "issue": "new.tr empty"})
-        if vd in ("reuse", "review") and not any((lg.get(l) or "").strip() for l in ("en", "tr")):
-            value_gaps.append({"key": k, "issue": f"verdict={vd} but no legacy value"})
-        # 4. untranslated
-        if (nw.get("tr") or "").strip() and nw.get("tr") == nw.get("en"):
-            untranslated.append(k)
-        # 5. resources
-        if args.resources_root and not is_component(k) and not k.startswith("(dynamic"):
-            seg = ".".join(s[:1].upper() + s[1:] if s else s for s in ck.split("."))
-            p1 = os.path.join(args.resources_root, "Localization", "Suggested", seg + ".json")
-            p2 = os.path.join(args.resources_root, "Resources", "Localization",
-                              "LocalizationStrings", "Sources", "Suggested", seg + ".json")
-            if not (os.path.isfile(p1) or os.path.isfile(p2)):
-                value_gaps.append({"key": k, "issue": "no Suggested/<Key>.json"})
-
-    # 2. code keys not in map
-    code_not_mapped = sorted(k for k in code_keys if k not in map_keys)
-
+            leaf = key.rsplit(".", 1)[-1].lower()
+            whole_word = r"\b%s\b" % re.escape(leaf)
+            if leaf and re.search(whole_word, corpus):
+                weak.append(key)
+            else:
+                unverified.append({"key": key, "element": row.get("element")})
+
+        verdict = row.get("verdict")
+        new = row.get("new") or {}
+        legacy = row.get("legacy") or {}
+        if verdict != "new" and not new.get("tr") and not dynamic:
+            gaps.append({"key": key, "issue": "new.tr empty"})
+        if verdict in ("reuse", "review") and not (legacy.get("en") or legacy.get("tr")):
+            gaps.append({"key": key, "issue": f"verdict={verdict} but no legacy value"})
+        if new.get("tr") and new.get("tr") == new.get("en"):
+            untranslated.append(key)
+        if args.resources_root and not component and not dynamic and key and not suggested_exists(args.resources_root, key):
+            gaps.append({"key": key, "issue": f"no Suggested/{normalize_key(key)}.json"})
+
+    not_in_map = sorted(code_keys - map_keys)
     report = {
-        "screen": m.get("screen"), "rows": len(rows), "filesScanned": nfiles,
-        "newKeyInCode": {"verified": len(verified), "weak": weak,
-                         "unverified": unverified, "component_or_dynamic": len(component)},
-        "codeKeysNotInMap": code_not_mapped,
-        "valueGaps": value_gaps, "untranslated": untranslated,
+        "screen": mapping.get("screen"),
+        "rows": len(rows),
+        "filesScanned": scanned,
+        "newKeyInCode": {
+            "verified": verified,
+            "weak": weak,
+            "unverified": unverified,
+            "component_or_dynamic": exempt,
+        },
+        "codeKeysNotInMap": not_in_map,
+        "valueGaps": gaps,
+        "untranslated": untranslated,
     }
-    hard = len(unverified) + len(code_not_mapped) + sum(1 for g in value_gaps if "no legacy" in g["issue"])
-
+    text = json.dumps(report, indent=2, ensure_ascii=False) + "\n"
     if args.out:
-        with open(args.out, "w", encoding="utf-8") as fh:
-            json.dump(report, fh, ensure_ascii=False, indent=2)
-            fh.write("\n")
-    # summary to stderr (always)
-    sys.stderr.write(
-        f"# fidelity: {len(rows)} rows · {nfiles} files\n"
-        f"#   newKey in code: {len(verified)} verified · {len(weak)} weak(leaf) · "
-        f"{len(unverified)} UNVERIFIED · {len(component)} component/dynamic (exempt)\n"
-        f"#   code keys not in map: {len(code_not_mapped)}\n"
-        f"#   value gaps: {len(value_gaps)} · untranslated(tr==en): {len(untranslated)}\n")
-    if unverified:
-        sys.stderr.write("#   UNVERIFIED keys: " + ", ".join(u["key"] for u in unverified[:12]) + "\n")
-    if code_not_mapped:
-        sys.stderr.write("#   wired-but-unmapped: " + ", ".join(code_not_mapped[:12]) + "\n")
-    if not args.out:
-        json.dump(report, sys.stdout, ensure_ascii=False, indent=2)
-        sys.stdout.write("\n")
-    sys.exit(2 if hard else 0)
+        with open(args.out, "w", encoding="utf-8") as sink:
+            sink.write(text)
+    else:
+        sys.stdout.write(text)
+
+    no_legacy = [g for g in gaps if "no legacy value" in g["issue"]]
+    hard = len(unverified) + len(not_in_map) + len(no_legacy)
+    print(
+        f"# rows {len(rows)}, files {scanned}: verified {verified}, weak {len(weak)}, "
+        f"UNVERIFIED {len(unverified)}, component/dynamic {exempt}, wired-but-unmapped {len(not_in_map)}, "
+        f"value gaps {len(gaps)} ({len(no_legacy)} hard), untranslated {len(untranslated)}",
+        file=sys.stderr,
+    )
+    for item in unverified[:12]:
+        print(f"#   UNVERIFIED {item['key']}  ({item['element']})", file=sys.stderr)
+    for key in not_in_map[:12]:
+        print(f"#   wired but unmapped: {key}", file=sys.stderr)
+    if hard:
+        print(f"# FAIL: {hard} hard issue(s); fix them or record a conscious waiver before publishing", file=sys.stderr)
+        sys.exit(2)
+    print("# PASS", file=sys.stderr)
 
 
 if __name__ == "__main__":

package/pipeline/skills/shared/external/nextjs-app-router/SKILL.md

@@ -2,6 +2,7 @@
 name: nextjs-app-router
 description: "Next.js 15+ App Router: Server/Client Components, Server Actions, data fetching, layouts, middleware, ISR/SSG/SSR, and routing patterns. Use when building or reviewing App Router work: Server Components, Server Actions, data fetching, layouts."
 metadata:
+  source: multi-agent-pipeline
   tags: [nextjs, react, frontend, ssr, app-router, full-stack]
   version: "2025.1"
 ---

package/pipeline/skills/shared/external/play-store-review/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: play-store-review
 description: "Prepare Android apps for Google Play Store review and compliance. Covers Google Play policy requirements, content rating questionnaire, target API level requirements, data safety section, privacy policy requirements, in-app purchase policies, common rejection reasons, app signing with Play App Signing, and AAB upload. Use when preparing for Play Store submission, handling policy violations, or auditing app compliance."
+metadata:
+  source: multi-agent-pipeline
 ---
 
 # Google Play Store Review

package/pipeline/skills/shared/external/python-patterns/SKILL.md

@@ -2,6 +2,7 @@
 name: python-patterns
 description: "Modern Python 3.12+: type hints, dataclasses, Pydantic v2, async/await, context managers, generators, pattern matching. Use when writing or reviewing modern Python: typing, dataclasses, Pydantic, async, generators."
 metadata:
+  source: multi-agent-pipeline
   tags: [python, type-hints, pydantic, asyncio, dataclasses, backend]
   version: "2025.1"
 ---

package/pipeline/skills/shared/external/react-best-practices/SKILL.md

@@ -2,6 +2,7 @@
 name: react-best-practices
 description: "React 19+ best practices: Server Components, use() hook, Actions, hooks patterns, state management, and performance optimization. Use when building or reviewing React work: components, hooks, state, Server Components, Actions."
 metadata:
+  source: multi-agent-pipeline
   tags: [react, frontend, javascript, typescript, hooks, state-management]
   version: "2025.1"
 ---

package/pipeline/skills/shared/external/rest-api-design/SKILL.md

@@ -2,6 +2,7 @@
 name: rest-api-design
 description: "REST API design: HTTP methods, status codes, pagination, versioning, rate limiting, caching headers, OpenAPI documentation. Use when a REST surface needs designing or reviewing: methods, status codes, pagination, versioning, caching."
 metadata:
+  source: multi-agent-pipeline
   tags: [rest, api, http, openapi, pagination, backend]
   version: "2025.1"
 ---

package/pipeline/skills/shared/external/retrofit-networking/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: retrofit-networking
 description: "Build networking layers on Android with Retrofit, OkHttp, and Kotlin Coroutines. Covers suspend functions in API interfaces, OkHttp interceptors (auth, logging, retry), sealed Result error handling, multipart uploads, WebSocket support, network-bound resource pattern (cache + API), and Hilt integration for Retrofit instances. Use when building API clients, handling network errors, implementing caching, or setting up networking infrastructure."
+metadata:
+  source: multi-agent-pipeline
 ---
 
 # Retrofit Networking

package/pipeline/skills/shared/external/room-database/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: room-database
 description: "Implement Room database persistence on Android with @Entity, @Dao, @Database, Flow-based reactive queries, TypeConverters for complex types, migration strategies (auto and manual), relations with @Embedded/@Relation and junction tables, in-memory database testing, and Hilt integration. Use when adding local persistence, defining database schemas, writing DAOs, handling migrations, or testing Room queries."
+metadata:
+  source: multi-agent-pipeline
 ---
 
 # Room Database

package/pipeline/skills/shared/external/search-first/SKILL.md

@@ -7,6 +7,7 @@ description: |
   Use at the start of any non-trivial feature or utility, especially when you
   are about to reach for a new dependency or hand-roll something common.
 metadata:
+  source: multi-agent-pipeline
   version: 1.0.0
 ---
 

package/pipeline/skills/shared/external/signal-community/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: signal-community
 description: "Check whether other people hit the same problem, via Stack Overflow and Hacker News (keyless) plus opt-in Reddit and X. Use when a bug report or complaint needs corroboration beyond one user. Advisory only: it belongs in a risks section, never in a business rule."
+metadata:
+  source: multi-agent-pipeline
 ---
 
 # Community signal

package/pipeline/skills/shared/external/skill-creator/SKILL.md

@@ -1,49 +1,88 @@
 ---
 name: skill-creator
-description: "Author and refine skills for a plugin/toolkit efficiently. Use when creating a new skill, trimming or splitting an existing one, writing a skill's description, or choosing skill vs command vs agent vs CLAUDE.md. Encodes the house rules - lean SKILL.md as an index, progressive disclosure into bundled files, the reference (descriptive) vs workflow (imperative) split, no-prefix naming, and growing a skill from observed failures. Bundles a template, a pre-ship checklist, and good/bad description examples."
+description: "House guide for authoring plugin skills: creating a new skill, trimming or splitting a bloated one, writing or sharpening a description, and choosing between a skill, slash command, subagent, CLAUDE.md entry or MCP server. Covers the lean-index SKILL.md, progressive disclosure into bundled files, the reference vs workflow vs tool split, naming without a platform prefix, growing skills from observed failures, and the pre-ship audit. Ships templates, a checklist and description examples. Use for 'write a new skill', 'this skill is too long', 'improve this skill description', 'should this be a skill or an agent'. Not for writing the domain content itself, prompt writing unrelated to plugin skills, or per-session facts that belong in CLAUDE.md."
 user-invocable: true
-argument-hint: [new | trim | description]
+argument-hint: "[new | trim | description]"
 allowed-tools: Read, Write, Edit, Glob
 metadata:
   version: 1.0.0
+  source: multi-agent-pipeline
 ---
 
-# skill-creator - how to write skills here
-
-> **Layer:** reference (knowledge)
-> **Use when:** creating/trimming a skill, writing a description, or choosing skill vs command/agent/CLAUDE.md.
-> **Bundled (read on demand):** [template.md](template.md) · [checklist.md](checklist.md) · [examples.md](examples.md) · [label-check.md](label-check.md) · [audit.md](audit.md)
-
-## 1. Is a skill the right tool?
-- **CLAUDE.md** - broad facts/rules true *every* session.
-- **Skill** - on-demand procedure or knowledge for a recurring task.
-- **Subagent/agent** - needs independent reasoning + its own context/tools.
-- **MCP server** - structured integration with an external system's API.
-
-## 2. The description is discovery (the 90% lever)
-It's the *only* thing the model sees when deciding to load the skill. **Write it first.** Include **what + when + trigger words + one example trigger**, in third person. (Anthropic's data: vague→specific lifts activation ~20%→50%; adding examples ~72%→90%.) Good/bad pairs in [examples.md](examples.md).
-
-## 3. Keep it lean (it stays in context every turn once loaded)
-- `SKILL.md` is an **index** - aim for ~1 page, hard cap ~500 lines.
-- Push detail into bundled files **one level deep** (reference, examples, scripts). They cost zero tokens until read; nested-deeper files get partially read - don't nest.
-- A **script executes without its source entering context** - prefer a script over asking the model to regenerate code.
-- Challenge every line: *"would Claude err without this?"* If no, cut it.
-
-## 4. Pick the right degree of freedom (= our layers)
-- **reference skill → descriptive:** invariants, conventions + pointers to canonical files, decision heuristics, pitfalls, escape hatches. **No numbered procedures.**
-- **workflow skill → imperative spine:** a numbered procedure **only** for deterministic/irreversible steps (branch/PR, codegen, build/verify). Cite reference skills for the judgment.
-- **tool skill → thin index over a script/CLI:** lean SKILL.md (when + the run command + sub-commands at a glance), heavy detail in a bundled `reference.md`; the script is the engine (e.g. `tools/figma-utility`).
-
-## 5. Naming
-No platform prefix - the toolkit name + description already carry it. Reference = aspect noun (`navigation`); workflow = verb-phrase (`branch-and-pr`). Avoid vague/reserved (`helper`, `utils`, `claude-*`). For a name/title/strict-rule label that must carry its **whole intent**, validate it with the fresh-subagent inference test in [label-check.md](label-check.md) before committing.
-
-## 6. Grow it from real usage - don't pre-write
-1. Do the task **without** a skill; note where Claude actually fails.
-2. Write the **minimum** that fixes those gaps.
-3. Watch Claude use it: move reused detail up into SKILL.md, cut detail it ignores, sharpen the description if it didn't trigger.
-
-## Before shipping
-Start from [template.md](template.md); run [checklist.md](checklist.md). For a new or
-substantially-changed skill that must be trusted, run the **multi-architect audit**
-([audit.md](audit.md)) - a panel of distinct-lens reviewers + synthesis, looped
-fix → re-audit until no blockers/majors remain.
+# skill-creator - authoring plugin skills
+
+> **Layer:** knowledge (reference). **Use when:** creating, trimming, splitting, naming or describing a plugin skill, or gating one before it ships.
+> **Not for:** the domain content inside a skill (hand that to the domain skill), prompt writing unrelated to plugin skills, or facts every session needs (those go in CLAUDE.md).
+
+Bundled, read when the step needs it:
+
+- [template.md](template.md) - reference and workflow skeletons with frontmatter.
+- [checklist.md](checklist.md) - the pre-ship checklist.
+- [examples.md](examples.md) - weak and strong descriptions, wrong and right layer shapes.
+- [audit.md](audit.md) - the multi-architect audit loop and its lens sets; driven by `scripts/audit-panel.js`.
+- [label-check.md](label-check.md) - the fresh-subagent inference test for names and rule labels.
+
+## Arguments
+
+| Argument | Start at |
+|---|---|
+| `new` | Pick the artifact, write the description, then the template |
+| `trim` | Leanness and the cut test, then the checklist |
+| `description` | The description recipe and examples.md |
+
+## Pick the artifact first
+
+| Artifact | Holds |
+|---|---|
+| CLAUDE.md | facts and rules that are true in every session |
+| Skill | a procedure or body of knowledge for a recurring task, loaded on demand |
+| Subagent | work that needs its own reasoning, context window and tool set |
+| MCP server | a structured integration with an external API |
+
+## The description is the skill's only advertisement
+
+Before a skill loads, the model sees its name and description and nothing else. Write the description before the body. It needs:
+
+- **what** the skill covers or does, and **when** to use it;
+- concrete **trigger phrases** a user would actually type, plus one sample request;
+- the **platform** where it matters (iOS/SwiftUI, Compose, backend);
+- an implied **boundary** against sibling skills;
+- third person throughout.
+
+Anthropic's measurements: a specific description instead of a vague one lifted activation from about 20% to about 50%; adding examples took it from about 72% to about 90%. A one-liner with no when, no triggers and no platform gives the router nothing to match. See examples.md.
+
+## Keep SKILL.md an index
+
+- Everything in SKILL.md sits in context for every turn after it loads. Aim for about one page; 500 lines is the hard ceiling.
+- Push detail into bundled files **one level below** SKILL.md (reference, examples, scripts). They cost nothing until read. A file reached only through another bundled file tends to be read in part, so do not nest.
+- Deterministic work belongs in a script. Running it keeps its source out of context; never ask the model to write that code again each time.
+- **Cut test:** keep a line only if Claude would get the task wrong without it. Do not explain what the model already knows: a paragraph on how PDFs are structured loses to "use pdfplumber".
+
+## Layer sets the degrees of freedom
+
+| Layer | Voice | Contains | Never contains |
+|---|---|---|---|
+| reference | descriptive | invariants, conventions pointing at canonical files, decision heuristics, pitfalls, escape hatches | numbered procedures |
+| workflow | imperative | numbered steps only for deterministic or irreversible actions (branch and PR, codegen, build and verify), citations of reference skills for judgement, a verification gate | open-ended judgement dressed as steps |
+| tool | index | when to use, the run command, a sub-command overview; heavy detail in a bundled `reference.md`; the script is the engine | the engine's logic in prose |
+
+`tools/figma-utility` in the iOS toolkit is the model tool skill.
+
+## Naming
+
+- No platform prefix: the toolkit name and the description already say it.
+- Reference skills take an aspect noun (`navigation`); workflow skills a verb phrase (`branch-and-pr`).
+- Avoid vague or reserved names: `helper`, `utils`, anything starting with `claude-`.
+- When a name, title or strict-rule label has to carry its whole intent, run the label check before committing to it.
+
+## Grow skills from failures
+
+1. Do the task with no skill and note exactly where Claude goes wrong.
+2. Write the smallest skill that fixes those failures. Nothing speculative.
+3. Watch real use: promote detail that keeps getting read into SKILL.md, cut what is ignored, and sharpen the description whenever the skill failed to trigger.
+
+## Before it ships
+
+1. Run checklist.md as the self-review floor.
+2. New or substantially changed skill: run the audit loop in audit.md until `clearsBar` is true.
+3. Wire it: add the path to the `skills` array in `<plugin>/.claude-plugin/plugin.json`, bump the plugin version in `.github/plugin/marketplace.json`, and add a row to the plugin's `index` skill route table.