git:20260922.b295ebe to git:20260922.cfad0b2

5 added, 0 removed. Audit B to B.

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Repository Overview

This is a Claude Code skills marketplace containing production-ready skills organized in a plugin marketplace structure. Most plugins expose one skill for narrow installs; suite plugins expose related skills under shared namespaces for combined installation workflows.

**Essential Skill**: `skill-creator` is the most important skill in this marketplace - it's a meta-skill that enables users to create their own skills. Always recommend it first for users interested in extending Claude Code.

## Skills Architecture

### Directory Structure

Each skill follows a standard structure:

```

skill-name/

├── SKILL.md (required) # Core skill instructions with YAML frontmatter

├── scripts/ (optional) # Executable Python/Bash scripts

├── references/ (optional) # Documentation loaded as needed

└── assets/ (optional) # Templates and resources for output

```

### Progressive Disclosure Pattern

Skills use progressive loading:

1. **Metadata** (name + description in YAML frontmatter) - Advertised according to the host's discovery policy and catalog budget; verify the fresh host rather than assuming every description is present

2. **SKILL.md body** - Loaded when skill triggers

3. **Bundled resources** - Loaded as needed by Claude

## Development Commands

### Installation Scripts

**In Claude Code (in-app):**

```text

/plugin marketplace add daymade/claude-code-skills

```

Then:

1. Select **Browse and install plugins**

2. Select **daymade/claude-code-skills**

3. Select **daymade-skill**

4. Select **Install now**

**From your terminal (CLI):**

```bash

# Automated installation (macOS/Linux)

curl -fsSL https://raw.githubusercontent.com/daymade/claude-code-skills/main/scripts/install.sh | bash

# Automated installation (Windows PowerShell)

iwr -useb https://raw.githubusercontent.com/daymade/claude-code-skills/main/scripts/install.ps1 | iex

# Manual installation

claude plugin marketplace add https://github.com/daymade/claude-code-skills

# Marketplace name: daymade-skills (from marketplace.json)

claude plugin install daymade-skill@daymade-skills

```

### Skill Validation and Packaging

Use [skill-creator](daymade-skill/skill-creator/SKILL.md) before creating or

changing a skill. It owns change classification, evidence selection, regression

review, validation, initialization, and packaging.

Treat [packaging_policy.py](daymade-skill/skill-creator/scripts/packaging_policy.py)

as the canonical inclusion policy for packaging, security attestation, source

audits, and version checks. Keep consumers on this shared implementation. Preserve the recorded policy

when verifying an existing baseline; consult

[source snapshot archives](daymade-skill/skill-creator/references/source-snapshot-archives.md)

before archiving or restoring it.

For hook loop and reminder semantics, load

`daymade-claude-code:claude-code-hooks` and follow rule 7. Keep recurring

advisory injectors available for the whole session, using cadence/hysteresis

and reset semantics to limit frequency; never add a lifetime session cap.

Reserve repetition budgets for blocking remediation loops whose capped exit is

explicitly blocked, unshipped, or pending. Test advisory liveness across later

fully-due windows, and leave current thresholds in the owning implementation

rather than copying them into this file.

Synchronous Claude Code/Codex lifecycle hooks and background services

(LaunchAgents included) must call a fixed direct interpreter **owned by the

installer that writes it**. Do not register a Python entry point through a

package manager, generic interpreter dispatcher, or `.py` shebang lookup: a

shared environment/cache lock can stall every prompt or tool boundary, and a

bare `python3` resolves under launchd's minimal PATH to the Developer Tools

stub, which is old enough to reject syntax the script was written in. The

opposite error costs the same: resolving `sys.executable` bakes in a versioned

path another product owns, so the job dies silently when that product upgrades.

Own the literal path, the way `SYSTEM_GIT` is owned. Explicit maintenance,

retrieval, validation, and test commands may still use their declared `uv`

project; the runtime boundary is the rule. The concrete prior-work wrapper and

profile-converger registration live in their respective Skills rather than

being copied here.

Treat `daymade-skill/skill-creator` as a locked uv project. Run its bundled Python tools from that directory with `uv run --frozen`; the project-local `.venv` is isolated from caller projects while uv's shared cache supplies the pinned packages. Do not reintroduce per-call `--with` overlays for dependencies already in its `pyproject.toml`.

