CLAUDE.md

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

Repository Overview

Tons of Skills — Claude Code plugins marketplace (343+ plugins, 1,399+ skills). Live at https://tonsofskills.com

Monorepo structure: pnpm workspaces (v9.15.9+)

plugins/[category]/* - AI instruction plugins (Markdown, ~98% of plugins)
plugins/mcp/* - MCP server plugins (TypeScript, ~2%)
plugins/saas-packs/*-pack - SaaS skill packs (pnpm workspace members)
marketplace/ - Astro 5 website (uses npm, not pnpm - CI enforced)
packages/cli - ccpi CLI (@intentsolutionsio/ccpi on npm)
packages/analytics-* - Analytics daemon and dashboard

Package manager policy (CI-enforced by scripts/check-package-manager.mjs):

pnpm everywhere at root
npm for marketplace/ only (it's excluded from pnpm workspace)

Essential Commands

# Before ANY commit (MANDATORY)
pnpm run sync-marketplace           # Regenerate marketplace.json from .extended.json
./scripts/validate-all-plugins.sh   # Full plugin validation (JSON, frontmatter, refs, permissions)
./scripts/quick-test.sh             # Fast validation: build + lint + validate (~30s)

# Build & test
pnpm install && pnpm build          # Install and build all workspace packages
pnpm test && pnpm typecheck         # Run vitest tests and TypeScript checks
pnpm lint                           # ESLint across all packages

# Single MCP plugin
cd plugins/mcp/[name]/ && pnpm build && chmod +x dist/index.js

# Skills validation with 100-point grading
python3 scripts/validate-skills-schema.py --verbose      # All content (skills + commands + agents)
python3 scripts/validate-skills-schema.py --skills-only   # SKILL.md files only
python3 scripts/validate-skills-schema.py --commands-only  # commands/*.md only

# CLI package
cd packages/cli && pnpm test -- --grep "pattern"  # Run single test
cd packages/cli && pnpm build && node dist/index.js validate --strict  # ccpi validate

# Marketplace website
cd marketplace/ && npm run dev                    # Dev server at localhost:4321
cd marketplace/ && npm run build                  # Full build pipeline (see below)
cd marketplace/ && npm run validate               # Route + link validation
cd marketplace/ && npx playwright test            # E2E tests (chromium + webkit)

Two Catalog System (Critical)

File	Purpose	Edit?
`.claude-plugin/marketplace.extended.json`	Source of truth with extended metadata	Yes
`.claude-plugin/marketplace.json`	CLI-compatible (auto-generated)	Never

sync-marketplace strips extended-only fields: featured, mcpTools, pluginCount, pricing, components, zcf_metadata, external_sync.

Run pnpm run sync-marketplace after editing .extended.json. CI fails if out of sync.

Auto-Generated Data Files (Never Hand-Edit)

File	Generated by
`.claude-plugin/marketplace.json`	`pnpm run sync-marketplace`
`marketplace/src/data/catalog.json`	`sync-catalog.mjs` (build step 2)
`marketplace/src/data/skills-catalog.json`	`discover-skills.mjs` (build step 1)
`marketplace/src/data/unified-search-index.json`	`generate-unified-search.mjs` (build step 3)
`marketplace/src/data/cowork-manifest.json`	`build-cowork-zips.mjs` (build step 4)

Data Flow

marketplace.extended.json (source of truth, edit this)
        ↓ pnpm run sync-marketplace
marketplace.json (auto-generated, never edit)
        ↓ CI deploys to GitHub Pages
tonsofskills.com/catalog.json
        ↓
ccpi CLI fetches and caches locally

Marketplace Build Pipeline

npm run build in marketplace/ runs 5 steps sequentially via scripts/build.mjs:

discover-skills.mjs - Scans all plugins, extracts SKILL.md data into src/data/
sync-catalog.mjs - Copies catalog JSON into marketplace data
generate-unified-search.mjs - Builds Fuse.js search index
build-cowork-zips.mjs - Generates plugin zips, category bundles, mega-zip, and manifest for /cowork downloads
astro build - Static site generation

Gotcha: compressHTML is disabled in astro.config.mjs because iOS Safari fails to render lines > 5000 chars. CI enforces this with a smoke test.

Post-build validation scripts (also run in CI):

validate-routes.mjs - Plugin page routes exist
validate-playbook-routes.mjs - Production playbook routes
validate-internal-links.mjs - No broken internal links in dist (seeds: index, playbooks, explore, skills, cowork)
validate-links.mjs - Skill-to-plugin link integrity
validate-cowork-downloads.mjs - Cowork zip build output (manifest, checksums, download links)
validate-cowork-security.mjs - Zip content security scanner (no secrets, no node_modules)

Performance Budgets

Enforced by scripts/check-performance.mjs in CI:

Budget	Limit
Total bundle (gzipped)	18 MB
Largest file (gzipped)	550 KB
Build time	< 10s
Route count	1,600–2,000

Largest pages: explore/index.html (~520KB), skills/index.html (~300KB), compare/index.html (~250KB). The /downloads directory is excluded from the budget.

Marketplace Design System

Tokens (marketplace/src/styles/tokens.css): OKLCH color system with warm terracotta primary (oklch(62% 0.16 35)). Fluid typography via clamp() (--text-xs through --text-4xl). 4pt spacing grid (--space-1 through --space-12). Three card tiers (compact/standard/featured). Motion presets with prefers-reduced-motion support.

Theme system (BaseLayout.astro): Dark theme default, light via [data-theme="light"] on <html>. FOUC prevented by inline script before first paint. Legacy --brand-* / --gold / --navy aliases map to OKLCH tokens.

Font stack: Instrument Sans (display h1/h2), Source Sans 3 (body), DM Mono (labels/stats/code). All via Google Fonts.

Key tokens for UI work: --primary, --primary-border, --primary-tint, --surface through --surface-3, --text / --text-2 / --text-3, --border / --border-bright, --card.

Plugin Structure

AI Instruction Plugins

plugins/[category]/[plugin-name]/
├── .claude-plugin/plugin.json    # Required fields: name, version, description, author
├── README.md                     # Required
├── commands/*.md                 # Slash commands (YAML frontmatter)
├── agents/*.md                   # Custom agents (YAML frontmatter)
└── skills/[skill-name]/SKILL.md  # Auto-activating skills

MCP Server Plugins

plugins/mcp/[plugin-name]/
├── .claude-plugin/plugin.json
├── src/*.ts                      # TypeScript source
├── dist/index.js                 # Must be executable (shebang + chmod +x)
├── package.json
└── .mcp.json

plugin.json only allows these fields: name, version, description, author, repository, homepage, license, keywords. CI rejects any others.

SKILL.md Frontmatter (2026 Spec)

---
name: skill-name
description: |
  When to use this skill. Include trigger phrases.
allowed-tools: Read, Write, Edit, Bash(npm:*), Glob
version: 1.0.0
author: Name <email>
license: MIT
# Optional fields:
# model: sonnet                    # LLM model override
# context: fork                    # Run in subagent
# agent: Explore                   # Subagent type
# user-invocable: false            # Hide from / menu
# argument-hint: "<file-path>"     # Autocomplete hint
# hooks: { pre-tool-call: ... }    # Lifecycle hooks
# compatibility: "Node.js >= 18"   # Environment requirements (AgentSkills.io)
# compatible-with: claude-code, cursor  # Platform compatibility
# tags: [devops, ci]               # Discovery tags
---

Valid tools: Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch, Task, TodoWrite, NotebookEdit, AskUserQuestion, Skill

Path variable: Use ${CLAUDE_SKILL_DIR} for portable file references within skills.

Adding a New Plugin

Copy from templates/ (minimal, command, agent, or full)
Create .claude-plugin/plugin.json with required fields
Add entry to .claude-plugin/marketplace.extended.json
pnpm run sync-marketplace
./scripts/validate-all-plugins.sh plugins/[category]/[name]/

CI Pipeline (validate-plugins.yml)

PRs trigger parallel jobs:

Job	What it checks
`validate`	JSON validity, plugin structure, catalog sync, secret scanning, dangerous patterns
`test` (matrix)	MCP plugin builds + vitest, Python pytest, `ccpi validate --strict` + frontmatter
`check-package-manager`	Enforces pnpm/npm policy per directory
`marketplace-validation`	Astro build, route validation, link validation, smoke tests, cowork downloads/security, performance budget
`playwright-tests`	E2E tests on chromium + webkit + mobile (needs marketplace-validation)
`cli-smoke-tests`	CLI build, `--help`, `--version`, `npm pack`, no `workspace:` deps
`production-e2e`	Runs against live site — can be flaky due to GitHub avatar CDN rate limits

Test Organization

Dev tests (marketplace/tests/T*.spec.ts): T1–T9 covering homepage search, search results, mobile viewport, install CTA, playbooks nav, explore flows, cowork page/integration.

Production tests (marketplace/tests/production/P*.spec.ts): P1–P8 covering core page smoke tests, search flow, redirects, navigation, cowork downloads, mobile responsive, performance budgets, SEO meta.

Config (playwright.config.ts): Chromium + WebKit, mobile viewports (iPhone 13 + Pixel 5). CI: 2 retries, 1 worker. Local: no retries, parallel.

External Plugin Sync

sources.yaml defines external repos synced daily via scripts/sync-external.mjs (midnight UTC cron). Each source specifies include/exclude globs. Sync writes .source.json provenance files and creates PRs (labels: automated, sync, external-plugins). Supports --dry-run, --force, --source=NAME.

Conventions

Hooks: Use ${CLAUDE_PLUGIN_ROOT} for portability
Scripts: All .sh files must be chmod +x
Model IDs in skills: Use sonnet, haiku, or opus
README Contributors: Newest contributors go at the TOP of the list
CSS colors: Use OKLCH values, never hex/rgb. Use tokens from tokens.css when possible.

Key Identifiers

Brand: Tons of Skills by Intent Solutions
Domain: tonsofskills.com
Slug: claude-code-plugins-plus
Install: /plugin marketplace add jeremylongshore/claude-code-plugins

Task Tracking (Beads)

See AGENTS.md for full protocol. Quick reference:

bd sync && bd ready                        # Session start: find work
bd update <id> --status in_progress        # Claim task BEFORE starting
bd close <id> --reason "..."               # Complete with evidence
bd sync && git push                        # Session end: MANDATORY

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

CLAUDE.md

Repository Overview

Essential Commands

Two Catalog System (Critical)

Auto-Generated Data Files (Never Hand-Edit)

Data Flow

Marketplace Build Pipeline

Performance Budgets

Marketplace Design System

Plugin Structure

AI Instruction Plugins

MCP Server Plugins

SKILL.md Frontmatter (2026 Spec)

Adding a New Plugin

CI Pipeline (validate-plugins.yml)

Test Organization

External Plugin Sync

Conventions

Key Identifiers

Task Tracking (Beads)

Uh oh!

FilesExpand file tree

CLAUDE.md

Latest commit

History

CLAUDE.md

File metadata and controls

CLAUDE.md

Repository Overview

Essential Commands

Two Catalog System (Critical)

Auto-Generated Data Files (Never Hand-Edit)

Data Flow

Marketplace Build Pipeline

Performance Budgets

Marketplace Design System

Plugin Structure

AI Instruction Plugins

MCP Server Plugins

SKILL.md Frontmatter (2026 Spec)

Adding a New Plugin

CI Pipeline (validate-plugins.yml)

Test Organization

External Plugin Sync

Conventions

Key Identifiers

Task Tracking (Beads)