git:20260929.3b184b4 to git:20260930.0f67929

# CLAUDE.md

## Project Overview

**chewiesoft-marketplace** — a dual-platform plugin marketplace owned by **j0ruge**. Distributes skills and commands for **Claude Code** and **Cursor**, developed exclusively by the owner.

For Claude Code, this repository follows the [Claude Code Plugin Marketplace](https://code.claude.com/docs/en/plugins-reference) specification.

For Cursor, skills are installed via the interactive `install.py` script at the repo root.

## Marketplace Structure

```

skills/

├── .claude-plugin/

│ └── marketplace.json # Marketplace catalog (lists all plugins)

├── plugins/ # Plugin directories (one per plugin)

│ └── .gitkeep

├── .claude/

│ ├── commands/ # Speckit commands (SDD dev tools, NOT marketplace content)

│ └── settings.json # Team distribution config

├── .specify/ # SDD framework (dev tooling, NOT marketplace content)

├── install.py # Interactive installer (Claude Code + Cursor)

└── CLAUDE.md

```

### Key files

- **`.claude-plugin/marketplace.json`** — The marketplace catalog. Lists all available plugins with their source paths. This is the entry point Claude Code reads when registering the marketplace.

- **`plugins/`** — Each subdirectory is a self-contained plugin with its own `.claude-plugin/plugin.json` manifest.

- **`.claude/settings.json`** — Registers this repo as a known marketplace for team auto-discovery.

- **`install.py`** — Interactive installer. Handles both Claude Code (shows installation commands) and Cursor (copies and adapts skills to `~/.cursor/skills/` or `.cursor/skills/`).

### Platform Compatibility

Each `plugin.json` includes a `platforms` field declaring which platforms support the plugin:

- `["claude-code", "cursor"]` — available on both platforms

- `["claude-code"]` — Claude Code only (e.g., `statusline`)

## Adding a New Plugin

1. Create a directory under `plugins/`:

```

plugins/my-plugin/

├── .claude-plugin/

│ └── plugin.json # Plugin manifest (name, description, author, etc.)

├── commands/ # Command definitions (.md files)

├── skills/ # Skill definitions (SKILL.md files)

```

2. Create `plugins/my-plugin/.claude-plugin/plugin.json`:

```json

{

"name": "my-plugin",

"description": "What this plugin does",

"author": {

"name": "Chewiesoft"

},

"version": "1.0.0",

"keywords": ["relevant", "tags"],

"platforms": ["claude-code", "cursor"],

"commands": "./commands",

}

```

Set `"platforms": ["claude-code"]` if the plugin uses Claude Code-specific APIs (e.g., status line, MCP tools) and cannot work in Cursor.

3. Register the plugin in `.claude-plugin/marketplace.json`:

```json

{

"plugins": [

{

"name": "my-plugin",

"source": "./plugins/my-plugin",

"version": "1.0.0",

"description": "Brief plugin description shown in Discover tab",

"category": "development",

"keywords": ["relevant", "tags"],

"platforms": ["claude-code", "cursor"]

}

]

}

```

4. If the plugin supports Cursor, add a mapping entry to `CURSOR_SKILL_MAP` in `install.py` so the installer knows how to copy and adapt the content.

- For skills: add an entry with `"source_type": "skill"` pointing to the skill directory.

- For commands: add an entry with `"source_type": "command"` and a `"cursor_description"` for Cursor's trigger-based discovery.

## Skill description guidelines

The `description` field in SKILL.md frontmatter and `marketplace.json` is the

primary trigger mechanism. When the combined skill listing exceeds Claude

Code's `skillListingBudgetFraction` (default 1% of context), descriptions are

**dropped silently** and the skills lose their trigger. Keep descriptions tight

so this never happens.

### DO

- Keep `description` ≤ 350 characters (hard cap: 500). Fits one line in

`/skills` output.

- Open with one sentence describing the function — not "Use this skill when…".

- Follow with 1–2 distinctive capabilities that disambiguate from neighbors.

- End with a single trigger list of ≤ 8 keywords, prefixed `Triggers — `.

- Pick **one language** per description (English preferred for cross-team

reach). Body of the skill can stay bilingual.

- Mirror the exact same description in `SKILL.md` frontmatter, `plugin.json` and

the matching entry in `.claude-plugin/marketplace.json` — the canonical source

is `SKILL.md` (that's the copy Claude Code reads to decide about the skill);

for commands-only plugins, `plugin.json`.

- **Quote the description value** in the SKILL.md frontmatter. An unquoted YAML

scalar containing `: ` (e.g. `...by stack: Node`) opens a nested mapping and

makes the whole frontmatter invalid YAML. Lenient parsers swallow it, so the

skill keeps working and the defect stays latent until a strict consumer shows up.

- Run `python scripts/validate-versions.py` before merging — check 6 enforces

the mirroring above and warns when a description is over the 500 cap. Run it

with `--fix` to mirror the canonical copy into the diverging files. Also run

`/doctor`: it reports descriptions dropped at runtime, which the script can't see.

> These two rules were written here long before anything measured them, and by

> 2026-08-08 five of the ten skill-bearing plugins had three different texts —

> one of them 2541 chars in `plugin.json` against 813 in `SKILL.md`, i.e. the

> description had become a changelog. That is why check 6 exists: a convention

> nothing verifies is a convention the repo will drift away from.

### DON'T

- Don't enumerate every quirk, capability, file, or use-case in the description

— that belongs in the SKILL.md body or in a `references/` file.

- Don't write the trigger list twice (once in prose "Use when X, Y, Z" and

again as a bullet list). Pick one form, prefer the explicit `Triggers — `

line.

- Don't write "Use this skill SEMPRE / ALWAYS / PROACTIVELY" — it's noise that

triggers nothing extra and eats budget.

- Don't mix languages inside a single description (PT + EN). It doubles the

text without doubling the recall.

- Don't paste the raw `keywords:` list into `description:` — Claude already

sees `keywords` separately.

- Don't ship hash-suffixed copies (`my-skill-2f5564a0.md`) in

`~/.claude/commands/`. If they appear, they're orphans from old installs and

should be deleted.

### Why

Each dropped description silently disables a skill's trigger — Claude only

sees the name, never the "when to use it" text. Symptoms: skills that used to

work stop firing on their canonical phrases, and `/doctor` shows

`N descriptions dropped`. The fix is always trimming descriptions, not raising

the budget (raising costs ~5k tokens per session and consumes rate limits

faster).

## Skill format (agentskills.io spec)

Every `SKILL.md` follows the open spec at https://agentskills.io/specification, which other

clients and the reference validator (`skills-ref`) read strictly even where Claude Code is lenient.

`scripts/validate-versions.py` check 7 enforces it.

- **Frontmatter:** top level holds only `name`, `description`, `license`, `compatibility`,

`metadata`, `allowed-tools`. `name` is a-z, 0-9 and single hyphens and equals the directory

(`coderabbit_pr` had to become `coderabbit-pr` in codereview 2.0.0). Version lives in

`metadata.version`. Lists in block style, never `[a, b]`. A Claude Code-only field

(e.g. `argument-hint`) stays only when it does something, and the CHANGELOG says why — the

field names are hyphenated; `user_invocable`/`argument_description` with underscores were

silently ignored.

- **Budget:** `SKILL.md` under 500 lines (error) and ~20,000 chars / ~5,000 tokens (warning).

Detail goes to `references/`, each routed from `SKILL.md` with *when* to read it; references

stay one level deep and get a table of contents past 300 lines.

- **Audit a skill:** `python3 plugins/skill-quality-audit/skills/skill-quality-audit/scripts/audit_skill_quality.py plugins/<p>/skills/<s> --external off --no-changelog-required --desc-budget 0`

(the auditor ships in this repo as the `skill-quality-audit` plugin; `/retrofit-skill` runs it

as a baseline before editing and a regression gate after).

## Prompt hygiene

Skills are prompts, and prompts age with the model they were written for. A

retrofit adds one lesson to the text that is already there; nothing removes the

caps-lock emphasis, the incident narrative, the origin project's hostname or the

pinned model name once the failure they guarded against stops reproducing. The

2026-09-03 audit of all 16 skills found that in every one of them (see

`KAIZEN_LOG.md`).

- Re-run `/claude-api prompt-audit` on a skill **at every retrofit** and **at

every model release** — it is the only pass that reads the whole skill against

the current model instead of appending to it.

- The reusable brief (procedure, signal greps, report shape, diff recipe with

`git apply --check` only) lives outside the repo at

`~/.claude/handoff/prompt-audit-2026-09-03/prompt-audit/BRIEF-auditoria.md`.

- What changed and why goes to the plugin's `CHANGELOG.md`, with the numbers;

the audit reports and diffs themselves stay out of the repo.

## Identity & canonical repository

**Chewiesoft is the fictional software company / brand. j0ruge is the GitHub

user that owns and publishes everything under that brand.** The two names

coexist by design — Chewiesoft is product branding, j0ruge is the GitHub

account that ships it.

| Layer | Value | Where it appears |

|---|---|---|

| Brand / company (fictional) | **Chewiesoft** | `author.name` in `plugin.json`, `owner.name` in `marketplace.json`, README/install.py headings |

| Marketplace slug | **chewiesoft-marketplace** | `name` in `.claude-plugin/marketplace.json`, key in `.claude/settings.json` |

| GitHub owner / user | **j0ruge** | All clone/install URLs, `git remote` |

| Canonical repo URL | **`https://github.com/j0ruge/skills`** | All install snippets, README, this CLAUDE.md |

Chewiesoft is **not** a GitHub organization. The repo lives under the personal

user `j0ruge`.

The repo was called `skills_commands_manager` until 2026-09-29. GitHub redirects

the old URL, so existing clones and `/plugin marketplace add` registrations keep

working, but new text uses `j0ruge/skills`. The redirect lasts only while no

new repo takes the old name.

### DO

- Use `j0ruge/skills` in every install/clone snippet

(`README.md`, this `CLAUDE.md`, `install.py`, `.claude/settings.json`,

`/plugin marketplace add` examples).

- Keep `"author": { "name": "Chewiesoft" }` in plugin manifests and

`"chewiesoft-marketplace"` as the marketplace slug — those are branding,

not repo references.

- When introducing a new plugin, use the same pairing: `author.name =

"Chewiesoft"` and any source/clone URL pointing at

`j0ruge/skills`.

### DON'T

- Don't write URLs like `Chewiesoft/skills` or

`chewiesoft/...` as if Chewiesoft were a GitHub org — it isn't. The user

`j0ruge` owns the repo.

- Don't introduce URLs pointing at any other GitHub owner or repo name for

this marketplace (internal mirrors, forks, archived predecessors). Any

reference that resolves to a different repo is stale and must be replaced

with the canonical URL above.

- Don't rename the brand to "j0ruge Marketplace" or vice-versa — the two

names coexist on purpose.

- Don't confuse external doc links (zitadel, wpfui, microsoft/fluentui,

FlaUI, ddd-crew, kgrzybek) with marketplace repo links — those external

