fix: modernize skill marketplace guidance

Author: levnikolaevich

.claude-plugin/marketplace.json

@@ -10,50 +10,43 @@
       "name": "review-suite",
       "description": "Independent plan and delivery reviews with evidence-based verdicts.",
       "source": "./plugins/review-suite",
-      "strict": false,
-      "skills": "./skills/"
+      "strict": false
     },
     {
       "name": "codebase-audit-suite",
       "description": "Read-only audits for documentation, code, tests, architecture, and persistence.",
       "source": "./plugins/codebase-audit-suite",
-      "strict": false,
-      "skills": "./skills/"
+      "strict": false
     },
     {
       "name": "optimization-suite",
       "description": "Measured performance, dependency, modernization, and benchmark workflows.",
       "source": "./plugins/optimization-suite",
-      "strict": false,
-      "skills": "./skills/"
+      "strict": false
     },
     {
       "name": "testing-suite",
       "description": "Risk-based test planning and reproducible acceptance-test creation.",
       "source": "./plugins/testing-suite",
-      "strict": false,
-      "skills": "./skills/"
+      "strict": false
     },
     {
       "name": "product-discovery-suite",
       "description": "Evidence-based product opportunity evaluation before implementation.",
       "source": "./plugins/product-discovery-suite",
-      "strict": false,
-      "skills": "./skills/"
+      "strict": false
     },
     {
       "name": "maintainer-suite",
       "description": "Optional maintainer toolkit for skill review, repository publication, releases, and project announcements.",
       "source": "./plugins/maintainer-suite",
-      "strict": false,
-      "skills": "./skills/"
+      "strict": false
     },
     {
       "name": "architecture-suite",
       "description": "Architecture baselines, current-state documentation, target designs, decisions, diagrams, and migration plans.",
       "source": "./plugins/architecture-suite",
-      "strict": false,
-      "skills": "./skills/"
+      "strict": false
     }
   ]
 }

AGENTS.md

@@ -15,7 +15,7 @@ Claude Code discovers the standard `skills/` directories through `.claude-plugin
 ## Skill rules
 
 - Edit the canonical skill only at `plugins/<plugin>/skills/<skill>/SKILL.md`.
-- Keep each skill standalone. It must not require another skill, an MCP server, a task tracker, or repository-wide shared instructions.
+- Keep each skill standalone. It must not require another skill, MCP server, task tracker, separately installed coordinator or worker, or shared runtime. A skill may require host-native independent contexts when that is intrinsic to its outcome and it defines an explicit `BLOCKED` result.
 - Keep YAML frontmatter to `name` and `description`. The folder name and `name` must match.
 - Put the trigger boundary in `description`: what the skill does, when to use it, and important near-negative cases.
 - Begin each skill body, before tool routing, with `**Goal:**` defining its intended outcome and boundary and `**Execution contract:**` telling the agent how to apply the skill.
@@ -52,15 +52,16 @@ Before finishing a change:
 
 1. Run the installed `skill-creator` `quick_validate.py` for every skill directory.
 2. Run the installed `plugin-creator` `validate_plugin.py` for every plugin directory.
-3. Run `claude plugin validate . --strict` for the Claude marketplace.
+3. Run `claude plugin validate . --strict` for the Claude marketplace. This validates the catalog, not Claude skill frontmatter in manifest-less plugin directories; the per-skill validator and manual frontmatter checks cover that known boundary.
 4. Confirm both marketplace catalogs contain the same plugin names in the same order, every manifest path exists, and each plugin description matches its Claude marketplace entry.
-5. Search for stale references to removed skills, MCP packages, shared registries, drafts, and orchestration harnesses.
+5. Confirm OpenAI directory-facing metadata meets current limits, including at most three starter prompts and display and short descriptions of at most 30 characters.
+6. Search for stale references to removed skills, MCP packages, shared registries, drafts, and orchestration harnesses.
 
 If an installed validator is unavailable, perform the equivalent checks manually: frontmatter contains only `name` and `description`; folder and frontmatter names match; descriptions are at most 200 characters; skills stay within the 100–200 line target; manifests parse and point to existing paths; both catalogs match; and no stale coupling remains.
 
 ## Release rules
 
-- Plugin versions live only in `.codex-plugin/plugin.json` and follow SemVer.
+- Explicit plugin SemVer lives only in `.codex-plugin/plugin.json`. Claude marketplace entries intentionally omit `version`, so Claude Code identifies ordinary updates by their source commit SHA.
 - Change a version only when the user explicitly requests a release; ordinary repository edits do not bump versions.
 - Record a release with a matching Git tag and GitHub Release. Document user-facing migration in `README.md`; a repository `CHANGELOG.md` is not required.
 

README.md

@@ -86,8 +86,11 @@ Add the marketplace and install only the suites you need:
 /plugin install product-discovery-suite@levnikolaevich-skills-marketplace
 /plugin install maintainer-suite@levnikolaevich-skills-marketplace
 /plugin install architecture-suite@levnikolaevich-skills-marketplace
+/reload-plugins
 ```
 
