Claude Code Skills Marketplace — Project Context

This repository is the Claude Code Skills Marketplace. It contains reusable skills for Claude Code. Each skill is a plugin directory under skills/. The directory contains SKILL.md (the instructions), metadata.json (machine-readable metadata), and README.md (documentation for people).

In this repository, help build, validate, and publish skills. Obey the conventions below.

Contribution Conventions

• Use kebab-case for skill directory names, for example git-workflow.
• Give each skill directory this structure: SKILL.md at the plugin root (with YAML frontmatter), metadata.json, README.md, and .claude-plugin/plugin.json.
• Do not make a commands/ directory. The project removed that legacy layout; see docs/decisions/0001-migrate-to-skill-md-layout.md.
• A multi-skill plugin uses skills/<sub-skill>/SKILL.md and has no root SKILL.md. Only agent-based-development uses this layout.
• Make sure that metadata.json agrees with schema/metadata.schema.json.
• Scaffold a new skill with ./scripts/new-skill.sh <name>. The script makes the full directory, including .claude-plugin/plugin.json, and adds the skill to registry.json and marketplace.json.
• After you add a skill directory, run ./scripts/check-registry.sh. Edit registry.json and marketplace.json by hand only for a skill that you made without the script.
• After you create or edit a skill, run ./scripts/validate.sh skills/<skill-name>.
• Distribute skills only through the Claude Code marketplace. There is no install script. Tell users to add this repository as a marketplace in ~/.claude/settings.json.
• Do not change skills/example-skill/. It is the reference for contributors.

Pre-Commit Checklist (MANDATORY — run before every commit)

Do all of these checks before each commit. CI fails if one fails.

1. Validate skill structure. Run ./scripts/validate.sh skills/<name> for each changed skill.
2. Sync registry versions. The version in skills/registry.json must be the same as the version in metadata.json for each skill. Change registry.json each time that you increase a skill version.
3. Increase versions. Increase the version of each skill whose SKILL.md, supporting files, metadata.json, or README.md changed. Write the new version in all four places: metadata.json, skills/registry.json, .claude-plugin/marketplace.json, and skills/<name>/.claude-plugin/plugin.json. Use a patch increase for a fix. Use a minor increase for a new feature or a layout change.
4. Run ShellCheck. Run shellcheck scripts/*.sh tests/*.sh. All scripts must pass with no errors.
5. Run markdownlint. Run npx markdownlint-cli2 "skills/**/*.md" "*.md". Do not use bare URLs. Put each email address and URL in backticks or angle brackets.
6. Check registration and version sync. Run ./scripts/check-registry.sh to make sure that the registry lists each skill directory. Run ./scripts/sync-versions.sh --check to make sure that the versions agree in metadata.json, registry.json, marketplace.json, and plugin.json.
7. Run the tests. Run bash tests/run-all.sh. CI runs the same suite.

Golden Rules

GOLDEN RULES (MANDATORY — ALL WORK IN THIS PROJECT MUST FOLLOW THESE)

1. Security is paramount. Every design, implementation, and review decision must prioritize security. When in doubt, choose the more secure option and document the assumption in docs/assumptions.md.
2. Do not store secrets, passwords, keys, PII, or other sensitive data insecurely.
   • Passwords: Hash with a strong adaptive function (Argon2id, bcrypt, scrypt). Never store plaintext or reversibly encrypted passwords.
   • Password policy (NIST SP 800-63B-4): no composition rules and no forced periodic rotation (change only on evidence of compromise); screen new passwords against breached and common-password lists; accept long passphrases (at least 64 characters) and allow paste and password managers.
   • MFA: offer phishing-resistant authentication (passkeys / WebAuthn) and prefer it over SMS or OTP codes.
   • API keys, tokens, secrets: Use environment variables or a secrets manager. Never commit to the repo or log.
   • PII: Encrypt at rest and in transit. Minimize collection and retention. Follow applicable privacy rules.
   • Other sensitive data: Use encryption or hashing as appropriate. Document non-obvious choices in docs/assumptions.md.