From the repository root, enter the locked tool project once and validate the

selected skill (replace `<skill-path>` with its absolute path):

```bash

cd daymade-skill/skill-creator

uv run --frozen python -m scripts.quick_validate <skill-path> --audience public

```

### Automated Test Suites (CI)

A `tests/` directory under a skill does **not** automatically run in CI. The

"Registered test suites (Linux)" GitHub Actions job only runs directories

explicitly listed in `scripts/ci/test-suites.txt` — that file's header is the

SSOT for the admission criteria (stdlib-only, no network/credentials,

deterministic, Linux-verified) and the runner types (`python-unittest` via

`unittest discover`, `node-test`). Adding a test file to an unregistered

`tests/` directory gives you a suite you can run locally, not CI coverage —

check the registry before assuming otherwise, and note `unittest discover`

only collects `unittest.TestCase` subclasses, not bare pytest-style functions.

### Transcript Correction

Use [transcript-fixer](daymade-audio/transcript-fixer/SKILL.md) for transcript

correction. Its Native workflow owns evidence selection, selective human escalation,

and correction/finalization order;

[Native review packets](daymade-audio/transcript-fixer/references/native_review_packets.md)

owns split, batch, and resumed review instructions. Keep CLI parameters and

validation behavior in

[native_review.py](daymade-audio/transcript-fixer/scripts/native_review.py), and

queue anchor behavior in

[review_queue.py](daymade-audio/transcript-fixer/scripts/core/review_queue.py).

When changing these paths, update their owning instructions together; keep

review coverage, unresolved verdicts, and repository publication distinct.

### Feishu Document Capture

For Feishu document reads and archives, enter

[feishu-doc-scraper](feishu-doc-scraper/SKILL.md). Its

[comments and feedback SOP](feishu-doc-scraper/references/comments-and-feedback.md)

owns discussion capture and interpretation; the bundled helper owns the CLI

interface. For filing, use its

[archive storage contract](feishu-doc-scraper/references/archive-storage-contract.md)

alongside the destination repository's storage SOP.

### Prior Work Retrieval Boundary

`prior-work-retrieval` creates an obligation only for an explicit prior-work,

reuse, or history request. Ordinary implementation, reports, and read-only

inspection do not arm it; PreToolUse and Stop may enforce only a requirement

already created by the current prompt. Artifact selection and runtime-read

comparison are owned by that Skill; a receipt about a locator is not proof of

the delivered artifact. Detailed retrieval mechanics remain in

`daymade-claude-code/prior-work-retrieval/SKILL.md`.

### Local Agent Messaging

For both Claude Code and Codex, use current native discovery, messaging, replies,

and waiting whenever those tools cover the target; do not load or run `peer-message`

merely for native communication. Use its routing guidance for uncovered local targets

or coordination evidence that needs verification, never to bypass denied or Held messages.

Treat `peer-message/scripts/peer.py` as the fallback CLI executable

contract and `peer-message/SKILL.md` as the runtime router and owner of stable

runtime prerequisites plus the peer-cannot-authorize safety boundary. Reply lookup,

transport and discovery details belong in `peer-message/references/protocol-and-discovery.md`;

current product availability, provenance, and inbound-control mechanics belong in

`peer-message/references/official-feature.md`; reply addressing, payload structure,

delivery-status language, what to do when you find another session's in-flight work on a

shared resource, and the verification contracts that decide what a peer assertion or a

peer denial is worth belong in

`peer-message/references/coordination-and-learning-loop.md`. Keep implementation, CLI help,

tests, and those owners aligned; README and changelog entries should point to

them instead of restating volatile protocol facts. The repository-wide

local-source activation contract below still applies—never hand-create Codex

Skill links.

### Codex Quota and Account Checks

For Codex reset announcements or account quota questions, enter

[tibo-reset-codex](tibo-reset-codex/SKILL.md). Follow its

[account usage SOP](tibo-reset-codex/references/account-usage.md) for authentication,

per-account verification and browser restoration. Treat