+Invoke a skill by its namespaced name, for example `/review-suite:ln-12-delivery-reviewer`.
+
 For local development, load one plugin directly:
 
 ```bash
@@ -129,10 +132,10 @@ This is the smallest practical shared layout for distributed plugins:
 
 - Both hosts use `skills/<name>/SKILL.md`, so each skill has one canonical copy.
 - Codex requires `.codex-plugin/plugin.json` for a plugin.
-- Claude Code can expose a standard `skills/` directory from the marketplace entry, so duplicate per-plugin Claude manifests are unnecessary here.
+- Claude Code automatically scans each manifest-less marketplace source's standard `skills/` directory, so duplicate per-plugin Claude manifests are unnecessary here.
 - `agents/openai.yaml`, references, scripts, assets, hooks, agents, and MCP configuration are optional and omitted until a concrete need appears.
 
-The structure follows the current official [Codex skill guide](https://learn.chatgpt.com/docs/build-skills), [Codex plugin guide](https://learn.chatgpt.com/docs/build-plugins), [Claude Code skill guide](https://code.claude.com/docs/en/skills), and [Claude Code plugin reference](https://code.claude.com/docs/en/plugins-reference).
+The structure follows the current official [Codex skill guide](https://developers.openai.com/codex/skills), [OpenAI plugin guide](https://developers.openai.com/plugins/build/plugins), [Claude Code skill guide](https://code.claude.com/docs/en/skills), and [Claude Code plugin reference](https://code.claude.com/docs/en/plugins-reference).
 
 ## Indexing
 

plugins/architecture-suite/.codex-plugin/plugin.json

@@ -14,18 +14,15 @@
   "skills": "./skills/",
   "interface": {
     "displayName": "Architecture Suite",
-    "shortDescription": "Create durable architecture artifacts",
+    "shortDescription": "Build architecture artifacts",
     "longDescription": "Create and update evidence-backed architecture baselines, current-state maps, target designs, decision records, diagrams, and reversible migration plans.",
     "developerName": "Lev Nikolaevich",
     "websiteURL": "https://github.com/levnikolaevich/claude-code-skills",
     "category": "Productivity",
     "capabilities": ["Interactive", "Read", "Write"],
     "defaultPrompt": [
-      "Create or update the system-design baseline for this project.",
-      "Document the current implemented architecture from repository evidence.",
-      "Create a decision-complete target system design.",
-      "Record this architecturally significant decision.",
-      "Create an evidence-backed architecture diagram.",
+      "Document or design the architecture for this project.",
+      "Record an architecture decision or create a diagram.",
       "Plan a reversible migration from the current architecture to the target."
     ]
   }

plugins/architecture-suite/skills/ln-73-system-design-proposal-builder/SKILL.md

@@ -15,7 +15,7 @@ Before returning, apply this skill's verdict and approval rules to every incompl
 | Need | Preferred capability | Fallback |
 |---|---|---|
 | Requirements and constraints | Approved requirements, baseline, decisions, and direct stakeholder input | Mark material gaps and ask the smallest decision question |
-| Current implementation and conventions | Repository search, manifests, entrypoints, and architecture artifacts | Treat the design as greenfield and state the limitation |
+| Current implementation and conventions | Repository search, manifests, entrypoints, and architecture artifacts | Treat as greenfield only when the user or repository establishes that fact; otherwise mark current state `UNKNOWN` and return `REVISE` or `BLOCKED` when the gap can change boundaries, compatibility, or migration |
 | External capabilities and limits | Current official documentation and specifications | Mark claims `UNVERIFIED`; avoid vendor-dependent commitment |
 | Estimates | Reproducible arithmetic from sourced workload assumptions | Use ranges and sensitivity; never present estimates as measurements |
 | Document mutation | Minimal patch to the approved target-design artifact | Return `BLOCKED` if scope or path is unsafe |

plugins/architecture-suite/skills/ln-75-architecture-diagram-builder/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ln-75-architecture-diagram-builder
-description: "Creates evidence-backed current or target architecture diagrams. Use when relationships need visualization; not for UI design, architecture audit, or invented structure."
+description: "Creates evidence-backed current or target architecture diagrams when the diagram is the primary deliverable. Not for UI design, architecture audit, or invented structure."
 ---
 
 # Architecture Diagram Builder

plugins/codebase-audit-suite/.codex-plugin/plugin.json

@@ -14,7 +14,7 @@
   "skills": "./skills/",
   "interface": {
     "displayName": "Codebase Audit Suite",
-    "shortDescription": "Evidence-based read-only codebase audits",
+    "shortDescription": "Run evidence-based audits",
     "longDescription": "Audit documentation, code health, tests, architecture, and persistence without changing the reviewed repository.",
     "developerName": "Lev Nikolaevich",
     "websiteURL": "https://github.com/levnikolaevich/claude-code-skills",

plugins/maintainer-suite/.codex-plugin/plugin.json

@@ -14,7 +14,7 @@
   "skills": "./skills/",
   "interface": {
     "displayName": "Maintainer Suite",
-    "shortDescription": "Optional publishing tools for maintainers",
+    "shortDescription": "Maintain and publish plugins",
     "longDescription": "Optional maintainer workflows for reviewing standalone skills, publishing repository changes and tagged releases, and announcing verified project news.",
     "developerName": "Lev Nikolaevich",
     "websiteURL": "https://github.com/levnikolaevich/claude-code-skills",
@@ -23,8 +23,7 @@
     "defaultPrompt": [
       "Review these skills for publication readiness.",
       "Publish the approved repository changes and verify the remote result.",
-      "Prepare a tagged release for explicit approval.",
-      "Draft a fact-checked GitHub Discussions announcement."
+      "Prepare a release or project announcement for approval."
     ]
   }
 }

plugins/maintainer-suite/skills/ln-61-skill-reviewer/SKILL.md

@@ -51,7 +51,7 @@ Tool absence is not itself a skill defect. Apply the documented fallback and use
 - [ ] Discover and run every repository-required skill validator for the changed skill directories; do not assume a validator name or location absent from repository evidence.
 - [ ] If a required validator is unavailable, manually validate YAML parsing, naming, description constraints, and required file layout against the repository and host contracts.
 - [ ] Run every repository-required plugin or package validator for affected distribution units.
-- [ ] Run each host-native strict validator when its corresponding catalog or manifest exists.
+- [ ] Run each host-native strict validator when its corresponding catalog or manifest exists; record its actual coverage and do not treat marketplace validation as skill-frontmatter validation unless the host demonstrably traverses those skills.
 - [ ] Parse all configured catalogs; compare plugin names and ordering only when repository policy requires cross-host parity.
 - [ ] Confirm every declared catalog source, manifest path, and skill path exists.
 - [ ] Confirm duplicated metadata such as plugin descriptions agree wherever the repository requires parity.

plugins/maintainer-suite/skills/ln-63-release-publisher/SKILL.md

@@ -29,7 +29,7 @@ Do not browse for generic release advice when repository policy and previous com
 
 - [ ] Confirm the user explicitly requested a release and identify the repository, release target, and intended audience.
 - [ ] Read repository release rules before selecting a version, tag shape, files, or publication sequence.
-- [ ] Verify GitHub CLI availability, authentication, repository access, and permission to create releases.
+- [ ] Verify an authenticated GitHub release capability, repository access, and permission to create releases.
 - [ ] Require a clean worktree or explicitly exclude unrelated changes before release preparation.
 - [ ] Fetch tags and the target branch; confirm local HEAD is synchronized with the remote release branch.
 - [ ] Find the latest relevant tag and GitHub Release rather than assuming the newest tag belongs to this release line.