3. Always assume the application could be the target of exploitation. Design for untrusted input, defense in depth, least privilege, and secure defaults. Document any accepted risks in docs/assumptions.md.
4. All inputs must be sanitized, length-checked, typed (where the language supports it), and exercised by unit tests. All exceptions must be trapped and handled — never allow an unhandled exception to propagate to the user or crash a process silently.
   • Sanitize: strip, escape, or reject untrusted input before use in queries, templates, file paths, shell commands, or downstream calls.
   • Bound: enforce explicit maximum lengths/sizes on every input (request bodies, headers, query params, file uploads, buffers). In memory-unsafe languages (C, C++, unsafe Rust, cgo), check buffer sizes before every copy/read/write — no strcpy, gets, sprintf, or unbounded memcpy. Use strncpy/snprintf/bounded equivalents.
   • Type: use static types or runtime schema validation (Zod, Pydantic, JSON Schema, or language equivalent) at every boundary.
   • Test: every input handler and parser must have unit tests covering valid input, invalid input, boundary/oversized input, and the exception path. Each Golden Rule above (sanitization, length bounds, exception handling) must be verified by at least one test per handler.
   • Handle: every thrown or returned error must be caught, logged with context, and converted to a meaningful response or recovery action. No empty catch blocks. No bare except: or catch (Throwable) that hides the failure.
5. AI-generated copy must be free of AI'isms and other telltale signs of machine-written content. This applies to all user-facing text, marketing copy, docs, READMEs, commit messages, and comments produced with AI assistance.
   • Forbidden phrases (non-exhaustive): "delve into", "in today's fast-paced world", "it's important to note", "navigate the landscape", "unleash", "leverage" (as a verb), "tapestry", "embark on a journey", "in the realm of", "game-changer", "revolutionize", "seamlessly", "robust solution", "cutting-edge", "elevate your", "at the end of the day", "boasts", "testament to".
   • Forbidden patterns: gratuitous tricolons ("X, Y, and Z" stacked in every sentence), em-dash sandwiches in every paragraph, "Not only… but also…" constructions, hedging openers like "Certainly!" or "Absolutely!", closing summaries that restate the obvious, emoji bullets in serious copy.
   • Write like a human who has read the codebase: specific, concrete, and grounded in the actual subject. If a sentence would survive deletion without losing information, delete it. Edit AI output before shipping — never paste raw model output into customer-facing surfaces.

CODING & NAMING GUIDELINES (apply unless project explicitly overrides in docs/assumptions.md)

• camelCase for variables, functions, and filenames (see language-specific table below).

• Language-specific naming conventions:

  Language	Variables/Functions	Files	Classes
  JavaScript/TypeScript	camelCase	camelCase	PascalCase
  Python	snake_case	snake_case	PascalCase
  Go	camelCase (unexported) / PascalCase (exported)	snake_case	PascalCase
  SQL	snake_case	snake_case	N/A
  CSS classes	kebab-case	kebab-case	N/A

• Strict typing and schema validation (e.g. Zod, Pydantic, or language-equivalent) for all inputs and boundaries.
• No hardcoded API keys, credentials, or secrets — use configuration or secrets management.
• No placeholder or stub code in production paths — write complete, functional code.
• Move task notes to docs/ToDo.md or docs/ — do not leave // TODO in the codebase for project tracking.
• Remove dead code before committing — commented-out code blocks, unused imports, unreachable functions, and orphaned files are not acceptable in production paths.

DESIGN & UX GUIDELINES (apply unless project explicitly overrides)

• Caching: Prefer designs that support caching where appropriate (HTTP cache headers, CDN, app-level) to improve performance.
• Light and dark mode: Support both themes with easy switching (toggle, system preference, or both). Persist user preference.
• Visual design: Prefer minimalist, clean designs. Avoid clutter; use clear hierarchy and whitespace.
• Responsive design: Layouts must be responsive — usable across mobile, tablet, and desktop. Use fluid layouts and touch-friendly targets.
• Accessibility: Choose accessible and pleasant color palettes. WCAG 2.2 AA contrast minimum. Do not rely on color alone for meaning.

GIT HYGIENE (MANDATORY)

• Never commit or push directly to main. All changes must go through a branch and PR, no exceptions.
• Branch from the current release branch (or main if no release branch exists). Name branches feature/, fix/, hotfix/, or claude/ as appropriate.
• If you find yourself on main with uncommitted changes, stash or move them to a new branch before committing.
• PRs targeting shared or release branches require at least one approval from a reviewer other than the author. For solo-maintainer repositories, self-merge is permitted — but CI must pass and the author must self-review the diff before merging.

TESTING STANDARDS (MANDATORY)

• Every module with logic must have corresponding tests. No untested business logic in production.
• Name tests descriptively: test_<unit>_<scenario>_<expected> or describe/it equivalents. A failing test name must explain what broke.
• Test behavior, not implementation. Mock external dependencies; do not mock the unit under test.
• Write the test first when fixing a bug — reproduce it as a failing test, then fix.
• Do not test framework internals, trivial getters/setters, or auto-generated code.
• Integration tests must cover critical paths: auth flows, payment flows, and data persistence boundaries.
• Tests must be deterministic — no flaky tests. Remove or fix any test that fails intermittently.

ERROR HANDLING (MANDATORY)

• Never swallow exceptions silently. Every catch block must log, re-throw, or return a meaningful error.
• Use structured error objects with a machine-readable code, human-readable message, and optional context. No bare string throws.
• Log errors with severity level, timestamp, request/correlation ID, and enough context to reproduce. No PII in logs.
• Distinguish client errors (4xx / validation) from server errors (5xx / unexpected). Return appropriate status codes.
• Fail fast on invalid state. Validate preconditions at function entry; do not let bad data propagate.
• Define and use a project-wide error hierarchy or error code enum. No ad-hoc error strings scattered across the codebase.

API & DATA CONTRACTS (MANDATORY)

• Validate all inputs at system boundaries with schema validation (Zod, Pydantic, JSON Schema, or equivalent). Reject invalid payloads before processing.
• Sanitize all user-supplied strings before use in queries, templates, or downstream calls. Assume all external input is hostile.
• Version APIs explicitly (URL path, header, or query param). Never introduce breaking changes to an existing version.
• Backward compatibility is required for at least one prior version. Deprecate before removing — never drop fields or endpoints without notice.
• Document every public endpoint or contract with request/response schemas. Undocumented APIs are not shippable.
• Use consistent naming across all API surfaces: plural resource nouns, standard HTTP verbs, consistent date/enum formats.

PERFORMANCE BASICS (MANDATORY)

• No N+1 queries. Use eager loading, joins, or batch fetches. Profile queries on realistic data volumes before shipping.
• All list endpoints must support pagination. No unbounded result sets. Default to reasonable page sizes.
• Use async/non-blocking I/O for network calls, file I/O, and any operation that can block the event loop or thread pool.
• Cache expensive computations and frequently-read data. Define TTLs and invalidation strategy — no stale-forever caches.
• Set timeouts on every external call (HTTP, DB, queue). No indefinite waits. Define retry policy with backoff for transient failures.
• Do not optimize prematurely, but do not ship known O(n^2) or worse algorithms on unbounded inputs. Document accepted performance trade-offs in docs/assumptions.md.
• Watch for memory leaks and race conditions. Long-lived processes must release listeners, timers, subscriptions, and connection pools. Concurrent access to shared state must be guarded by locks, atomics, transactions, or message passing — never assume "it works in dev."

LOGGING & OBSERVABILITY (MANDATORY)

• Emit structured logs (JSON or logfmt) with: timestamp, level, message, request/correlation ID, and contextual fields. No print / console.log for production code paths.
• Log every security-relevant event with enough context to investigate later: failed logins, successful logins from new IPs, password resets, permission changes, MFA challenges, account lockouts, rate-limit trips, CSRF/origin rejections, suspicious input rejections.
• Log every outbound integration event: email sends (provider, message ID, recipient hash, status), SMS sends, payment attempts, webhook deliveries, third-party API failures, retries, and timeouts. Include the upstream response code.
• Never log secrets, passwords, full tokens, full PAN/SSN/keys, or raw PII. Hash, redact, or omit. Log a stable correlation ID instead of the raw subject.
• Emit metrics for: request rate, error rate, p50/p95/p99 latency, queue depth, background job success/failure counts, external dependency latency, and the security/integration events above (auth_failures_total, email_send_failures_total, etc.).
• Wire alerts to the metrics that actually indicate user pain or breach risk. Alerts without an owner and a runbook are noise — remove them.

HEALTH CHECKS & UPTIME MONITORING (MANDATORY)

• Every deployable service must expose a /healthz (liveness) and /readyz (readiness) HTTP endpoint. Liveness reports "the process is up"; readiness reports "this instance can serve traffic right now" and fails when dependencies are unhealthy.
• Provide a deeper /health (or /status) endpoint that synthetically checks each critical dependency the service relies on: primary database, cache, queue, object storage, search index, and every third-party API in the request path (e.g. Resend or other email providers, Stripe, auth provider). Each dependency reports ok / degraded / fail with the last check timestamp and latency.
• The dependency check must also verify credential validity where the upstream supports it (e.g. token introspection, low-cost authenticated call) so expired API keys are caught before users hit them.
• Health endpoints must not require authentication for liveness/readiness, but the detailed dependency endpoint must not leak secrets, connection strings, or internal hostnames. Return HTTP 200 when healthy and 503 when not, so external monitors (NodePing, UptimeRobot, Pingdom, CloudFlare health checks) can alert correctly.
• Configure an external uptime monitor (e.g. NodePing) against the public URL and the deep health endpoint, with alerting routed to the on-call channel. A service without an external monitor is unmonitored.

CACHING & CDN (MANDATORY)

• Treat cacheability as a design decision per route. For every public response, set explicit Cache-Control, ETag/Last-Modified, and Vary headers — never rely on framework defaults.
• Static assets and immutable content (hashed filenames, versioned URLs, public marketing pages): Cache-Control: public, max-age=31536000, immutable. Serve through the CDN.
• Cacheable HTML / API responses: pick a deliberate s-maxage for the CDN and a shorter max-age for the browser. Use stale-while-revalidate for low-risk content.
• Non-cacheable responses (authenticated user pages, dashboards, mutation responses, anything containing PII or per-user data): Cache-Control: private, no-store and ensure Set-Cookie responses bypass shared caches. Audit any route that returns user-specific data to confirm it is not cached publicly.
• Provide an explicit cache-purge path for content that can change (deploy hook, admin action, or webhook → CDN purge API). Stale-forever caches are a bug.
• If hosted on CloudFlare, follow CloudFlare's published guidance: use Cache Rules (not deprecated Page Rules) for cache behavior, set Tiered Cache where it helps, use Cache Reserve only for content that justifies it, configure Bot Fight Mode / WAF / rate-limiting rules at the edge, set Origin Rules to strip cookies on static paths so they remain cacheable, and use the CF-Cache-Status header in monitoring to confirm hit ratio. For SPA/SSR apps, follow CloudFlare's framework-specific guidance (Workers, Pages, or the documented cache-key recipe for the framework in use).

CODE EFFICIENCY & DEPENDENCY HYGIENE (MANDATORY)

• Every line of code must have a clear purpose. No speculative abstractions, no dead branches, no unused exports, no "just in case" features.
• Minimize dependencies. Before adding a new package (npm, pip, cargo, NuGet, gem, go module), justify it: does the value outweigh the size, security surface, and maintenance cost? Prefer the standard library or a small focused implementation.
• Minimize binary and bundle size. Avoid heavyweight libraries when a small utility will do. Watch for dependency explosions — transitive bloat counts.
• Prefer clarity over cleverness. Avoid deep inheritance or abstraction layers that obscure what the runtime is actually doing — assume 80% of effort is debugging, so write code that is easy to step through.

RESOURCE STEWARDSHIP (MANDATORY)

• Treat RAM and CPU cycles as valuable commodities. Don't poll when you can subscribe; don't refresh when nothing changed; don't recompute what you can cache.
• Prefer async / non-blocking calls over sync calls when there is no added complexity penalty. Never block the UI thread on I/O (disk, network, IPC) — move it to a worker.
• Be cache- and allocation-aware in hot paths. Respect locality, batch work, and avoid unnecessary allocations or memory fragmentation, especially in native code (C/C++/Rust).
• Support a degraded or "lean" mode when the application could run on resource-constrained hardware. Failing to start is worse than degraded operation.
• Truthful telemetry: performance metrics must reflect actual system state. Do not smooth, round, or fabricate numbers for UI aesthetics.
• Apply language- and platform-specific best practices. The rules above describe intent; idiomatic implementation is contextual to the stack and the goals of the project.

PLATFORM-SPECIFIC GUIDELINES (MANDATORY)

• Apple platforms (iOS, iPadOS, macOS, watchOS, tvOS, visionOS): Follow the Apple Human Interface Guidelines (HIG) for UX, layout, typography, motion, accessibility, and platform conventions. Prefer native frameworks (SwiftUI, UIKit, AppKit) and idiomatic Swift; respect Apple's review and entitlement rules where relevant.
• Android: Follow Google's Material Design and the Android Developer guidelines for UX, navigation, and architecture (e.g. Architecture Components, Jetpack). Use Kotlin idioms and follow Google's Kotlin / Java style guides.
• Linux applications and scripts: Follow Red Hat's documented best practices (Fedora Packaging Guidelines, RHEL system design guidance, systemd conventions) where they apply. Otherwise follow the most widely accepted conventions for the language and ecosystem — POSIX shell guidelines, the Linux Filesystem Hierarchy Standard, freedesktop.org specs, and the relevant distro packaging norms.
• Windows: Follow Microsoft's official guidance for the target stack — Fluent Design / WinUI for modern UI, Windows App SDK / .NET conventions, and Microsoft Learn documentation for APIs, security, and packaging (MSIX).
• Cross-platform code: When shared UI or behavior spans platforms, branch to honor each host's conventions rather than picking a lowest common denominator. Document any deliberate deviations from a platform's guidelines in docs/assumptions.md.

ASSUMPTIONS TRACKING

Any time a non-obvious decision is made, record it in docs/assumptions.md:

• Assumption: one clear sentence
• Why: rationale
• Recorded by: <agent or developer name>
• Date: YYYY-MM-DD

Project-Specific Rules

CLAUDE CODE PLUGIN & SKILL LAYOUT (MANDATORY)

Skills and plugins installed via the Claude Code plugin system must follow this layout so they are discovered automatically as slash commands:

skills/<skill-name>/            ← plugin root
  SKILL.md                      ← skill content with YAML frontmatter (name, description)
  metadata.json
  README.md
  .claude-plugin/
    plugin.json
  templates/ rules/ ...         ← optional supporting files, loaded on demand
  .scan-exempt                  ← optional reviewed scanner exemptions

• The skill file must be SKILL.md at the plugin root — NOT commands/<name>.md (legacy) and NOT skill.md.
• The YAML frontmatter in SKILL.md must include name (matching the directory) and description. Optional fields: model, effort, allowed-tools, argument-hint, disable-model-invocation, paths.
• A plugin shipping more than one skill uses skills/<sub-skill>/SKILL.md inside the plugin instead of a root SKILL.md (each frontmatter name matches its <sub-skill> directory). Only agent-based-development does this today.
• Reference supporting files from SKILL.md with markdown links so they load on demand; resolve bundled assets via ${CLAUDE_PLUGIN_ROOT} with a cwd fallback for local checkouts.
• Run ./scripts/validate.sh skills/<skill-name> after creating or editing a skill.
• Use ./scripts/new-skill.sh <name> to scaffold; it generates the correct structure automatically.

PYTHON ENVIRONMENT (MANDATORY)

• Never install Python packages into the OS Python install. Always use a virtual environment.
• Create a venv at the project root: python3 -m venv .venv
• Activate before running or installing: source .venv/bin/activate
• Add .venv/ to .gitignore — never commit it.
• Pin all dependencies in requirements.txt (or pyproject.toml). Use pip freeze > requirements.txt after installing.