[query_usage.py](tibo-reset-codex/scripts/query_usage.py) as the executable authority

for query parameters, supported response fields and exit behavior. Keep detailed

commands and changing account state out of this file.

### WeCom Send Boundary

WeCom sender skills must read an explicit target class. `self` may send to the

user's own delivery channel without authorization; `others` requires the exact

label and message at a human confirmation gate. Unknown target identity fails

fast. Automatic self delivery also requires the config-bound sender path and

digest; a matching basename is not identity. A pending item is not a delivery

receipt, and an automatic outbox path gets one non-retrying HTTP attempt.

### Testing Skills Locally

Test from the canonical checkout, not from a mutable direct copy. Use the current

`claude-switch-models-setup` local-source workflow for this maintainer machine,

and use `daymade-skill:skill-governance` to verify source, installed state,

discovery policy, and the fresh model-visible catalog. Do not blindly remove and

re-add a marketplace: removing it uninstalls plugins installed from that

marketplace. Do not `cp -r` a second Skill tree into a user Skill directory; that

copy immediately creates an independent drift owner.

For maintainer source-backed activation, follow

[Local Source Sync Architecture](daymade-claude-code/claude-switch-models-setup/references/local-source-sync-architecture.md).

That reference owns the activation-manifest contract, host-specific selection,

legacy compatibility, and repair workflow. An approved whole-marketplace policy

includes newly registered members; a source checkout or registration alone does

not establish that policy. Do not hand-create user Skill links.

+ For intentional same-name source variants, use the owner's explicit source-selection

+ contract; retain every candidate and reject undeclared collisions. Audit tools must

+ consume the owner's selected inventory rather than choose a source independently.

When delivery includes local availability, finish the source owner's dry-run/apply

and the [newly registered Skill gate](daymade-skill/skill-governance/references/skill-surface-governance.md#14-verify-a-newly-registered-skill).

Take expected identities from the requested change, not from links or a whitelist

that may already omit the new Skill. Keep installation/catalog evidence separate

from actual task results. A daemon using a pinned plugin copy also needs the

[pin-update workflow](daymade-claude-code/claude-switch-models-setup/references/troubleshooting.md#advance-the-pin).

Do not treat a merged source change as proof that this runtime advanced.

+ For recorder deployment, follow that workflow's ordinary-copy migration and

+ link readback; retaining a LaunchAgent wrapper does not update its files.

The syncer's managed marketplace identities, conventional checkout candidates,

and generated watch paths are owned by `sync-local-skill-sources.py`; derive them

from its constants/functions and `--print-watch-paths` output instead of copying

their current members or counts into instructions or references.

For context-window setting changes, keep the executable configuration and the

[context request probe](daymade-claude-code/claude-switch-models-setup/references/context-window-config.md)

aligned. That reference owns the request fields and probe commands.

In Claude Code, use `/plugin ...` slash commands. In your terminal, use `claude plugin ...`.

### Source Location Guard for Skill Edits

Before editing an existing skill, verify the **source** path, not just the path currently loaded by Codex / Claude Code.

Treat these as installed copies unless proven otherwise:

- `~/.codex/skills/<skill-name>`

- `~/.claude/skills/<skill-name>`

- `~/.agents/skills/<skill-name>`

- `~/.claude/plugins/cache/...`

- `~/.codex/plugins/cache/...`

The source for this marketplace is this repository. For single-skill plugins, edit:

```bash

<repo-root>/<skill-name>/SKILL.md

```

For suite skills, edit:

```bash

<repo-root>/<suite-name>/<skill-name>/SKILL.md

```

Required workflow before any skill edit:

```bash

pwd

git rev-parse --show-toplevel

rg -n '"name": "<skill-or-suite-name>"' .claude-plugin/marketplace.json

find . -path '*/SKILL.md' -maxdepth 4 | rg '(^|/)<skill-name>/SKILL.md$'

```

After editing, commit and run `scripts/ci/validate_changed_skills.sh origin/main` (it examines the committed

diff, so it sees nothing until you commit). It runs the same per-skill `quick_validate` the CI uses;

repo-level `claude plugin validate --strict .` passes even when a description exceeds the 1024-character

cap, so a green repo-level validate is not evidence the touched skill will pass.

If the user gives a source path, use that path. If the available skill list points to a different installed copy, update the source first, then sync the installed copy only if the user explicitly needs the current session to use the new version immediately.

### Git Operations

This repository uses standard git workflow, but **always stage files by name**,

never `git add -A` / `git add .`. Multiple agents may have unstaged changes in

the same worktree — a blanket stage piggybacks their work into your commit:

```bash

git status

git add path/to/file1 path/to/file2 # specific files only

git diff --cached --name-status # every staged entry (`D` lines included) must be one you intended; a `D` you never made = drift from a parallel session's index-bypassing commit — see git-safety-net Mode D

git commit -m "message"

git push

```

For recovery or repository convergence under concurrent work, treat

`git-safety-net/SKILL.md` as the canonical authorization and evidence router. It owns the

change-authorized / inspect-only / excluded partition, the scoped-vs-exhaustive audit

boundary, and authorized temporary-backup retirement;

do not copy its detailed commands here or treat a visible collaborator ref/worktree as a cleanup

target merely because it appears in the inventory.

For GitHub-hosted state — PRs, issues, Actions, repository or organization settings, permissions,

and API/UI mutations — treat `github-ops/SKILL.md` as the canonical operating contract. A command

receipt is not completion; use that Skill's operation-specific independent readback. Keep detailed

GitHub SOPs there rather than copying them into this repository-level instruction file.

**Closing a PR unmerged (declined, or superseded by another PR) → delete its head

branch in the same action.** `gh pr merge --delete-branch` only covers merged PRs.

⚠️ Deleting the branch does NOT remove `refs/pull/<N>/head` — GitHub keeps serving

that ref, so the commits remain publicly fetchable by anyone who fetches it, and the

branch listing (plus the weekly `stale-branch-watch`, which only sees branch refs)

loses sight of the residue. Branch deletion closes the *discoverable* surface, which

is still worth doing at close time. But if the content needs **sanitizing**, branch

deletion alone is cosmetic — first move the pull ref to a sanitized commit (reopen

the PR → push the fix → close again; pushes do not move a *closed* PR's ref), then

delete the branch, and accept that the old SHAs stay addressable from GitHub's object

cache until GC — a guaranteed purge requires a GitHub support ticket. (2026-08-17: a

closed-superseded PR's branch carried an unsanitized fixture for 13 days after the

fix was written; the pull ref had to be moved via the reopen dance before deletion.)

### Local `main` Is a Read-Only Mirror

Squash-merged PRs rewrite commits under new SHAs, so every direct commit to

local `main` guarantees divergence the moment its PR merges. These rules keep

`main` clean:

`.githooks/pre-commit` and `.githooks/pre-push` dispatch to

`scripts/git-mainline-guard.mjs`, which rejects direct local-main work and stale

marketplace manifests or reused plugin versions against current main. The

dispatchers preserve the shared PII guard when it is installed. Activate this

repository **from the canonical primary main checkout** with

`git config core.hooksPath "$(pwd -P)/.githooks"`. The absolute path matters:

`core.hooksPath` is shared by linked worktrees, so a relative path would let a

stale feature worktree select its own stale dispatcher. CI and the GitHub main

ruleset independently require the same release checks on every PR.

**Push through the remote name, never a bare URL.** The guard resolves the

remote from its argument (`process.argv[3]`) and then fetches

`<remote> refs/heads/main:refs/remotes/<remote>/main` to judge the push against

current main. Handed a bare URL it therefore builds the refspec

`refs/remotes/https://github.com/…/main` and dies with

`fatal: invalid refspec` followed by `could not refresh current main` — which

reads like a network failure and is not (five retries against it change

nothing). From a linked worktree, push over HTTPS with a token without editing

repository config by overriding per invocation:

```

git -C <worktree> \

-c remote.origin.url=<https-url> -c remote.origin.pushurl=<https-url> \

push origin HEAD:refs/heads/<branch>

```

1. **Never commit directly to local `main`.** All work starts on a feature

branch (`git checkout -b <topic>`), ships via PR, and lands by squash merge.

2. **After every merge, run the post-merge ritual:** `git checkout main && git pull --ff-only`.

A successful ff-only pull proves nobody broke rule 1. If it fails, someone

committed to local `main` — inspect `git log origin/main..main` and rebase

the stray commits onto a feature branch; do not merge or force-push `main`.

3. **If step 2's `git checkout main` itself refuses** ("local changes would be

overwritten") while you're still on your feature branch: this is not

automatically the divergence case above. Check whether local `main` is

merely **stale** (nobody committed to it, it just never got its ref

updated after a previous merge) before assuming divergence — `git diff

HEAD origin/main -- <the-file>` from your feature branch; empty output

means your branch's committed content already matches `origin/main`

exactly, and the checkout conflict is purely local `main`'s ref being

behind. Fix without touching the working tree or any other session's

uncommitted changes: `git fetch origin main:main` (updates the ref

directly, no checkout needed), then retry `git checkout main`. Only fall

through to the divergence procedure below if the diff is non-empty.

4. **Treat `pull --ff-only` as a whole transaction, not a per-file one.** It

refuses when *any* file it would update carries local modifications — and

that file may belong to another session and be untouched by your branch.

One peer's uncommitted file therefore blocks the update of every other file

in the same pull, which is how a shared checkout stays behind `origin/main`

while every signal you checked still looks fine. Before assuming

divergence, list what the pull would touch and check each path:

`git diff --name-only main origin/main`, then

`git status --porcelain=v1 -- <that-path>`. When the blocking file is not

yours and is still being written, leave it alone and report the baseline

SHA, who was asked, and that the ff is still outstanding — do not stash,

`checkout --`, or `restore` it.

If local `main` has already diverged: do not `reset --hard` until every stray

commit is proven superseded — mechanical test: cherry-pick them onto

`origin/main` resolving conflicts toward the upstream version; an empty net

result means the content already shipped. Back up first

(`git bundle create /tmp/main-backup.bundle main` and verify it restores).

## Skill Writing Requirements

### Writing Style

Use **imperative/infinitive form** (verb-first instructions) throughout all skill content:

- ✅ "Extract files from a repomix file using the bundled script"

- ❌ "You should extract files from a repomix file"

### YAML Frontmatter Requirements

Every SKILL.md must include:

```yaml

---

name: skill-name

description: Clear description with activation triggers. This skill should be used when...

---

```

### Privacy and Path Guidelines (Enforced by Pre-commit Hook)

Skills for public distribution must NOT contain:

- Absolute paths to user directories (`/home/username/`, `/Users/username/`)

- Personal usernames, company names, product names

- Phone numbers, personal email addresses

- OneDrive paths or environment-specific absolute paths

- Use relative paths within skill bundle or standard placeholders (`<workspace>/`, `<user_id>`)

**Defense layers:**

1. **CLAUDE.md rules** (this section) — Claude avoids generating sensitive content

2. **Global PII Guard pre-commit hook** (`~/scripts/git-pii-guard/pre-commit`) — blocks staged PII/secrets and generated/local artifact paths

3. **Global PII Guard pre-push hook** (`~/scripts/git-pii-guard/pre-push`) — scans commits about to be pushed, catching bad local history before it hits GitHub

4. **gitleaks** (`.gitleaks.toml`) — deep scan with custom rules for this repo

5. **AI semantic read-through** — pattern-based scans only match patterns someone listed, and are blind to private content with **no keyword** — a real name in another language (gitleaks doesn't cover CJK), a verbatim line from a real transcript, a real example dropped into an illustration. Before publishing, **read the whole skill yourself and judge each concrete name/example/snippet semantically** ("generic placeholder / public entity, or lifted from a real project / person / transcript?"). A green scan is **not** a clean bill of health; "grep found nothing" only means your word list didn't fire. Method: [`daymade-skill/skill-creator/references/sanitization_checklist.md`](./daymade-skill/skill-creator/references/sanitization_checklist.md).

Most repositories enable PII Guard via `~/scripts/git-pii-guard/manage.sh enable <repo-path>`. This repository instead points `core.hooksPath` at the canonical primary checkout's absolute `.githooks` directory: its versioned dispatchers run the repository mainline guard and then delegate to the same shared PII guard when installed.

For repo-specific additions:

- `.pii-patterns` — extra content regexes

- `.pii-path-patterns` — extra forbidden path regexes

- `.pii-allowpaths` — explicit path allowlist exceptions

- `.pre-commit-config.yaml` — optional repo-local runner that wires `pre-commit` framework to the same path/content rules for contributors who prefer managed hooks

If it fires, fix the issue — do NOT use `--no-verify` to bypass.

### Content Organization

- Size SKILL.md by information density, not a line-count target

- Move detailed documentation to `references/` files

- Avoid duplication between SKILL.md and references

- Keep `tunnel-doctor` environment-neutral: it may teach discovery and presence checks, but exact private node labels, billing identities, endpoints, credentials, and current chain state remain in the owning private configuration/Skill and must not be copied into this public repository.

- Scripts must be executable with proper shebangs

- All bundled resources must be referenced in SKILL.md

## Marketplace Configuration

The marketplace is configured in `.claude-plugin/marketplace.json`:

- Contains plugin entries: single-skill plugins point `source` directly at the skill directory (no `skills` field); any plugin entry with a non-empty `skills` array is a suite and uses those relative paths for multi-skill routing

- Each plugin has: name, description, source, version, category, keywords

- Marketplace metadata: name, owner, version

- Single-skill plugins follow the official pattern: `source` points to the Skill directory and `skills` is omitted

- **All suite plugins are suite-only.** Derive the current suite set from non-empty `plugins[].skills`; do not maintain another name list here. Users install the suite and invoke members as `<suite>:<skill>`. When adding a member, update only the suite entry's `skills` array — do NOT create a parallel standalone plugin entry.

### Versioning Architecture

**Version tracking layers:**

1. **Marketplace Version** (`.claude-plugin/marketplace.json` → `metadata.version`)

- Tracks the marketplace catalog as a whole

- Bump when: Adding/removing skills, adding/removing suite plugins, major marketplace restructuring

- Semantic versioning: MAJOR.MINOR.PATCH

2. **Individual Skill Versions** (`.claude-plugin/marketplace.json` → `plugins[].version`)

- Each skill has its own independent version

- Bump when: Updating that specific skill

- **CRITICAL**: Skills should NOT have version sections in SKILL.md

**Key Principle**: SKILL.md files should be timeless content focused on functionality. Versions are tracked in marketplace.json only.

### ⚠️ Updating Existing Skills (MANDATORY)

Changes to a skill's shipped files require a version bump in

`marketplace.json`.

**Version bump rules:**

- Content/doc updates (new sections, rewritten principles) → bump **MINOR** (1.0.1 → 1.1.0)

- Bug fixes, typo fixes → bump **PATCH** (1.0.1 → 1.0.2)

- Breaking changes (renamed commands, removed features) → bump **MAJOR** (1.0.1 → 2.0.0)

**Pre-commit check:** Before committing, run `git diff --name-only` and verify: for every `skill-name/` directory that appears, `marketplace.json` also has a version bump for that skill's `plugins[].version`.

**Read the baseline version from an immutable ref, never from the working tree.**

In a shared checkout `marketplace.json` may already carry a parallel session's

in-flight bump — staged or merely saved — and `git status` looks normal either

way, so a version computed from the working copy silently inherits their number

as its starting point:

```bash

git show origin/main:.claude-plugin/marketplace.json # baseline to bump FROM

```

This is what makes the check above decidable. `git diff --name-only` tells you

*which* skills changed; only an immutable ref tells you what their versions were

before anyone started editing. (2026-09-04: a bump computed from the working

tree adopted another session's staged `peer-message` 1.1.1→1.2.0 as its own

baseline. Every status-shaped signal stayed green; a CHANGELOG anchor assertion

was the only thing that caught it.)

## Available Skills

Current plugin names, versions, sources, and suite membership are defined only

in `.claude-plugin/marketplace.json`. Use README.md / README.zh-CN.md for the

human-readable capability guide; do not maintain another numbered Skill snapshot

in this model-loaded file.

## YouTube Downloader SOP (Internal)

See [youtube-downloader/references/internal-sop.md](./youtube-downloader/references/internal-sop.md) for yt-dlp troubleshooting steps (PO tokens, proxy, cookies, etc.).

## Python Development

All Python scripts in this repository:

- Use Python 3.10+ syntax

- Include shebang: `#!/usr/bin/env python3`

- Are executable (chmod +x)

- Have no external dependencies or document them clearly

- Follow PEP 8 style guidelines

## Quality Standards

For changes to scripts, configuration, or operating procedures, use

[docs-cleaner](daymade-docs/docs-cleaner/SKILL.md) for scoped documentation delivery:

resolve implementation intent and authorization before updating the owning SOP,

and validate the delivered command examples. Keep detailed governance in that Skill.

Before submitting or modifying skills:

- Valid YAML frontmatter with required fields

- Description includes clear activation triggers

- All referenced files exist

- Scripts are executable and tested

- No absolute paths or user-specific information

- Comprehensive documentation

- No TODOs or placeholders

## Adding a New Skill to Marketplace

Follow [Adding a New Skill to Marketplace](references/new-skill-guide.md) for

registration, README updates, validation, and publication. Use the existing suite

identity when adding a member; do not introduce a parallel standalone plugin.

The local-availability gate under **Testing Skills Locally** applies when local

use is part of the requested delivery.

## Chinese User Support

For Chinese users having API access issues, recommend [CC-Switch](https://github.com/farion1231/cc-switch):

- Manages Claude Code API provider configurations

- Supports DeepSeek, Qwen, GLM, and other Chinese AI providers

- Tests endpoint response times to find fastest provider

- Cross-platform (Windows, macOS, Linux)

See README.md section "🇨🇳 中文用户指南" for details.

## Handling Third-Party Marketplace Promotion Requests

Decline all third-party marketplace promotion requests. For policy, response template, and precedents, see [references/promotion-policy.md](./references/promotion-policy.md).

## External Contributor PRs (Curation Policy)

**Policy SSOT: [CONTRIBUTING.md](./CONTRIBUTING.md)** — this is a curated marketplace of our own skills; bug fixes are welcome, new-skill PRs are not accepted.

Agent rules when an external PR appears:

- **Never merge external PRs unilaterally.** Every external-PR merge decision goes to the user first, no matter how small or obviously-correct the fix looks. (2026-07-19: an agent batch-merged 4 external PRs under an ambiguous "merge what's left" instruction, including a whole new contributor skill the policy would never have accepted — it had to be reverted. Ambiguous instruction + other people's work = ask first, always.)

- **Bug-fix PRs** (after the user approves): land the repo bookkeeping as a maintainer follow-up — version bump in `marketplace.json`, CHANGELOG entry, README sync where applicable. Contributor PRs usually lack these.

- **New-skill PRs**: close with the standing message in CONTRIBUTING.md.

## Best Practices Reference

Always consult Anthropic's skill authoring best practices before creating or updating skills:

https://docs.claude.com/en/docs/agents-and-tools/agent-skills/best-practices.md

Infrastructure/SRE operating contracts stay in their owning Skills rather than this repository guide:

`terraform-skill` owns generic Terraform release safety and environment-parity rules; an application's

project-level health-check Skill owns that application's concrete audit facets. Keep those two layers

aligned without copying project hostnames, variable lists, or rollout commands into this file.

## Plugin and Skill Architecture

For full architecture documentation (core concepts, installation flow, data flow, common misconceptions, best practices), see [references/plugin-architecture.md](./references/plugin-architecture.md).

## Plugin and Skill Troubleshooting

For systematic debugging steps (common errors, debugging process, pitfalls, real-world examples), see [references/plugin-troubleshooting.md](./references/plugin-troubleshooting.md).

For maintainer source/install/catalog drift, use **Testing Skills Locally** above.

Identify the failing layer before updating a marketplace or reinstalling a plugin.

## Cloudflare mail operations

For domain forwarding diagnosis, use [Email Routing](cloudflare-troubleshooting/references/email-routing.md) through the owning Cloudflare Skill. Keep its endpoint sequence and delivery evidence contract in that reference.