Skip to content

fabioc-aloha/Alex_Skill_Mall / .github/skills/mall-self-curation

mall-self-curation

Verified

lastReviewed: 2026-09-19

name: mall-self-curation description: Operate the Plugin Mall's canonical vendor, contribution, scan, score, render, and validation workflows. Use when importing or refreshing curated plugins, reviewing contributor PRs, running first-party maintenance, debugging the weekly catalog refresh, or onboarding to Mall internals. lastReviewed: 2026-08-01

Mall Self-Curation

The Plugin Mall is self-curating. Day-to-day operations (inventory, scoring, catalog publishing, staleness pruning) run inside this repo's .github/workflows/scan-sources.yml. This skill is the operational playbook for that pipeline.

When to Use

  • Authoring or debugging anything under scripts/scan-sources.cjs / normalize-frontmatter.cjs / compute-trust.cjs / list-refs.cjs / render-catalog.cjs
  • Weekly catalog-refresh PR (catalog-refresh/YYYY-MM-DD) is stuck or producing surprising deltas
  • New source added to sources/supported-stores.json — verifying it flows through the pipeline
  • New plugin shape encountered (frontmatter convention we haven't seen before)
  • Importing or refreshing a first-party plugin with npm run vendor
  • Preparing or reviewing a contributor submission with submit:prepare / submit:validate
  • Refreshing first-party catalog state with npm run maintain -- --curated
  • Onboarding to Mall internals

Canonical operator commands

RoleCommandWritesApproval boundary
Maintainernpm run vendor -- --source <path-or-repo> --category <category> --repository <url> --ref <tag-or-sha>None by defaultDry-run; add --apply, and --replace for existing plugins
Maintainernpm run maintain -- --curatedFirst-party catalog, trust, marketplace, README, rendered pagesReview git diff before commit
Maintainernpm run maintain -- --fullFull registered-store catalog surfaceRequires SOURCES_DIR and GitHub auth
Contributornpm run submit:prepare -- ... --applyProposed plugin payload + marketplace entry in contributor branchNever commits, pushes, merges, or approves
Contributor / CInpm run submit:validate -- --plugin <category>/<name>NoneStructural eligibility only; CODEOWNER decides acceptance

All plugin packaging routes through scripts/lib/plugin-package.cjs. Do not author a second copier or validator for one plugin. The shared library owns component-path normalization, prompt renaming, metadata generation, secret and symlink rejection, the 100-file limit, and atomic replacement.

A curated plugin can declare retirement in .mall-metadata.json only with state: "withdrawn", a reader-facing message, and a replacement plugin name plus marketplace. The catalog retains and labels the entry with its replacement command; the generated install marketplace omits it. Add or change retirement metadata through a reviewed plugin PR, never through the generated refresh lane.

Two PR lanes

LaneTriggerMerge behavior
Generated catalog refreshWeekly or manual scan-sources.ymlAuto-merges after deterministic tests and validation; workflow-owned paths only
Curated plugin contributionHuman PR under plugins/validate-plugin-pr.yml reports checks; never auto-merges; @fabioc-aloha CODEOWNER approval required

Do not apply the catalog-refresh auto-merge rule to plugin contributions. A green contribution is structurally reviewable, not editorially accepted.

The pipeline (per .github/workflows/scan-sources.yml)

  bootstrap-sources.cjs            ─┐
  scan-sources.cjs                  │
  normalize-frontmatter.cjs         ├─▶ catalog/index.json
  list-refs.cjs                     │   catalog/stores/*.json
  compute-trust.cjs                 │   scoring/trust-audit.{json,md}
  render-catalog.cjs                │   catalog/INDEX.md + per-store + per-category
  validate-catalog.cjs             ─┘   structural gate before merge
                                        README.md (storefront)

Each step is idempotent: re-running with no upstream changes produces byte-identical output.

StepOwnsReadsWrites
bootstrap-sources.cjsSource-repo clones into $SOURCES_DIRsources/supported-stores.json$SOURCES_DIR/<name>/ (one shallow clone per third-party store; plugin-mall is excluded — it's this repo)
scan-sources.cjsPer-plugin metadata extractionsources/supported-stores.json + $SOURCES_DIR/<name>/<pluginDir>/<plugin>/ + this repo's plugins/<category>/<name>/ (for plugin-mall self-scan)catalog/stores/<store>.json (without trust scores yet)
normalize-frontmatter.cjsStandard + extended + raw three-layer schemacatalog/stores/<store>.json (plugins[*].frontmatter.raw)catalog/stores/<store>.json (plugins[*].frontmatter.standard + extended)
list-refs.cjsPer-plugin version discovery$SOURCES_DIR/<name>/.git/ + plugin source_pathcatalog/stores/<store>.json (plugins[*].available_refs)
compute-trust.cjsTrust score (provenance + 5 signals)catalog/stores/*.json + scoring/github-stats.jsoncatalog/stores/*.json (store_trust + plugins[*].trust_score) + scoring/trust-audit.{json,md}
render-catalog.cjsJSON → MD renderingcatalog/stores/*.jsoncatalog/index.json + catalog/INDEX.md + catalog/stores/<store>.md (one per store) + catalog/categories/<cat>.md (one per category) + README.md (storefront) + sources/SOURCES.md (rendered registry)
validate-catalog.cjsStructural integrity gateRegistry + generated JSON/MarkdownExit 0 only when registry, stores, counts, trust fields, and rendered surfaces reconcile

The plugin-mall self-entry — load-bearing rule

sources/supported-stores.json includes one entry with name: "plugin-mall" and provenance: true. This entry refers to this repo itself and is the mechanism that puts Mall-curated plugins in the same catalog as third-party plugins.

Two rules govern it:

  1. Bootstrap MUST skip plugin-mall. This repo is already checked out; cloning it from itself is wasteful and could cause race conditions during the workflow. bootstrap-sources.cjs filters by name !== "plugin-mall".
  2. Scan MUST include plugin-mall. The scan walks $REPO_ROOT/plugins/ (not $SOURCES_DIR/plugin-mall/) and produces catalog/stores/plugin-mall.json like any other store. scan-sources.cjs resolves the path conditionally: third-party stores use $SOURCES_DIR/<name || local_dir_name>/<pluginDir>; plugin-mall uses $REPO_ROOT/<pluginDir>.

Crossing this boundary (cloning self in bootstrap, or skipping self in scan) is the most common source of bugs in this pipeline.

Trust scoring formula

Computed by compute-trust.cjs; signals published alongside score so readers can audit why a score is what it is.

SignalRangeSourceMall-as-storeThird-party typical
Provenance0 or +50supported-stores.json provenance field+500
Store maintenance0–15scoring/github-stats.json last_commit recency150–15
Store adoption0–10GitHub stars + contributors via scoring/github-stats.json100–10
License clarity0–10OSI-approved=10, clear non-permissive=7, ambiguous=07 (PolyForm-NC)0–10
Frontmatter completeness0–10description + version + lastReviewed presence100–10
README presence0–5README ≥ 200 chars50–5

Mall-as-store ceiling: 97/100. Third-party stores cap at 50 by construction (no provenance). Per-plugin score adds up to +20 from plugin-specific signals on top of store score.

If the formula drifts from this table, update this skill in the same commit. Changes to the weights or signals are [behaviour]-class commits; changes that alter what the published-signal contract guarantees are [constitutional].

Workflow + cadence

  • Weekly cron: Mondays 11:00 UTC per .github/workflows/scan-sources.yml
  • PR-back: only when catalog/, scoring/, README.md, or sources/SOURCES.md change (timestamp-only deltas filtered)
  • Manual dispatch: workflow_dispatch available for ad-hoc re-scans (e.g., after adding a store to supported-stores.json)
  • Deterministic pre-merge gate: npm test + npm run validate must pass before the catalog-refresh PR can open or merge
  • Generated refresh oversight: catalog-refresh PRs auto-merge after gates; the merged diff is the sampling surface for Steward oversight
  • Contributor approval: plugin PRs never auto-merge and require CODEOWNER review

What the Mall does vs out-of-scope

ConcernOwner
Add / remove a source store from supported-stores.jsonMall (this skill + source-inventory)
Tune trust score weightsMall (this skill + compute-trust.cjs)
Scan / score / render / publish pipelineMall
Curated plugin payload validationMall automation, followed by maintainer approval
Decide a plugin earns a slot in any consumer project's baselineOut of scope (consumer-owned decision)
Coherence with a specific consumer projectOut of scope (consumer-owned audit)
Reframe what counts as "curated"Out of scope (editorial decision, not pipeline)
Periodic review of how the catalog is consumed downstreamOut of scope (consumer-owned)

If a question crosses the line into editorial or downstream policy, route it out of the workflow. Don't self-modify cross-repo policy from inside the Mall.

Curation log

Every editorial Mall decision lands in docs/curation-log.md in this repo (Mall's own append-only log). Decisions ship with re-eval dates; routine refreshes do not need log entries unless they triggered a curation action.

Anti-Patterns

Anti-patternCorrection
Editing brain files (skills/instructions/prompts/agents) under plugins/ during the workflowThe workflow MUST NOT modify plugins/ — editorial changes ship via PR review only. The workflow only writes to catalog/, scoring/, README.md, sources/SOURCES.md.
Treating a green contributor check as approvalAutomation establishes structural eligibility. The CODEOWNER still judges evidence, overlap, license, safety, category, and maintenance.
Hand-copying a source plugin into plugins/Use npm run vendor or npm run submit:prepare; both use the shared canonical packager.
Bootstrap re-cloning plugin-mall from itselfbootstrap-sources.cjs MUST filter name !== "plugin-mall".
Scan skipping plugin-mallscan-sources.cjs MUST include plugin-mall (walks $REPO_ROOT/plugins/, not bootstrapped sources).
Trust score without published signalsEvery score MUST come with its signal breakdown in catalog/stores/<store>.json trust_signals field.
Hardcoded "curated" tier flag in codeThere is NO tier flag in the schema. Curation bias emerges from provenance: true in supported-stores.json.
Quietly fudging the license signal so Mall scores 100Score honestly. PolyForm-NC = 7/10. The provenance +50 already carries the first-party trust weight.

Falsifiability

This skill needs revision if any of the following occur by 2026-08-29 (90 days):

  • The workflow modifies a file outside catalog/, scoring/, README.md, sources/SOURCES.md ≥1 time
  • A structurally inconsistent registry/catalog/render state passes npm run validate ≥1 time
  • Trust scores cluster oddly (e.g., third-party score consistently > 60 — provenance bonus undercalibrated)
  • Mall-curated plugins fail to rank #1 in /mall-search for the same name as a third-party entry (provenance signal not flowing)
  • A new source-shape (frontmatter convention) breaks normalize-frontmatter.cjs ≥2 times without surfacing in scoring/trust-audit.md
  • The boundary table (what the Mall does vs out-of-scope) produces wrong-routing decisions ≥2 times in a quarter

Track in docs/curation-log.md tagged [MALL-SELF-CURATION].

Related

slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall