# CLAUDE.md

## Repository Overview

This repository is a Claude Code skills marketplace.

**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)           # Update-owned 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.

For permission-sensitive fixtures, use its
[execution-context verification recipe](daymade-skill/skill-creator/references/stateful-script-verification.md#execution-identity-and-permission-fixtures).

For its audit, release, source-contract or materialization commands from another
working directory, use the [fixed command entry](daymade-skill/skill-creator/references/fixed-command-entry.md).

For saved HTML batches, follow [the conversion owner](daymade-docs/doc-to-markdown/references/html-conversion.md#gate-a-batch-through-the-existing-recipe)
and its actual-reader pilot before expansion. Keep conversion evidence and reader
observations separate; this file does not define another batch recipe.

When creating or changing an operational Skill's first-use setup or recovery
workflow, enter `skill-creator` and load its
[first-use and recovery contract](daymade-skill/skill-creator/references/first-use-and-resume.md).

For proxy-selection or disruptive VPN recovery changes, enter `tunnel-doctor` and its
proxy-conflict and network-recovery references. For automatic WeCom integration,
enter `setup-notifications-via-wecom`; its receipt contract owns accepted/rejected/unknown
handling, while the worker owns event identity and delivery state.

For Terraform publication, approval, first mutation, expired plans, environment isolation or
initialization-cache changes, enter [`terraform-skill`](terraform-skill/SKILL.md).
Its pre-deploy and release references own publisher preparation, native-expression verification and authorization;
its isolation reference owns backend/workspace identity and fresh-state validation.

For Deep Research or Kimi financial-research changes, enter the owning
[`deep-research`](deep-research/SKILL.md) or [`kimi-use`](kimi-use/SKILL.md) Skill.
Their linked references own the input handoff, download/export, run, source-archive, mode, and billing procedures;
the bundled CLIs own executable argument and validation behavior. Keep this file
as the route rather than a second copy of those procedures.

For customer-approved report forms, follow
[skill-creator's report-template contract](daymade-skill/skill-creator/SKILL.md#show-the-result-not-just-the-work).

For HTML report creation or updates, enter
[report-with-html's Define success workflow](report-with-html/SKILL.md#workflow)
for reader/use, evidence precision, delivery location and investigation acceptance.
Its [technical comparison reading order](report-with-html/references/visualization-patterns.md)
owns concrete plans, cost boundaries and next-verification choices; do not turn a research
shortlist into purchase or deployment approval.
Its [maintenance contract](report-with-html/references/long-lived-report-maintenance.md)
owns later reconciliation and consumer readback.

For HTML report images and explanatory diagrams, enter
[report-with-html](report-with-html/SKILL.md); its
[visual evidence workflow](report-with-html/references/visual-evidence.md) owns selection,
source verification, placement and review. Keep report-specific assets with the report.

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 creation, consolidation, Skill-entry enforcement, registration or recovery, load
[`daymade-claude-code:claude-code-hooks`](daymade-claude-code/claude-code-hooks/SKILL.md)
and follow its Build order and installer-owned recovery contract. Follow that
Skill's loop and reminder contract; keep current thresholds in the
owning implementation.

Python entry points registered as synchronous Claude Code/Codex lifecycle hooks or
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. An owning installer may support an already authorized
launcher; that does not make a package-manager dispatcher the default for
Python hooks.

### Background Full Disk Access repair

When a LaunchAgent cannot read protected data, enter
[`macos-permissions`](daymade-macos/macos-permissions/SKILL.md) and its
[automated repair SOP](daymade-macos/macos-permissions/references/automated-full-disk-access.md).
Identify the actual permission subject and reuse an existing usable grant when
the owning installer supports it. After repair, restart the job and verify a
protected read in its real background context; a GUI switch or foreground read
alone is not completion.

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
```

### Review and evaluation input preparation

When review, replay or evaluation needs input copies, follow
[the materialization SOP](daymade-skill/skill-creator/references/materialization-budget.md)
from the locked skill-creator project above. Its
[CLI](daymade-skill/skill-creator/scripts/materialize.py) owns argument parsing,
accounting, retry eligibility and cleanup behavior. For disk diagnosis, cleanup
recovery, or capacity checks before necessary backup/copy/extraction, use
[macos-cleaner](daymade-macos/macos-cleaner/SKILL.md) and its
[necessary-copy capacity preflight](daymade-macos/macos-cleaner/references/safety_rules.md#necessary-copy-capacity-preflight).
When changing measurement, run the SOP's targeted regression suite before shipping.

### Automated Test Suites (CI)

A `tests/` directory under a Skill does **not** automatically run in CI.
[The registry](scripts/ci/test-suites.txt) owns suite admission and membership;
[the dispatcher](scripts/ci/run_registered_tests.sh) owns their execution commands.
[The workflow](.github/workflows/ci.yml) owns job environments, dependency installation,
timeouts and additional test steps. For required-check readback, installation stalls,
test failures and temporary-Git cleanup, follow [CI operations](references/ci-operations.md).

For browser-backed recurring jobs, enter
[macos-watchdog](daymade-macos/macos-watchdog/SKILL.md) and apply its deployment
acceptance before shipping. That Skill owns resource-budget and focus evidence;
keep the detailed procedure there.

Before choosing or changing any periodic observer's cadence, follow
[macos-watchdog's observation contract](daymade-macos/macos-watchdog/references/probe-cost.md).
For changed operating defaults or thresholds in an already-required review, use
[skill-creator's independent-review protocol](daymade-skill/skill-creator/references/independent-review-protocol.md).
Keep decision criteria and verification details in those owners.

### 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).
For batch audio checks, use [verify_queue_audio.py](daymade-audio/transcript-fixer/scripts/verify_queue_audio.py)
and its [adjudication guide](daymade-audio/transcript-fixer/references/advanced_correction_evidence.md):
audio verification may add evidence but never resolves a review row or proves
whole-transcript completion.
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.
For local originals or an Obsidian delivery, follow the Skill's
[original-media and reader SOP](feishu-doc-scraper/references/original-media-and-reader.md).
That SOP owns archive-root containment, conversion versus delivery evidence,
and the source-catalog handoff to favorites-search. Respect the selected destination
and any user-excluded checks; do not substitute a different archive or acceptance claim.

### 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 Conversation History Boundary

For recent unfinished-request inventories, follow
[`local-conversation-history`](daymade-claude-code/local-conversation-history/SKILL.md).

For remembered facts or a repeated search request, use that router's evidence
selection contract. The provider readers own original-record retrieval;
[`read-codex-history`](daymade-claude-code/read-codex-history/SKILL.md#original-tool-and-record-evidence)
owns complete Codex tool evidence, and
[`hybrid history recall`](daymade-claude-code/read-claude-code-history/references/hybrid_history_recall.md#query)
owns indexed role/phrase filters. Keep commands and source-attribution rules in
those owners rather than copying them here.

Codex inventory must use the index-only command in
`daymade-claude-code/read-codex-history/SKILL.md`. If its state database is
unavailable, report an unknown inventory; do not substitute a raw rollout scan.
Edit shared reader code in `daymade-claude-code/_conversation_core/`, then run
`python3 daymade-claude-code/sync_core.py sync` and `check` before shipping;
bundled `scripts/_core/` copies are generated projections.
For Claude task-ending and cwd interpretation, enter `read-claude-code-history`
and its [local runtime and cwd contract](daymade-claude-code/read-claude-code-history/references/session_file_format.md#local-runtime-and-working-directory-evidence).
Use its [session-ending workflow](daymade-claude-code/read-claude-code-history/references/workflow_examples.md#inspect-session-endings)
for candidate selection and commands; keep the detailed rules in those owners.

### 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.

### Ghostty Terminal Sessions

For snapshotting, restoring or reconciling Claude Code / Codex sessions in Ghostty
across reboots, enter [`ghostty-use`](ghostty-use/SKILL.md). Its bundled script owns
liveness classification and the paste-restore + auto-reconciliation loop; keep the
storage-layout facts and macOS Ghostty limits in its references rather than here.
For change-only automatic backups, use its
[automatic workflow](ghostty-use/references/automatic-snapshots.md).

### 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, adjacent-reset attribution 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. For local
snapshot reconstruction, [scan_rollouts.py](tibo-reset-codex/scripts/scan_rollouts.py)
owns candidate output. An unfulfilled
reset promise or a question about missing execution signals enters the Skill's
[monitoring route](tibo-reset-codex/SKILL.md#监测轮从信息到可行动信号) and
[output contract](tibo-reset-codex/SKILL.md#输出合同先给结论再交代边界).
Before using a third-party date or Yes/No as a reset signal, check its source-post
chronology (an operator-entered event cites no source post), whether it observes
account quota changes or only classifies posts, and whether the monitor completed a
plausible-time check. The Skill owns the
detailed procedure.
[Next-reset forecast](tibo-reset-codex/references/next-reset-forecast.md) owns
date judgments; [forecast feedback](tibo-reset-codex/references/forecast-feedback.md)
owns recording, review and withdrawal, with
[forecast_log.py](tibo-reset-codex/scripts/forecast_log.py) as the executable
authority for CLI and local journal layout. Keep detailed commands and changing
account or forecast 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 Creation and Edits

Load [skill-creator](daymade-skill/skill-creator/SKILL.md) and follow its canonical
source preflight before the first write. Its shared source-contract checker owns
repository identity, marketplace registration and project-local placement; use
[skill-governance](daymade-skill/skill-governance/SKILL.md) for installation and
fresh-host readback. Keep source, installed entry and private review archive distinct.
A registered marketplace source does not prove the installed copy or current host advanced;
follow the consumed-file checks in that governance reference before claiming activation.

After committing, run `scripts/ci/validate_changed_skills.sh origin/main`; it checks
the committed diff. A repository-level plugin validation does not replace per-Skill
validation.

### 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.
For hosted-state writes through `gh`, follow its
[identity, host and target binding](github-ops/SKILL.md#2-bind-identity-host-and-target)
before using an operation recipe. For historical account or connector attribution,
use the [identity-source contract](tibo-reset-codex/references/account-usage.md#区分身份来源与观察时刻).

**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.
Use `github-ops`'s [exact-tip branch retirement workflow](github-ops/references/pr_operations.md#converging-parallel-prs-and-retiring-remote-branches).
For sensitive publication residuals, first enter `github-sensitive-data-cleanup`'s
[surface selection](github-sensitive-data-cleanup/SKILL.md#step-05-bind-each-exposed-surface);
approved PR body revision removal follows `github-ops`'s
[edit-history cleanup](github-ops/references/pr_operations.md#pr-body-edit-history-cleanup).
Keep detailed procedures and completion limits in those owners.

### 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:

Before pushing shipped Skill changes, follow
[skill release readiness](daymade-skill/skill-creator/references/release-readiness.md).
The existing pre-push entry checks committed current-review evidence for the exact head.

`.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 enforce version progression on PRs; private review
evidence is checked locally by pre-push, as defined in the linked release SOP.

**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. 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, read the current branch before updating the checkout.**
   If already on `main`, pull with `--ff-only` without another checkout. If the
   shared checkout is on another session's branch, coordinate before moving it.
   A failed pull is not proof of local-main commits: inspect its error and compare
   the local and remote refs to distinguish divergence, changed files, and a
   failed remote read. Do not merge or force-push `main` to bypass a refusal.
3. **If switching your own feature checkout to `main` is refused** ("local
   changes would be overwritten"): 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.

For divergent local `main` or branch/worktree retirement, follow
[git-safety-net](git-safety-net/SKILL.md) and its
[content-containment proof](git-safety-net/references/merge_verification.md).
Resolving conflicts toward upstream can erase the very delta being checked;
an empty result after that resolution does not prove it shipped.

## 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.
- Kimi desktop input and tunnel diagnostics follow the current host-specific procedures in `kimi-use/references/driving-kimi-app.md` and `tunnel-doctor/SKILL.md`; a proxy bypass recommendation requires compared path evidence.
- 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
- **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

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. **Plugin release identity** (`.claude-plugin/marketplace.json` → `plugins[].version`)
   - The registered plugin owns the release version. Suite members share their suite's
     version; a standalone Skill uses its own plugin entry.
   - Follow [skill-creator's versioning contract](daymade-skill/skill-creator/SKILL.md)
     for shipped-file changes and change classification.

### ⚠️ Updating Existing Skills (MANDATORY)

Use [skill-creator](daymade-skill/skill-creator/SKILL.md) to classify the change and
[packaging_policy.py](daymade-skill/skill-creator/scripts/packaging_policy.py) to
decide which changed files ship. Do not infer a separate member version from its directory.

For pre-commit release progression, use the existing
[version checker](scripts/ci/check_version_progression.py) through the
[mainline guard](scripts/git-mainline-guard.mjs). Its registered-plugin mapping and
the packaging owner above determine which release identity must advance.

**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.

**When the pre-commit guard blocks with "marketplace release state is stale or
incomplete"**: the staged `marketplace.json` diverges from current `origin/main`
in plugins you did *not* touch — someone merged after you branched, and the
guard's progression check compares your index against *current* main, not your
branch point. Recovery:

1. Rebuild `marketplace.json` from `origin/main`'s state plus **only** your
   changes, programmatically — assert the base values before mutating, never
   text-merge or hand-edit two versions:
   ```bash
   git show origin/main:.claude-plugin/marketplace.json   # the ONLY baseline
   # then apply your bump(s)/skills-array addition onto THAT content,
   # and preserve the file's trailing newline (json.dump drops it)
   ```
2. If the guard then reports a *foreign* plugin's "content changed but version
   did not increase": your branch is missing that plugin's merge entirely —
   bring the branch current with `origin/main`. On a contended shared checkout
   where `git merge` (ort) refuses your staged files: merge in a temporary
   worktree, copy the merged file back so staged content equals the merge
   result byte-for-byte, then `git merge --ff-only <merge-sha>` — a
   fast-forward accepts staged content that equals the target; ort never does.
3. Commit as a standalone command — `git add … && git commit` in one line trips
   the scope guard's unknown-domain branch (150-second dialog) regardless of
   content.

**CHANGELOG.md merges as a union** (`.gitattributes`). Merging `origin/main`
into a branch locally, or rebasing onto it, keeps parallel additions under
`## [Unreleased]`. Limits:

- GitHub's mergeability check ignores the attribute, so a PR can still show
  CONFLICTING until `origin/main` is merged into it locally.
- Git reads the attribute from the branch you are on. A branch cut before
  `.gitattributes` existed conflicts as before: commit the file onto it first
  (`git checkout origin/main -- .gitattributes`, then commit), then merge.

Read the merged section before you push. Union keeps lines, not structure:
lines can come out duplicated or interleaved, a blank line can go missing, and
across a release cut an entry can land under the new version heading instead of
`[Unreleased]`. The CHANGELOG structure check still fails a duplicated
`[Unreleased]` heading; it cannot see a misplaced entry.

## 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.
When a changed workflow affects stable rules or entry routes, update this file's
rules and indices; retain implementation values and detailed procedures in their SSOT.

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.
- **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

An application's project-level health-check Skill owns its concrete audit facets; keep project
hostnames, variable lists and rollout commands with that owner.

## 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.