links are valid and should not be rewritten.

## Plugin Source Options

When registering plugins in `marketplace.json`, the `source` field supports:

- **Relative path**: `"./plugins/my-plugin"` — local directory in this repo

- **GitHub**: `{ "source": "github", "repo": "j0ruge/plugin-repo" }` — from a GitHub repository

- **npm**: `{ "source": "npm", "package": "@j0ruge/my-plugin" }` — from npm registry

## Installation (End Users)

### Cursor

```bash

git clone git@github.com:j0ruge/skills.git

cd skills

python install.py

```

The installer prompts for platform (Claude Code / Cursor / Both) and install location, then copies and adapts the skills automatically.

**Cursor caveat:** Cursor (as of 2026) does not auto-load skills from a global directory — only project-local `.cursor/skills/` is read by the agent. Run `install.py` inside each project and pick the **Project** option. The optional **Staging cache** writes to `~/.cursor/skills/` as a master copy you mirror manually.

### Claude Code

Users can install this marketplace in Claude Code:

```

/plugin marketplace add <path-or-url-to-this-repo>

```

Or clone the repo and add locally:

```

/plugin marketplace add ./path/to/skills

```

## Speckit (Development Tooling)

The `.claude/commands/speckit.*` commands and `.specify/` directory are **development tools** (Specification-Driven Development framework) used to build this project. They are NOT part of the marketplace content and are not distributed as plugins.

Available speckit commands: `specify`, `clarify`, `plan`, `analyze`, `tasks`, `implement`, `checklist`, `constitution`, `taskstoissues`.

## Session Rules

- At the end of every coding session, update `README.md` to reflect the current state of the marketplace — especially the **Available Plugins** table (sync with `.claude-plugin/marketplace.json`).

## Git

- **Main branch**: `main`