diff --git a/.github/workflows/registry.yml b/.github/workflows/registry.yml new file mode 100644 index 00000000..7ee7f277 --- /dev/null +++ b/.github/workflows/registry.yml @@ -0,0 +1,56 @@ +name: Registry + +on: + pull_request: + paths: + - 'registry/**' + - '.claude-plugin/marketplace.json' + +permissions: + contents: read + +jobs: + validate-submissions: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - uses: actions/setup-python@v5 + with: + python-version: '3.12' + + - name: Detect changed submission folders + id: changed + run: | + FOLDERS=$(git diff --name-only "${{ github.event.pull_request.base.sha }}" HEAD -- registry/skills/ \ + | grep '/' \ + | cut -d'/' -f1-3 \ + | sort -u \ + | tr '\n' ' ') + echo "folders=$FOLDERS" >> "$GITHUB_OUTPUT" + echo "Changed submission folders: $FOLDERS" + + - name: Validate changed submissions + if: steps.changed.outputs.folders != '' + run: | + RESULT=0 + for folder in ${{ steps.changed.outputs.folders }}; do + echo "::group::Validating $folder" + python registry/scripts/validate.py --clone "$folder" || RESULT=1 + echo "::endgroup::" + done + exit $RESULT + + check-index: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-python@v5 + with: + python-version: '3.12' + + - name: Verify index.json is in sync + run: python registry/scripts/build_index.py --check diff --git a/registry/CONTRIBUTING.md b/registry/CONTRIBUTING.md new file mode 100644 index 00000000..e4158fc5 --- /dev/null +++ b/registry/CONTRIBUTING.md @@ -0,0 +1,103 @@ +# Contributing to the Claude Skills Registry + +Share your skill with the community. This guide walks through submitting a skill +hosted in your own public GitHub repository. + +## Requirements + +Your skill must: + +1. Be hosted in a **public GitHub repository** +2. Have a `SKILL.md` at the repo root (or at the path you declare) +3. Be usable with at least one supported tool (Claude Code, Codex, Gemini CLI, …) + +## Submission steps + +### 1. Fork this repository + +### 2. Create your submission folder + +``` +registry/skills/__/ +``` + +The folder name uses a **double underscore** (`__`) to separate your GitHub +username from the skill name. Both halves must match `author` and `name` in your +`metadata.json`. + +### 3. Add the required files + +#### `metadata.json` + +```json +{ + "name": "my-skill", + "author": "your-github-username", + "description": "A short description of what your skill does", + "repository": "https://github.com/your-username/your-repo", + "path": "", + "version": "1.0.0", + "category": "productivity", + "tags": ["tag1", "tag2"], + "license": "MIT", + "adapters": ["claude-code"], + "icon": false, + "banner": false +} +``` + +| Field | Required | Description | +|-------|----------|-------------| +| `name` | Yes | Skill name (lowercase, hyphens) | +| `author` | Yes | Your GitHub username | +| `description` | Yes | What the skill does (10–300 chars) | +| `repository` | Yes | Public GitHub repo URL (`https://github.com/...`) | +| `path` | No | Subdirectory in the repo where `SKILL.md` lives (default: root) | +| `version` | Yes | Semver version | +| `category` | Yes | One of the allowed categories (below) | +| `tags` | Yes | 1–10 lowercase-hyphen tags | +| `license` | Yes | SPDX license identifier | +| `model` | No | Preferred model identifier | +| `adapters` | No | Supported tools (e.g. `claude-code`, `codex`, `gemini-cli`) | +| `icon` | No | `true` if `icon.png` (256×256) is included | +| `banner` | No | `true` if `banner.png` (1200×630) is included | + +**Categories:** `development`, `data-engineering`, `devops`, `security`, +`compliance`, `documentation`, `testing`, `research`, `productivity`, `finance`, +`leadership`, `product`, `marketing`, `project-management`, `business-growth`, +`commercial`, `operations`, `design`, `knowledge`, `customer-support`, +`creative`, `education`, `other`. + +#### `README.md` + +A markdown description of your skill — what it does, key capabilities, example +usage. Shown on the registry. + +#### `icon.png` / `banner.png` (optional) + +A 256×256 icon and/or 1200×630 banner. Set the matching boolean in +`metadata.json` to `true` when included. + +### 4. Validate locally (optional but recommended) + +```bash +python registry/scripts/validate.py --clone registry/skills/__/ +``` + +### 5. Open a pull request + +CI will automatically: + +- Validate `metadata.json` against the schema +- Check the folder name matches `__` +- Verify `README.md` exists and is non-empty +- Clone your repository and verify `SKILL.md` exists at the declared path +- Confirm the committed `index.json` is in sync + +## Updating your skill + +Open a new PR modifying your folder and bump `version` in `metadata.json`. + +## Questions? + +Open an issue or discussion in this repository. diff --git a/registry/README.md b/registry/README.md new file mode 100644 index 00000000..fc8e8411 --- /dev/null +++ b/registry/README.md @@ -0,0 +1,70 @@ +# Claude Skills Registry + +A browsable, searchable registry of skills — the skill packages that ship in +this repo **plus** community-submitted skills hosted in their own repos. + +Modeled on the [gitagent registry](https://registry.gitagent.sh) pattern: +GitHub is the source of truth, there is no database and no backend. + +``` +PR → CI validates → merge → index.json regenerated → static site reads index.json +``` + +## What's in here + +| Path | Purpose | +|------|---------| +| `schema/metadata.schema.json` | JSON Schema for a community submission's `metadata.json` | +| `scripts/validate.py` | Validate a submission folder (stdlib only) | +| `scripts/build_index.py` | Generate `index.json` from internal + community skills (stdlib only) | +| `skills/__/` | Community submission folders | +| `index.json` | Generated catalog the site reads | +| `site/` | Static browse/search UI (vanilla HTML/CSS/JS, no build step) | + +## Two sources, one index + +- **Internal** entries are derived automatically from + [`.claude-plugin/marketplace.json`](../.claude-plugin/marketplace.json) — every + plugin in this repo appears in the registry. +- **Community** entries are folders under `skills/`, each pointing at an external + public GitHub repo that contains a `SKILL.md`. + +## Develop + +No npm, no build system — Python standard library only. + +```bash +# Regenerate index.json (deterministic, no network) +python registry/scripts/build_index.py + +# Enrich entries with live GitHub stars/forks (network) +python registry/scripts/build_index.py --github + +# Fail if the committed index.json is stale (used in CI) +python registry/scripts/build_index.py --check + +# Validate every community submission +python registry/scripts/validate.py --all + +# Validate + clone each repo to confirm SKILL.md exists (network) +python registry/scripts/validate.py --clone registry/skills/__/ +``` + +## Run the site locally + +```bash +cd registry +python -m http.server 8000 +# open http://localhost:8000/site/ +``` + +The site fetches `index.json`; serve from the `registry/` directory so the +relative path resolves. + +## Submit a skill + +See [CONTRIBUTING.md](./CONTRIBUTING.md). + +## License + +MIT diff --git a/registry/index.json b/registry/index.json new file mode 100644 index 00000000..b838c126 --- /dev/null +++ b/registry/index.json @@ -0,0 +1,1704 @@ +{ + "skills": [ + { + "name": "example-skill", + "author": "alirezarezvani", + "description": "Example community submission. Copy this folder, point it at your own public repo that contains a SKILL.md, and open a PR. See registry/CONTRIBUTING.md.", + "category": "productivity", + "tags": [ + "example", + "template", + "getting-started" + ], + "version": "1.0.0", + "license": "MIT", + "origin": "community", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "engineering/caveman/skills/caveman", + "readme": "https://raw.githubusercontent.com/alirezarezvani/claude-skills/main/registry/skills/alirezarezvani__example-skill/README.md", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-05-27", + "adapters": [ + "claude-code", + "codex", + "gemini-cli" + ] + }, + { + "name": "a11y-audit", + "author": "Alireza Rezvani", + "description": "WCAG 2.2 accessibility audit and fix for React, Next.js, Vue, Angular, Svelte, and HTML. Static scanner detecting 20+ violation types, contrast checker with suggest mode, framework-specific fix patterns, /a11y-audit slash command.", + "category": "development", + "tags": [ + "accessibility", + "a11y", + "wcag", + "aria", + "screen-reader", + "contrast", + "keyboard-navigation" + ], + "version": "2.2.2", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "engineering-team/a11y-audit", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/a11y-audit", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-03-26" + }, + { + "name": "aeo", + "author": "Alireza Rezvani", + "description": "Answer Engine Optimization (AEO) skill — optimize content to be cited by AI language models (ChatGPT, Perplexity, Claude, Gemini, Mistral) as authoritative sources. Distinct from SEO (which optimizes for search rankings), AEO optimizes for citation in LLM-generated responses. 3 stdlib Python tools (aeo_audit, aeo_optimizer, citation_tracker), 3 references citing 8 sources each, industry-aware thresholds for 8 industries (saas/healthcare/finance/legal/ecommerce/b2b/media/education). Ported from alirezarezvani/aeo-box.", + "category": "marketing", + "tags": [ + "aeo", + "answer-engine-optimization", + "llm-citation", + "eeat", + "chatgpt", + "perplexity", + "claude", + "gemini", + "marketing", + "seo-complement" + ], + "version": "2.7.3", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "marketing-skill/skills/aeo", + "readme": "https://raw.githubusercontent.com/alirezarezvani/claude-skills/main/marketing-skill/skills/aeo/SKILL.md", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-05-17" + }, + { + "name": "agenthub", + "author": "Alireza Rezvani", + "description": "Multi-agent collaboration — spawn N parallel subagents that compete on code optimization, content drafts, research approaches, or any task that benefits from diverse solutions. 7 slash commands (/hub:init, /hub:spawn, /hub:status, /hub:eval, /hub:merge, /hub:board, /hub:run), agent templates, DAG-based orchestration, LLM judge mode, message board coordination.", + "category": "development", + "tags": [ + "multi-agent", + "collaboration", + "parallel", + "git-dag", + "orchestration", + "competition", + "worktree", + "content-generation", + "research", + "optimization" + ], + "version": "2.2.2", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "engineering/agenthub", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/engineering/agenthub", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-03-26" + }, + { + "name": "agile-product-owner", + "author": "Alireza Rezvani", + "description": "Agile product ownership for backlog management and sprint execution. INVEST-compliant user story generation, acceptance criteria patterns (Given/When/Then, rule-based, checklist), epic breakdown with 5 split techniques, sprint planning with velocity-based capacity math, and weighted backlog prioritization. Includes user_story_generator Python tool and 2 reference guides.", + "category": "product", + "tags": [ + "agile", + "scrum", + "product-owner", + "user-stories", + "sprint-planning", + "backlog", + "acceptance-criteria", + "epic-breakdown" + ], + "version": "2.3.2", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "product-team/agile-product-owner", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/product-team/agile-product-owner", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-03-30" + }, + { + "name": "andreessen", + "author": "Alireza Rezvani", + "description": "Marc Andreessen-mode decision and productivity skill. Market-first operator that pressure-tests ventures/ideas/features/bets (market > team > product; product/market fit is the only milestone; bias to build) and runs the 3x5-card + Anti-Todo routine. Fixed anti-sycophancy operating prompt: counterargument first, no disclaimers, explicit confidence levels, no capitulation. Issues hard verdicts backed by deterministic stdlib tools.", + "category": "productivity", + "tags": [ + "andreessen", + "pmarca", + "productivity", + "product-market-fit", + "market-first", + "anti-sycophancy", + "decision-making", + "anti-todo" + ], + "version": "2.8.4", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "productivity/andreessen", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/productivity/andreessen", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-05-24" + }, + { + "name": "apple-hig-expert", + "author": "Alireza Rezvani", + "description": "Master Apple's Human Interface Guidelines (HIG) with focus on 2026 Liquid Glass aesthetics. Design and audit iOS, macOS, and visionOS apps for full compliance and premium feel. Includes hig_checker Python tool for tap targets and contrast.", + "category": "design", + "tags": [ + "apple-hig", + "design-guidelines", + "ios-design", + "macos-design", + "visionos", + "liquid-glass", + "accessibility", + "ui-design" + ], + "version": "2.3.2", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "product-team/apple-hig-expert", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/product-team/apple-hig-expert", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-04-09" + }, + { + "name": "autoresearch-agent", + "author": "Alireza Rezvani", + "description": "Autonomous experiment loop — optimize any file by a measurable metric. 5 slash commands (/ar:setup, /ar:run, /ar:loop, /ar:status, /ar:resume), 8 built-in evaluators, configurable loop intervals (10min to monthly).", + "category": "development", + "tags": [ + "autoresearch", + "optimization", + "experiments", + "benchmarks", + "loop", + "metrics", + "evaluators" + ], + "version": "2.2.2", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "engineering/autoresearch-agent", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/engineering/autoresearch-agent", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-03-26" + }, + { + "name": "business-growth-skills", + "author": "Alireza Rezvani", + "description": "5 business & growth skills: customer success manager, sales engineer, revenue operations, contract & proposal writer.", + "category": "business-growth", + "tags": [ + "customer-success", + "sales-engineering", + "revenue-operations", + "business-growth", + "proposals" + ], + "version": "2.2.3", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "business-growth", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/business-growth", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-03-26" + }, + { + "name": "business-operations-skills", + "author": "Alireza Rezvani", + "description": "Internal BizOps domain. v2.8.0 ships 7 skills: orchestrator + process-mapper (BPMN/bottleneck/cycle-time, Lean+TOC) + vendor-management (scorecard+SLA+3rd-party risk, NIST SP 800-161/ISO 27036) + capacity-planner (Erlang-C queueing math for ops teams, NOT engineering) + internal-comms (ADKAR+Kotter 8-step, NOT marketing) + knowledge-ops (SOP+runbook+KB hygiene with 5W2H, context: fork) + procurement-optimizer (UNSPSC spend categorization + supplier consolidation). Orchestrator uses context: fork to route inquiries via Matt Pocock grill discipline (one question per turn, recommended answer, canon-cited challenge). Every SKILL.md ships a Forcing-question library section. 18 stdlib Python tools, 24+ reference docs. Distinct from business-growth (external sales) and c-level-advisor (strategic).", + "category": "operations", + "tags": [ + "bizops", + "operations", + "process-mapping", + "bottleneck", + "vendor-management", + "sla", + "third-party-risk", + "lean", + "theory-of-constraints", + "value-stream", + "capacity-planning", + "erlang-c", + "queueing-theory", + "internal-comms", + "change-management", + "adkar", + "kotter", + "knowledge-ops", + "sop", + "runbook", + "5w2h", + "procurement", + "spend-categorization", + "unspsc", + "supplier-consolidation", + "matt-pocock", + "grill-with-docs" + ], + "version": "2.8.0", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "business-operations", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/business-operations", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-05-19" + }, + { + "name": "c-level-agents", + "author": "Alireza Rezvani", + "description": "Founder-mode executive team plugin: 13 cs-* C-suite agents (CFO, CMO, CRO, CPO, COO, CHRO, CISO, Chief of Staff, General Counsel, Chief Data Officer, Chief AI Officer, Chief Customer Officer, VP of Engineering) with distinct cognitive voices, plus 21 /cs:* slash commands — forcing-question office hours (CFO/CMO/CPO/CRO/CTO/CISO/GC/CDO/CAIO/CCO/VPE reviews), strategic sprint pipeline (brief → boardroom → decide → execute → post-mortem), and meta routing (/cs:founder-mode auto-router, /cs:onboard, /cs:cross-eval multi-model consensus, /cs:freeze cooldown lock). Wraps the 33 c-level skills with cognitive gearing, persona voice, and artifact-driven handoffs. The business-domain answer to YC Garry Tan's gstack.", + "category": "leadership", + "tags": [ + "founder-mode", + "boardroom", + "office-hours", + "executive-agents", + "c-suite", + "cfo", + "cmo", + "cro", + "cpo", + "ciso", + "general-counsel", + "contract-review", + "term-sheet", + "ip-strategy", + "chief-data-officer", + "cdo", + "ai-training-data", + "data-product-strategy", + "data-as-asset", + "chief-ai-officer", + "caio", + "ai-strategy", + "model-buildvsbuy", + "eu-ai-act", + "ai-cost-economics", + "chief-customer-officer", + "cco", + "retention-decomposition", + "customer-segmentation", + "cs-coverage", + "vp-engineering", + "vpe", + "dora", + "delivery-throughput", + "engineering-hiring", + "eng-team-structure", + "decision-logging", + "cross-model" + ], + "version": "1.5.0", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "c-level-advisor/c-level-agents", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/c-level-agents", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-05-12" + }, + { + "name": "c-level-skills", + "author": "Alireza Rezvani", + "description": "33 C-level advisory skills + c-level-agents plugin layer: virtual board of directors (CEO, CTO, COO, CPO, CMO, CFO, CRO, CISO, CHRO) plus General Counsel, CDO, CAIO, CCO, and VP of Engineering (DORA delivery throughput analyzer, engineering hiring funnel calculator with conversion + pipeline gap, eng team structure designer with squad/tribe + manager-trigger), executive mentor, founder coach, orchestration (Chief of Staff, board meetings, decision logger), strategic capabilities (board deck builder, scenario war room, competitive intel, M&A playbook), culture frameworks, and 13 cs-* persona agents + 21 /cs:* slash commands (founder-mode router, office-hours intake, multi-role boardroom, strategic sprint pipeline, cross-model consensus, cooldown freeze).", + "category": "leadership", + "tags": [ + "ceo", + "cto", + "cfo", + "executive", + "strategy", + "leadership", + "board", + "advisory", + "founder-mode", + "boardroom" + ], + "version": "2.5.5", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "c-level-advisor", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-03-26" + }, + { + "name": "capture-skill", + "author": "Alireza Rezvani", + "description": "Brain-dump-to-action workspace skill. Routes vague captures into discoverable actions via classify→cluster→connect→clarify intake. Path-B from megaprompt 05.", + "category": "productivity", + "tags": [ + "capture", + "brain-dump", + "productivity", + "gtd", + "workspace", + "path-b-megaprompt" + ], + "version": "2.7.0", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "productivity/capture", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/productivity/capture", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-05-16" + }, + { + "name": "caveman", + "author": "Alireza Rezvani", + "description": "Ultra-compressed communication mode. Cuts token usage 20-50% (75% upper bound) by dropping filler, articles, pleasantries, and hedging while keeping full technical accuracy. Derived from Matt Pocock's MIT-licensed caveman with: (1) 3 stdlib Python tools (deterministic compressor, token-savings estimator with $/Mtok cost extrapolation, lint that detects banned vocab with code-block + exception-zone whitelisting), (2) 3 references citing 7-8 sources (compression principles, when caveman backfires, companion tooling), (3) cs-caveman-mode persona agent + /cs:caveman slash command. Matt's persistence rules + auto-clarity exception preserved verbatim per MIT.", + "category": "development", + "tags": [ + "token-compression", + "matt-pocock", + "terse-mode", + "caveman", + "cost-reduction", + "communication" + ], + "version": "2.6.0", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "engineering/caveman", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/engineering/caveman", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-05-13" + }, + { + "name": "chaos-engineering", + "author": "Alireza Rezvani", + "description": "End-to-end chaos engineering discipline: design experiments with hypothesis + steady-state metric + blast radius + abort criteria, calculate risk score against error budget, and generate blameless postmortems. 3 stdlib Python tools (experiment_designer, blast_radius_calculator, experiment_postmortem), 4 references on chaos principles + experiment design + 7-attack taxonomy + tooling landscape (Chaos Toolkit/Mesh/Litmus/Gremlin/AWS FIS/DIY), templates, and /chaos-experiment slash command. Composes with feature-flags-architect (kill switches as abort triggers) and kubernetes-operator (chaos targets).", + "category": "development", + "tags": [ + "chaos-engineering", + "resilience", + "fault-injection", + "gameday", + "sre", + "reliability", + "chaos-mesh", + "litmus", + "gremlin", + "aws-fis" + ], + "version": "2.4.0", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "engineering/chaos-engineering", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/engineering/chaos-engineering", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-05-09" + }, + { + "name": "chief-ai-officer-advisor", + "author": "Alireza Rezvani", + "description": "Chief AI Officer advisory for startups: model build-vs-buy calculator (API vs fine-tune vs build with 3-year TCO across 6 paths + breakeven that balances economics with practical feasibility), AI risk classifier (EU AI Act tier with 7 Article citations + US state patchwork: NYC LL 144, CO AI Act, IL HB 53, CA SB 1001, IL BIPA + industry overlays for FDA AI/ML, CFPB Circular 2023-03, NYDFS Reg 23, NAIC, ECOA, Fed SR 11-7), AI cost economics (API vs self-hosted breakeven with 2026 pricing across A100/H100, utilization reality, hidden costs). 4 in-depth references each citing 5+ authoritative sources. Standalone-installable; also bundled in c-level-skills. Strategic only — does not duplicate engineering AI/ML skills.", + "category": "leadership", + "tags": [ + "chief-ai-officer", + "caio", + "ai-strategy", + "model-buildvsbuy", + "fine-tuning", + "eu-ai-act", + "ai-risk-tier", + "nist-ai-rmf", + "ai-cost-economics", + "ai-self-hosted-breakeven", + "ai-team-org" + ], + "version": "1.0.0", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "c-level-advisor/chief-ai-officer-advisor", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/chief-ai-officer-advisor", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-05-13" + }, + { + "name": "chief-customer-officer-advisor", + "author": "Alireza Rezvani", + "description": "Chief Customer Officer advisory: retention decomposition analyzer (honest GRR vs NRR; 7-category churn taxonomy with preventable% scoring), customer segmentation designer (4-tier framework, ICP fit scoring across 7 weighted signals, kill list + upgrade candidates), CS coverage calculator (pooled vs named CSM ratio math + 12-month hiring plan with quarterly sequencing). 4 in-depth references each citing 5+ authoritative sources. Standalone-installable; also bundled in c-level-skills. Strategic only — does not duplicate business-growth tactical CS skills.", + "category": "leadership", + "tags": [ + "chief-customer-officer", + "cco", + "customer-success", + "retention", + "gross-retention", + "net-retention", + "churn-analysis", + "customer-segmentation", + "cs-coverage", + "cs-team-org" + ], + "version": "1.0.0", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "c-level-advisor/chief-customer-officer-advisor", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/chief-customer-officer-advisor", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-05-13" + }, + { + "name": "chief-data-officer-advisor", + "author": "Alireza Rezvani", + "description": "Chief Data Officer advisory for startups: AI training data audit (origin × class × use-case matrix with GDPR Art. 6 + EU AI Act citations), data product strategy picker (warehouse vs lakehouse vs mesh + 6-layer build-vs-buy + 12-month sequencing), data asset valuator (strategic value 0-10 + M&A multiplier with carve-out penalties + 3 ranked productization paths). 4 references answering one decision each: training rights, data product strategy, customer-data-as-asset, data team org evolution. Standalone-installable; also bundled in c-level-skills. Strategic only — does not duplicate engineering data skills.", + "category": "leadership", + "tags": [ + "chief-data-officer", + "cdo", + "data-strategy", + "ai-training-data", + "consent-provenance", + "data-product-strategy", + "data-mesh", + "lakehouse", + "data-as-asset", + "data-team-org" + ], + "version": "1.0.0", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "c-level-advisor/chief-data-officer-advisor", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/chief-data-officer-advisor", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-05-13" + }, + { + "name": "code-to-prd", + "author": "Alireza Rezvani", + "description": "Reverse-engineer any codebase into a complete PRD. Frontend (React, Vue, Angular, Next.js), backend (NestJS, Django, Express, FastAPI), and fullstack. 2 Python scripts (codebase_analyzer, prd_scaffolder), 2 reference guides, /code-to-prd slash command.", + "category": "product", + "tags": [ + "prd", + "product-requirements", + "reverse-engineering", + "frontend", + "backend", + "fullstack", + "documentation", + "code-analysis", + "react", + "vue", + "angular", + "nestjs", + "django", + "fastapi", + "express" + ], + "version": "2.2.2", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "product-team/code-to-prd", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/product-team/code-to-prd", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-03-26" + }, + { + "name": "code-tour", + "author": "Alireza Rezvani", + "description": "Create CodeTour .tour files — persona-targeted, step-by-step walkthroughs that link to real files and line numbers. 10 developer personas, all CodeTour step types, SMIG description formula.", + "category": "development", + "tags": [ + "codetour", + "walkthrough", + "onboarding", + "code-review", + "documentation" + ], + "version": "2.2.2", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "engineering/code-tour", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/engineering/code-tour", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-04-03" + }, + { + "name": "commercial-skills", + "author": "Alireza Rezvani", + "description": "Per-deal-and-packaging Commercial domain. v2.8.0 ships 8 skills: orchestrator + pricing-strategist (model picker + Van Westendorp WTP + packaging) + deal-desk (deal scorer + discount approval routing + redline) + partnerships-architect (5-tier classifier + joint GTM + revshare modeler) + channel-economics (cost-to-serve + ROI + mix optimizer) + commercial-policy (data-backed discount matrix + exception flow + linter) + rfp-responder (Shipley structured RFP/RFI/RFQ + win-theme + winrate predictor, context: fork) + commercial-forecaster (4Q-weighted bookings + cohort NRR/GRR + funnel-confidence with mandatory assumption disclosure). Hard rules: pricing outputs model+range (never a single number), deal outputs route to named human approver (never auto-approve), forecast outputs surface conversion assumption, RFP never invents claims for GAP requirements. 21 stdlib Python tools, 28+ reference docs. Distinct from business-growth (sales execution), c-level-advisor/cro-advisor (strategic), finance (close+report).", + "category": "commercial", + "tags": [ + "commercial", + "pricing", + "deal-desk", + "discount-approval", + "van-westendorp", + "wtp", + "packaging", + "saas-pricing", + "redline", + "margin", + "partnerships", + "channel-partners", + "joint-gtm", + "revshare", + "channel-economics", + "cost-to-serve", + "channel-roi", + "commercial-policy", + "discount-matrix", + "exception-flow", + "rfp", + "rfi", + "shipley-method", + "winrate-predictor", + "bookings-forecast", + "cohort-arr", + "funnel-confidence", + "matt-pocock", + "grill-with-docs" + ], + "version": "2.8.0", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "commercial", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/commercial", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-05-19" + }, + { + "name": "data-quality-auditor", + "author": "Alireza Rezvani", + "description": "Audit datasets for completeness, consistency, accuracy, and validity. 3 stdlib-only Python tools: data profiler with DQS scoring, missing value analyzer with MCAR/MAR/MNAR classification, and multi-method outlier detector.", + "category": "development", + "tags": [ + "data-quality", + "profiling", + "outlier-detection", + "missing-values", + "data-audit" + ], + "version": "2.2.2", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "engineering/data-quality-auditor", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/engineering/data-quality-auditor", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-04-04" + }, + { + "name": "demo-video", + "author": "Alireza Rezvani", + "description": "Create polished demo videos from screenshots and scene descriptions. Orchestrates playwright, ffmpeg, and edge-tts with story structure, scene design system, and narration guidance.", + "category": "development", + "tags": [ + "video", + "demo", + "product-demo", + "walkthrough", + "ffmpeg", + "tts" + ], + "version": "2.2.2", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "engineering/demo-video", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/engineering/demo-video", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-04-03" + }, + { + "name": "docker-development", + "author": "Alireza Rezvani", + "description": "Docker and container development — Dockerfile optimization, docker-compose orchestration, multi-stage builds, security hardening, and CI/CD container pipelines.", + "category": "development", + "tags": [ + "docker", + "container", + "dockerfile", + "docker-compose", + "devops" + ], + "version": "2.2.2", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "engineering/docker-development", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/engineering/docker-development", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-03-26" + }, + { + "name": "dossier", + "author": "Alireza Rezvani", + "description": "Decision-grade entity research. Due-diligence/background-check/competitor-prep with tier-weighted verdict + citation tracker. Research-pack convention. Path-B from megaprompt 02.", + "category": "research", + "tags": [ + "research", + "dossier", + "due-diligence", + "background-check", + "competitor", + "entity-research", + "research-pack", + "path-b-megaprompt" + ], + "version": "2.7.0", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "research/dossier", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/research/dossier", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-05-15" + }, + { + "name": "email-pair", + "author": "Alireza Rezvani", + "description": "Email-workflow skill pair: inbox-setup builds your taxonomy/KB; inbox-triage classifies + drafts (drafts-only, never auto-send). KB-file contract between them. Path-B from megaprompts 06+07.", + "category": "productivity", + "tags": [ + "email", + "inbox", + "triage", + "gmail", + "outlook", + "productivity", + "path-b-megaprompt" + ], + "version": "2.7.0", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "productivity/email", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/productivity/email", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-05-15" + }, + { + "name": "engineering-advanced-skills", + "author": "Alireza Rezvani", + "description": "40 advanced engineering skills: agent designer, agent workflow designer, AgentHub, RAG architect, database designer, focused-fix, browser-automation, spec-driven-workflow, secrets-vault-manager, sql-database-assistant, migration architect, observability designer, dependency auditor, release manager, API reviewer, CI/CD pipeline builder, MCP server builder, skill security auditor, performance profiler, Helm chart builder, Terraform patterns, self-eval, llm-cost-optimizer, prompt-governance, behuman, code-tour, demo-video, data-quality-auditor, statistical-analyst, llm-wiki (second brain for Obsidian + Claude Code, Karpathy pattern), feature-flags-architect (flag debt scanner, rollout planner, kill-switch audit), kubernetes-operator (CRD validator, reconcile linter, capability auditor), chaos-engineering (experiment designer, blast-radius calculator, postmortem generator), ship-gate (pre-production 8-category audit with deploy-intent intercept), slo-architect (SLO designer, error-budget calculator with multi-window burn-rate alerts, SLO reviewer per Google SRE Workbook), and more.", + "category": "development", + "tags": [ + "agent-design", + "rag", + "database", + "migration", + "observability", + "dependency-audit", + "release", + "api-review", + "ci-cd", + "mcp", + "security-audit" + ], + "version": "2.4.3", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "engineering", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/engineering", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-03-26" + }, + { + "name": "engineering-skills", + "author": "Alireza Rezvani", + "description": "32 engineering skills: architecture, frontend, backend, fullstack, QA, DevOps, security, AI/ML, data engineering, Playwright (9 sub-skills), self-improving agent, Stripe integration, TDD guide, tech stack evaluator, Google Workspace CLI, a11y audit (WCAG 2.2), Azure cloud architect, GCP cloud architect, security pen testing, Snowflake development, adversarial-reviewer, ai-security, cloud-security, incident-response, red-team, threat-detection. v2.8.1 audits senior-fullstack / senior-frontend / senior-backend against karpathy-coder + Matt Pocock — each ships a 7-question forcing-question library, 4 customization profiles (JSON), deterministic decision engine, composition map into POWERFUL specialists, plus cs-fullstack-engineer / cs-frontend-engineer / cs-backend-engineer orchestrator agents (context: fork) + /cs:fullstack-review, /cs:frontend-review, /cs:backend-review, /cs:engineer-grill slash commands.", + "category": "development", + "tags": [ + "engineering", + "architecture", + "frontend", + "backend", + "devops", + "security", + "ai", + "ml", + "data", + "playwright", + "google-workspace", + "gws", + "gmail", + "google-drive", + "google-sheets" + ], + "version": "2.8.1", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "engineering-team", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-03-30" + }, + { + "name": "executive-mentor", + "author": "Alireza Rezvani", + "description": "Adversarial thinking partner for founders and executives. Stress-tests plans, prepares for board meetings, navigates hard calls, runs postmortems. 5 sub-skills with slash commands.", + "category": "leadership", + "tags": [ + "executive", + "mentor", + "stress-test", + "board-prep", + "founder", + "leadership" + ], + "version": "2.2.2", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "c-level-advisor/executive-mentor", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/executive-mentor", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-03-26" + }, + { + "name": "feature-flags-architect", + "author": "Alireza Rezvani", + "description": "End-to-end feature-flag discipline: classify, ship, ramp, retire. Detects stale flags as debt, generates phased rollout plans (ring/linear/log/cohort), and audits every flag for a documented kill switch. 3 stdlib Python tools, 4 references on flag taxonomy + provider trade-offs (LaunchDarkly/GrowthBook/Statsig/Unleash/Flipt/DIY) + rollout strategies + lifecycle. /flag-cleanup slash command. Cross-tool compatible.", + "category": "development", + "tags": [ + "feature-flags", + "progressive-delivery", + "rollout", + "kill-switch", + "launchdarkly", + "growthbook", + "statsig", + "unleash", + "flipt", + "release-engineering" + ], + "version": "2.4.0", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "engineering/feature-flags-architect", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/engineering/feature-flags-architect", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-05-09" + }, + { + "name": "finance-skills", + "author": "Alireza Rezvani", + "description": "3 finance skills: financial analyst (ratio analysis, DCF valuation, budgeting, forecasting), SaaS metrics coach (ARR, MRR, churn, CAC, LTV, NRR, Quick Ratio, projections), and business investment advisor. 7 Python automation tools.", + "category": "finance", + "tags": [ + "finance", + "dcf", + "valuation", + "budgeting", + "forecasting", + "saas", + "metrics", + "arr", + "mrr", + "churn", + "ltv", + "cac" + ], + "version": "2.2.3", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "finance", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/finance", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-03-30" + }, + { + "name": "general-counsel-advisor", + "author": "Alireza Rezvani", + "description": "General Counsel advisory for startups: contract risk scanner (12 founder-killer patterns: auto-renew traps, uncapped indemnity, vague IP, MFN pricing, missing DPA, one-sided venue, broad non-solicit, perpetual license-back, etc.) and term sheet analyzer (0-100 founder-friendliness across 12 dimensions). 3 in-depth references: contracts playbook (7 startup contract types), IP + regulatory landscape mapping (HIPAA, GDPR, FDA, fintech, EU AI Act, SOC 2 → ISO sequencing), term sheet decoder (full glossary + founder-friendly defaults). Standalone-installable; also bundled in c-level-skills. Stdlib-only. NOT a substitute for licensed counsel.", + "category": "leadership", + "tags": [ + "general-counsel", + "gc", + "legal-review", + "contract-review", + "term-sheet", + "ip-strategy", + "regulatory", + "dpa", + "indemnity", + "liability-cap" + ], + "version": "1.0.0", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "c-level-advisor/general-counsel-advisor", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/general-counsel-advisor", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-05-13" + }, + { + "name": "google-workspace-cli", + "author": "Alireza Rezvani", + "description": "Google Workspace administration via the gws CLI. Install, authenticate, and automate Gmail, Drive, Sheets, Calendar, Docs, Chat, and Tasks. 5 Python tools, 3 reference guides, 43 built-in recipes, 10 persona bundles.", + "category": "development", + "tags": [ + "google-workspace", + "gws", + "gmail", + "google-drive", + "google-sheets", + "google-calendar", + "workspace-admin" + ], + "version": "2.2.2", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "engineering-team/google-workspace-cli", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/google-workspace-cli", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-03-26" + }, + { + "name": "grants", + "author": "Alireza Rezvani", + "description": "NIH grant-funding intelligence skill. RePORTER/NOSI/study-section navigation, R01/R21/K-award strategy. Research-pack convention. Path-B from megaprompt 11.", + "category": "research", + "tags": [ + "research", + "grants", + "nih", + "r01", + "k-award", + "reporter", + "nosi", + "research-pack", + "path-b-megaprompt" + ], + "version": "2.7.0", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "research/grants", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/research/grants", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-05-15" + }, + { + "name": "grill-me", + "author": "Alireza Rezvani", + "description": "Relentless plan-and-design interrogator. Walks the decision tree one branch at a time, asking forcing questions sequentially with recommended answers. Explores codebase before asking. Derived from Matt Pocock's MIT-licensed grill-me with: (1) 3 stdlib Python tools (decision-tree extractor across 6 branch kinds, question generator with dependency-aware ordering, JSON-backed session tracker for multi-day grills), (2) 3 references citing 7-8 sources (6 forcing-question patterns, when to stop grilling, companion tooling), (3) cs-grill-master persona agent + /cs:grill-me slash command. Matt's relentless one-at-a-time interview discipline preserved verbatim per MIT.", + "category": "development", + "tags": [ + "plan-interrogation", + "matt-pocock", + "forcing-questions", + "decision-tree", + "design-review", + "stress-test", + "socratic-method" + ], + "version": "2.6.0", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "engineering/grill-me", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/engineering/grill-me", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-05-13" + }, + { + "name": "handoff-engineering", + "author": "Alireza Rezvani", + "description": "Conversation-handoff document generator. Compacts the current session into a markdown handoff for a fresh agent — references existing artifacts (PRDs, plans, ADRs, issues, commits) by path/URL instead of duplicating them. Derived from Matt Pocock's MIT-licensed handoff with: (1) 3 stdlib Python tools (template generator tailored to 5 next-session emphases, artifact deduplicator across 5 categories of duplication, skill recommender matching content to 14 skills in this repo), (2) 4 references citing 7-8 sources (handoff structure, deduplication discipline, next-session skill matching, companion tooling), (3) cs-handoff-author persona agent + /cs:handoff slash command. Matt's no-duplication discipline + mktemp convention preserved verbatim per MIT.", + "category": "development", + "tags": [ + "session-handoff", + "matt-pocock", + "continuity", + "context-transfer", + "documentation", + "no-duplication" + ], + "version": "2.6.0", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "engineering/handoff", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/engineering/handoff", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-05-13" + }, + { + "name": "handoff-productivity", + "author": "Alireza Rezvani", + "description": "Compact the current conversation into a handoff document for another agent to pick up. Configurable save location, redaction enforcement, SessionStart auto-load + SessionEnd reminder, self-check fidelity script, --refresh flag, mtime-guarded cleanup. Inspired by Matt Pocock's handoff (MIT).", + "category": "productivity", + "tags": [ + "handoff", + "productivity", + "session-continuity", + "redaction", + "session-start-hook", + "session-end-hook", + "self-check", + "matt-pocock" + ], + "version": "2.8.2", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "productivity/handoff", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/productivity/handoff", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-05-21" + }, + { + "name": "helm-chart-builder", + "author": "Alireza Rezvani", + "description": "Helm chart development — chart scaffolding, values design, template patterns, dependency management, and Kubernetes deployment strategies.", + "category": "development", + "tags": [ + "helm", + "kubernetes", + "k8s", + "chart", + "deployment" + ], + "version": "2.2.2", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "engineering/helm-chart-builder", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/engineering/helm-chart-builder", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-03-26" + }, + { + "name": "karpathy-coder", + "author": "Alireza Rezvani", + "description": "Active coding discipline enforcer based on Karpathy's 4 principles: surface assumptions, simplify, make surgical changes, define verifiable goals. Ships 4 Python tools (complexity_checker, diff_surgeon, assumption_linter, goal_verifier), a review agent, /karpathy-check command, and pre-commit hook. All stdlib-only.", + "category": "development", + "tags": [ + "code-quality", + "karpathy", + "simplicity", + "surgical-changes", + "complexity", + "anti-patterns", + "review", + "discipline" + ], + "version": "2.3.2", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "engineering/karpathy-coder", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/engineering/karpathy-coder", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-04-12" + }, + { + "name": "kubernetes-operator", + "author": "Alireza Rezvani", + "description": "End-to-end Kubernetes Operator discipline: CRD design, reconcile-loop patterns, and OperatorHub Capability Levels. Ships CRD validator, reconcile-loop linter, and capability auditor (3 stdlib Python tools), 4 references on the operator pattern + CRD design + reconcile patterns + framework comparison (controller-runtime/kubebuilder/operator-sdk/metacontroller/KOPF), CRD + Go controller skeletons, and /operator-audit slash command. NOT a generic k8s skill — specifically the Operator pattern.", + "category": "development", + "tags": [ + "kubernetes", + "operator", + "crd", + "controller-runtime", + "kubebuilder", + "operator-sdk", + "metacontroller", + "kopf", + "reconcile", + "devops" + ], + "version": "2.4.0", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "engineering/kubernetes-operator", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/engineering/kubernetes-operator", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-05-09" + }, + { + "name": "landing", + "author": "Alireza Rezvani", + "description": "Single-file HTML landing-page generator with 4 design styles, brand palette validation, GSAP animation patterns, kebab-slug URL hygiene. Path-B from megaprompt 04.", + "category": "marketing", + "tags": [ + "landing-page", + "html", + "marketing", + "generator", + "gsap", + "brand", + "path-b-megaprompt" + ], + "version": "2.7.0", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "marketing/landing", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/marketing/landing", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-05-15" + }, + { + "name": "litreview", + "author": "Alireza Rezvani", + "description": "Academic literature orientation skill. PICO/SPIDER frameworks, systematic review structure, 8-section DOCX guide. Research-pack convention. Path-B from megaprompt 09.", + "category": "research", + "tags": [ + "research", + "literature-review", + "pico", + "spider", + "systematic-review", + "academic", + "research-pack", + "path-b-megaprompt" + ], + "version": "2.7.0", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "research/litreview", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/research/litreview", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-05-15" + }, + { + "name": "llm-wiki", + "author": "Alireza Rezvani", + "description": "A second brain for Claude Code + Obsidian inspired by Karpathy's LLM Wiki gist. Turn any LLM CLI into a disciplined wiki maintainer: incrementally ingest sources into a persistent, interlinked markdown vault; update entity/concept/source pages; flag contradictions; maintain index and append-only log. Knowledge compounds instead of being re-derived by RAG on every query. Ships 3 sub-agents (wiki-ingestor, wiki-librarian, wiki-linter), 5 slash commands (/wiki-init, /wiki-ingest, /wiki-query, /wiki-lint, /wiki-log), 8 Python tools (stdlib only: init_vault, ingest_source, update_index, append_log, wiki_search BM25, lint_wiki, graph_analyzer, export_marp), 8 reference docs, full vault templates (CLAUDE.md, AGENTS.md, cursorrules, 5 page templates), and a worked example vault. Cross-tool compatible with Claude Code, Codex CLI, Cursor, Antigravity, OpenCode, and Gemini CLI.", + "category": "knowledge", + "tags": [ + "knowledge-management", + "obsidian", + "second-brain", + "pkm", + "wiki", + "rag-alternative", + "karpathy", + "memex", + "incremental-knowledge", + "cross-tool" + ], + "version": "2.3.2", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "engineering/llm-wiki", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/engineering/llm-wiki", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-04-11" + }, + { + "name": "marketing-skills", + "author": "Alireza Rezvani", + "description": "44 marketing skills across 7 pods: Content, SEO, CRO, Channels, Growth, Intelligence, Sales enablement, and X/Twitter growth. 51 Python tools, 73 reference docs.", + "category": "marketing", + "tags": [ + "marketing", + "content", + "seo", + "cro", + "growth", + "sales", + "copywriting", + "email", + "social-media", + "paid-ads", + "twitter", + "x-twitter" + ], + "version": "2.2.3", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "marketing-skill", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-03-30" + }, + { + "name": "notebooklm", + "author": "Alireza Rezvani", + "description": "Google NotebookLM browser-automation skill. 4 actions (read/extract, add-source, Studio outputs, create notebook). Screenshot-first + find-before-click + fire-and-notify async discipline. Path-B from megaprompt 03.", + "category": "research", + "tags": [ + "research", + "notebooklm", + "google", + "browser-automation", + "studio", + "audio-overview", + "research-pack", + "path-b-megaprompt" + ], + "version": "2.7.0", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "research/notebooklm", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/research/notebooklm", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-05-16" + }, + { + "name": "patent", + "author": "Alireza Rezvani", + "description": "Patent prior-art + IP landscape skill. FTO/novelty/family-resolver via 3-pass Jaccard heuristic. Research-pack convention. Path-B from megaprompt 12.", + "category": "research", + "tags": [ + "research", + "patent", + "prior-art", + "fto", + "freedom-to-operate", + "ip-landscape", + "research-pack", + "path-b-megaprompt" + ], + "version": "2.7.0", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "research/patent", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/research/patent", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-05-16" + }, + { + "name": "pm-skills", + "author": "Alireza Rezvani", + "description": "9 project management skills with 12 Python tools: senior PM, scrum master, Jira expert, Confluence expert, Atlassian admin, template creator.", + "category": "project-management", + "tags": [ + "project-management", + "scrum", + "agile", + "jira", + "confluence", + "atlassian" + ], + "version": "2.2.3", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "project-management", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/project-management", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-03-30" + }, + { + "name": "product-skills", + "author": "Alireza Rezvani", + "description": "13 product skills with 17 Python tools: product manager toolkit (RICE, PRDs), agile product owner, product strategist, UX researcher, UI design system, competitive teardown, landing page generator, SaaS scaffolder, product analytics, experiment designer, product discovery, roadmap communicator, code-to-prd, research summarizer, apple-hig-expert.", + "category": "product", + "tags": [ + "product", + "pm", + "agile", + "ux", + "design-system", + "competitive-analysis", + "landing-page", + "saas", + "analytics", + "experimentation", + "discovery", + "discovery", + "roadmap", + "apple-hig", + "design-guidelines" + ], + "version": "2.3.3", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "product-team", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/product-team", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-03-30" + }, + { + "name": "pulse", + "author": "Alireza Rezvani", + "description": "Multi-source recency research. Reddit/HN/X/web sentiment + trending. Research-pack convention (1 q/sec, three-count tracking). Path-B from megaprompt 01.", + "category": "research", + "tags": [ + "research", + "pulse", + "sentiment", + "reddit", + "hn", + "trending", + "research-pack", + "path-b-megaprompt" + ], + "version": "2.7.0", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "research/pulse", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/research/pulse", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-05-16" + }, + { + "name": "pw", + "author": "Alireza Rezvani", + "description": "Production-grade Playwright testing toolkit. 9 skills, 3 agents, 55 templates, TestRail + BrowserStack MCP integrations. Generate tests, fix flaky failures, migrate from Cypress/Selenium.", + "category": "development", + "tags": [ + "playwright", + "testing", + "e2e", + "qa", + "test-automation", + "browserstack", + "testrail" + ], + "version": "2.2.2", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "engineering-team/playwright-pro", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/playwright-pro", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-03-26" + }, + { + "name": "ra-qm-skills", + "author": "Alireza Rezvani", + "description": "14 regulatory affairs & quality management skills for HealthTech/MedTech: ISO 13485 QMS, MDR 2017/745, FDA 510(k)/PMA, GDPR/DSGVO, ISO 27001 ISMS, CAPA management, risk management, clinical evaluation, SOC 2 compliance.", + "category": "compliance", + "tags": [ + "regulatory", + "quality", + "compliance", + "iso-13485", + "mdr", + "fda", + "gdpr", + "medtech" + ], + "version": "2.2.3", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "ra-qm-team", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/ra-qm-team", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-03-30" + }, + { + "name": "reflect-skill", + "author": "Alireza Rezvani", + "description": "Light-prompt reflection skill. Single forcing question + structured journal capture. Path-B sibling of capture from megaprompt 08.", + "category": "productivity", + "tags": [ + "reflect", + "journaling", + "productivity", + "forcing-question", + "path-b-megaprompt" + ], + "version": "2.7.0", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "productivity/reflect", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/productivity/reflect", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-05-16" + }, + { + "name": "research-orchestrator", + "author": "Alireza Rezvani", + "description": "Research orchestrator (hybrid router + fallback). Deterministic SIGNALS classification routes to 6 specialists (pulse/litreview/grants/dossier/patent/syllabus) at >=2 signals, else runs own 8-step plan-decompose-search-synthesize-cite fallback. Routing transparency mandatory. Path-B from megaprompt 13.", + "category": "research", + "tags": [ + "research", + "router", + "orchestrator", + "classifier", + "fallback", + "hybrid-architecture", + "research-pack", + "path-b-megaprompt" + ], + "version": "2.7.0", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "research/research", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/research/research", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-05-16" + }, + { + "name": "research-summarizer", + "author": "Alireza Rezvani", + "description": "Structured research summarization — summarize academic papers, market research, user interviews, and competitive analysis into actionable insights.", + "category": "product", + "tags": [ + "research", + "summarization", + "analysis", + "insights", + "product" + ], + "version": "2.2.2", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "product-team/research-summarizer", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/product-team/research-summarizer", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-03-26" + }, + { + "name": "security-guidance", + "author": "Alireza Rezvani", + "description": "PreToolUse security reminder hook for Claude Code. Catches 12 common security anti-patterns in Edit/Write/MultiEdit operations BEFORE they happen — command injection (exec, os.system, subprocess shell=True), XSS (innerHTML, dangerouslySetInnerHTML, document.write), SQL injection (f-string queries, .format), unsafe deserialization (pickle, yaml.unsafe_load), code injection (eval, new Function), and GitHub Actions workflow injection. Session-state caching prevents duplicate warnings; 30-day auto-cleanup. Disable per-session with ENABLE_SECURITY_REMINDER=0. Ported from David Dworken at Anthropic.", + "category": "development", + "tags": [ + "security", + "hook", + "pretooluse", + "command-injection", + "xss", + "sql-injection", + "eval", + "pickle", + "engineering", + "static-analysis" + ], + "version": "2.7.3", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "engineering/security-guidance", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/engineering/security-guidance", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-05-17" + }, + { + "name": "self-improving-agent", + "author": "Alireza Rezvani", + "description": "Curate auto-memory, promote learnings to CLAUDE.md and rules, extract patterns into skills. Ships 5 slash commands (/si:review, /si:promote, /si:extract, /si:status, /si:remember) and 2 sub-agents (memory-analyst, skill-extractor).", + "category": "development", + "tags": [ + "memory", + "auto-memory", + "self-improvement", + "learning" + ], + "version": "2.3.0", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "engineering-team/self-improving-agent", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/self-improving-agent", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-03-30" + }, + { + "name": "slo-architect", + "author": "Alireza Rezvani", + "description": "End-to-end SLO/SLI/error-budget discipline per Google SRE Workbook. Ships SLO designer (refuses to render without required fields), error-budget calculator with multi-window burn-rate alert thresholds (PromQL-shaped), and SLO reviewer that catches the 7 common bugs. 4 references on principles + SLI design + error budget math + composition with feature-flags-architect/chaos-engineering/kubernetes-operator. Asset templates for SLO YAML and error budget policy. /slo-design slash command. NOT a generic observability skill.", + "category": "development", + "tags": [ + "slo", + "sli", + "sla", + "error-budget", + "burn-rate", + "sre", + "reliability", + "google-sre-workbook", + "observability" + ], + "version": "2.4.4", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "engineering/slo-architect", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/engineering/slo-architect", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-05-10" + }, + { + "name": "statistical-analyst", + "author": "Alireza Rezvani", + "description": "Hypothesis testing, A/B experiment analysis, sample size calculation, and confidence intervals. 3 stdlib-only Python tools: Z-test/t-test/chi-square with effect sizes, sample size calculator with power tradeoffs, and Wilson score confidence intervals.", + "category": "development", + "tags": [ + "statistics", + "hypothesis-testing", + "ab-testing", + "sample-size", + "confidence-interval" + ], + "version": "2.2.2", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "engineering/statistical-analyst", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/engineering/statistical-analyst", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-04-07" + }, + { + "name": "syllabus", + "author": "Alireza Rezvani", + "description": "Course supplementary-reading skill. Topic-grouper + bundled Node.js DOCX generator for syllabus-anchored reading lists. Research-pack convention. Path-B from megaprompt 10.", + "category": "research", + "tags": [ + "research", + "syllabus", + "curriculum", + "reading-list", + "docx", + "course", + "research-pack", + "path-b-megaprompt" + ], + "version": "2.7.0", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "research/syllabus", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/research/syllabus", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-05-16" + }, + { + "name": "terraform-patterns", + "author": "Alireza Rezvani", + "description": "Terraform infrastructure-as-code — module design patterns, state management, provider configuration, CI/CD integration, and multi-environment strategies.", + "category": "development", + "tags": [ + "terraform", + "iac", + "infrastructure", + "devops", + "cloud" + ], + "version": "2.2.2", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "engineering/terraform-patterns", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/engineering/terraform-patterns", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-03-26" + }, + { + "name": "vpe-advisor", + "author": "Alireza Rezvani", + "description": "VP of Engineering advisory: delivery throughput analyzer (DORA 4 metrics + cycle-time bottleneck identification with typical fixes per stage), engineering hiring funnel calculator (7-stage conversion + pipeline gap + weakest-stage fixes from sourcing to offer-accept), engineering team structure designer (squad/tribe model + manager-trigger + director-trigger + span-of-control). 4 in-depth references citing DORA / Spotify / Conway / Google SRE / Larson / Fournier. Standalone-installable; also bundled in c-level-skills. NOT a CTO skill — VPE owns how the team ships; CTO owns what to build.", + "category": "leadership", + "tags": [ + "vp-engineering", + "vpe", + "engineering-operations", + "dora", + "delivery-throughput", + "cycle-time", + "engineering-hiring", + "hiring-funnel", + "eng-team-structure", + "squad-tribe", + "manager-trigger", + "production-discipline" + ], + "version": "1.0.0", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "c-level-advisor/vpe-advisor", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/vpe-advisor", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-05-13" + }, + { + "name": "write-a-skill", + "author": "Alireza Rezvani", + "description": "Skill-author skill: create new agent skills with proper structure, progressive disclosure, and bundled resources. Derived from Matt Pocock's MIT-licensed write-a-skill with: (1) 3 stdlib Python validation tools (description validator, structure validator, review-checklist runner — all enforcing Matt's 6-item checklist), (2) 4 references citing 7-8 authoritative sources each (progressive disclosure principles, description design patterns, quality gates, companion tooling), (3) cs-skill-author persona agent + /cs:write-a-skill slash command. Matt's voice and 3-phase workflow (Gather → Draft → Review) preserved verbatim per MIT.", + "category": "development", + "tags": [ + "skill-authoring", + "matt-pocock", + "progressive-disclosure", + "validators", + "review-checklist", + "skill-quality", + "meta-skill" + ], + "version": "2.6.0", + "license": "MIT", + "origin": "internal", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "engineering/write-a-skill", + "readme": "https://github.com/alirezarezvani/claude-skills/tree/main/engineering/write-a-skill", + "icon": null, + "banner": null, + "github": null, + "added_at": "2026-05-13" + } + ], + "total": 62, + "counts": { + "internal": 61, + "community": 1 + }, + "generated_at": "2026-05-27" +} diff --git a/registry/schema/metadata.schema.json b/registry/schema/metadata.schema.json new file mode 100644 index 00000000..087373ed --- /dev/null +++ b/registry/schema/metadata.schema.json @@ -0,0 +1,121 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://github.com/alirezarezvani/claude-skills/registry/schema/metadata.schema.json", + "title": "Claude Skills Registry Metadata", + "description": "Schema for a community skill submission's metadata.json in the claude-skills registry", + "type": "object", + "required": ["name", "author", "description", "repository", "version", "category", "tags", "license"], + "additionalProperties": false, + "properties": { + "name": { + "type": "string", + "pattern": "^[a-z0-9][a-z0-9-]*[a-z0-9]$", + "minLength": 2, + "maxLength": 64, + "description": "Skill name (lowercase, hyphens only)" + }, + "author": { + "type": "string", + "pattern": "^[a-zA-Z0-9][a-zA-Z0-9-]*$", + "minLength": 1, + "maxLength": 64, + "description": "GitHub username of the author" + }, + "description": { + "type": "string", + "minLength": 10, + "maxLength": 300, + "description": "Short description of what the skill does" + }, + "repository": { + "type": "string", + "format": "uri", + "pattern": "^https://github\\.com/", + "description": "Public GitHub repository URL hosting the skill" + }, + "path": { + "type": "string", + "maxLength": 256, + "description": "Subdirectory within repo where SKILL.md lives (default: root)" + }, + "version": { + "type": "string", + "pattern": "^\\d+\\.\\d+\\.\\d+", + "description": "Semver version" + }, + "category": { + "type": "string", + "enum": [ + "development", + "data-engineering", + "devops", + "security", + "compliance", + "documentation", + "testing", + "research", + "productivity", + "finance", + "leadership", + "product", + "marketing", + "project-management", + "business-growth", + "commercial", + "operations", + "design", + "knowledge", + "customer-support", + "creative", + "education", + "other" + ], + "description": "Skill category" + }, + "tags": { + "type": "array", + "items": { + "type": "string", + "pattern": "^[a-z0-9-]+$", + "maxLength": 32 + }, + "minItems": 1, + "maxItems": 10, + "uniqueItems": true, + "description": "Tags for discoverability" + }, + "license": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "description": "SPDX license identifier" + }, + "model": { + "type": "string", + "minLength": 1, + "maxLength": 128, + "description": "Preferred model identifier (optional)" + }, + "adapters": { + "type": "array", + "items": { + "type": "string", + "minLength": 1, + "maxLength": 64 + }, + "minItems": 1, + "uniqueItems": true, + "description": "Supported tools/adapters (e.g. claude-code, codex, gemini-cli)" + }, + "icon": { + "type": "boolean", + "default": false, + "description": "Whether icon.png is included (256x256 PNG)" + }, + "banner": { + "type": "boolean", + "default": false, + "description": "Whether banner.png is included (1200x630 PNG, used for social sharing / OG image)" + } + } +} diff --git a/registry/scripts/build_index.py b/registry/scripts/build_index.py new file mode 100755 index 00000000..2d6ed877 --- /dev/null +++ b/registry/scripts/build_index.py @@ -0,0 +1,233 @@ +#!/usr/bin/env python3 +"""Generate registry/index.json from two sources. + + 1. Internal skills — the plugins declared in .claude-plugin/marketplace.json + (this repo's own skill packages). + 2. Community skills — submission folders under registry/skills/__/ + each containing a metadata.json (validated by validate.py). + +Usage: + python registry/scripts/build_index.py # deterministic, no network + python registry/scripts/build_index.py --github # enrich entries with live + # GitHub stars/forks (network) + python registry/scripts/build_index.py --check # fail if index.json is stale + +The default run performs no network calls so the committed index.json is +reproducible in CI. Stdlib only. + +Exit code: 0 on success; with --check, 1 if the on-disk index.json differs from +a freshly built one. +""" + +from __future__ import annotations + +import argparse +import json +import subprocess +import sys +from datetime import date +from pathlib import Path + +REGISTRY_ROOT = Path(__file__).resolve().parent.parent +REPO_ROOT = REGISTRY_ROOT.parent +MARKETPLACE_PATH = REPO_ROOT / ".claude-plugin" / "marketplace.json" +SKILLS_DIR = REGISTRY_ROOT / "skills" +INDEX_PATH = REGISTRY_ROOT / "index.json" + +REPO_URL = "https://github.com/alirezarezvani/claude-skills" +RAW_BASE = "https://raw.githubusercontent.com/alirezarezvani/claude-skills/main" +TREE_BASE = f"{REPO_URL}/tree/main" + + +def _git_first_commit_date(rel_path: str) -> str: + """Date of the first commit that touched rel_path (YYYY-MM-DD).""" + try: + out = subprocess.run( + ["git", "log", "--diff-filter=A", "--format=%aI", "--", rel_path], + cwd=REPO_ROOT, + stdout=subprocess.PIPE, + stderr=subprocess.DEVNULL, + text=True, + timeout=20, + ).stdout.strip().splitlines() + if out: + return out[-1].split("T")[0] + except (subprocess.SubprocessError, OSError): + pass + return date.today().isoformat() + + +def _fetch_github_stats(repository: str) -> dict | None: + """Best-effort GitHub repo stats via the public API (only with --github).""" + import urllib.error + import urllib.request + + repo_path = repository.replace("https://github.com/", "").rstrip("/") + api = f"https://api.github.com/repos/{repo_path}" + try: + req = urllib.request.Request(api, headers={"User-Agent": "claude-skills-registry"}) + with urllib.request.urlopen(req, timeout=15) as resp: # noqa: S310 (https only) + data = json.loads(resp.read().decode("utf-8")) + return { + "stars": data.get("stargazers_count", 0), + "forks": data.get("forks_count", 0), + "issues": data.get("open_issues_count", 0), + "language": data.get("language"), + "avatar": (data.get("owner") or {}).get("avatar_url", ""), + "description": data.get("description"), + } + except (urllib.error.URLError, ValueError, KeyError, TimeoutError): + return None + + +def _entry_base(meta: dict) -> dict: + """Common fields shared by internal and community entries.""" + return { + "name": meta["name"], + "author": meta["author"], + "description": meta["description"], + "category": meta.get("category", "other"), + "tags": meta.get("tags", []), + "version": meta.get("version", "0.0.0"), + "license": meta.get("license", "MIT"), + } + + +def build_internal_entries(with_github: bool) -> list[dict]: + if not MARKETPLACE_PATH.exists(): + return [] + market = json.loads(MARKETPLACE_PATH.read_text(encoding="utf-8")) + owner = (market.get("owner") or {}).get("name", "alirezarezvani") + entries: list[dict] = [] + for plugin in market.get("plugins", []): + source = (plugin.get("source") or "").lstrip("./") + author = (plugin.get("author") or {}).get("name") or owner + skill_md = REPO_ROOT / source / "SKILL.md" + readme = ( + f"{RAW_BASE}/{source}/SKILL.md" + if skill_md.exists() + else f"{TREE_BASE}/{source}" + ) + entry = { + "name": plugin["name"], + "author": author, + "description": plugin.get("description", ""), + "category": plugin.get("category", "other"), + "tags": plugin.get("keywords", []), + "version": plugin.get("version", "0.0.0"), + "license": "MIT", + "origin": "internal", + "repository": REPO_URL, + "path": source, + "readme": readme, + "icon": None, + "banner": None, + "github": None, + "added_at": _git_first_commit_date(source) if source else date.today().isoformat(), + } + if with_github: + entry["github"] = _fetch_github_stats(REPO_URL) + entries.append(entry) + return entries + + +def build_community_entries(with_github: bool) -> list[dict]: + if not SKILLS_DIR.exists(): + return [] + entries: list[dict] = [] + for folder in sorted(SKILLS_DIR.iterdir()): + if not folder.is_dir() or "__" not in folder.name: + continue + meta_path = folder / "metadata.json" + if not meta_path.exists(): + print(f" skipping {folder.name}: no metadata.json", file=sys.stderr) + continue + try: + meta = json.loads(meta_path.read_text(encoding="utf-8")) + except json.JSONDecodeError as exc: + print(f" skipping {folder.name}: invalid metadata.json — {exc}", file=sys.stderr) + continue + + has_icon = meta.get("icon") is True and (folder / "icon.png").exists() + has_banner = meta.get("banner") is True and (folder / "banner.png").exists() + rel = f"registry/skills/{folder.name}" + + entry = _entry_base(meta) + entry.update( + { + "origin": "community", + "repository": meta["repository"], + "path": meta.get("path", ""), + "readme": f"{RAW_BASE}/{rel}/README.md", + "icon": f"{RAW_BASE}/{rel}/icon.png" if has_icon else None, + "banner": f"{RAW_BASE}/{rel}/banner.png" if has_banner else None, + "github": _fetch_github_stats(meta["repository"]) if with_github else None, + "added_at": _git_first_commit_date(rel), + } + ) + if "adapters" in meta: + entry["adapters"] = meta["adapters"] + if "model" in meta: + entry["model"] = meta["model"] + entries.append(entry) + return entries + + +def build_index(with_github: bool = False) -> dict: + internal = build_internal_entries(with_github) + community = build_community_entries(with_github) + agents = internal + community + agents.sort(key=lambda e: (e["origin"] != "community", e["name"].lower())) + return { + "skills": agents, + "total": len(agents), + "counts": {"internal": len(internal), "community": len(community)}, + "generated_at": date.today().isoformat(), + } + + +def _serialize(index: dict) -> str: + return json.dumps(index, indent=2, ensure_ascii=False) + "\n" + + +def main(argv: list[str] | None = None) -> int: + parser = argparse.ArgumentParser(description="Build registry/index.json.") + parser.add_argument( + "--github", action="store_true", help="enrich entries with live GitHub stats (network)" + ) + parser.add_argument( + "--check", + action="store_true", + help="do not write; exit 1 if index.json is out of date", + ) + args = parser.parse_args(argv) + + index = build_index(with_github=args.github) + serialized = _serialize(index) + + if args.check: + # generated_at changes daily; compare everything except that field. + current = json.loads(INDEX_PATH.read_text(encoding="utf-8")) if INDEX_PATH.exists() else {} + fresh = json.loads(serialized) + current.pop("generated_at", None) + fresh.pop("generated_at", None) + if current != fresh: + print( + "index.json is stale. Run: python registry/scripts/build_index.py", + file=sys.stderr, + ) + return 1 + print("index.json is up to date.") + return 0 + + INDEX_PATH.write_text(serialized, encoding="utf-8") + print( + f"Wrote {INDEX_PATH.relative_to(REPO_ROOT)}: " + f"{index['total']} skills " + f"({index['counts']['internal']} internal, {index['counts']['community']} community)" + ) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/registry/scripts/validate.py b/registry/scripts/validate.py new file mode 100755 index 00000000..4cbfbcfd --- /dev/null +++ b/registry/scripts/validate.py @@ -0,0 +1,256 @@ +#!/usr/bin/env python3 +"""Validate a claude-skills registry submission folder. + +Usage: + python registry/scripts/validate.py registry/skills/__/ [more...] + python registry/scripts/validate.py --all # validate every submission + python registry/scripts/validate.py --clone # also clone repo + verify SKILL.md + +Checks: + 1. metadata.json exists and validates against schema/metadata.schema.json + 2. Folder name matches __ from metadata + 3. README.md exists and is non-empty + 4. If icon: true, icon.png exists; if banner: true, banner.png exists + 5. With --clone: clones the repository (shallow) and verifies SKILL.md exists + at the declared path + +Stdlib only. The JSON-Schema validation supports the draft-07 subset used by +schema/metadata.schema.json (type/required/properties/additionalProperties/ +enum/pattern/min-maxLength/min-maxItems/uniqueItems/items/format:uri). + +Exit code: 0 if all submissions pass, 1 otherwise. +""" + +from __future__ import annotations + +import argparse +import json +import re +import shutil +import subprocess +import sys +import tempfile +from pathlib import Path + +REGISTRY_ROOT = Path(__file__).resolve().parent.parent +SCHEMA_PATH = REGISTRY_ROOT / "schema" / "metadata.schema.json" +SKILLS_DIR = REGISTRY_ROOT / "skills" + + +# --------------------------------------------------------------------------- # +# Minimal JSON-Schema (draft-07 subset) validator +# --------------------------------------------------------------------------- # +def _type_ok(value, expected: str) -> bool: + if expected == "string": + return isinstance(value, str) + if expected == "array": + return isinstance(value, list) + if expected == "object": + return isinstance(value, dict) + if expected == "boolean": + return isinstance(value, bool) + if expected == "integer": + return isinstance(value, int) and not isinstance(value, bool) + if expected == "number": + return isinstance(value, (int, float)) and not isinstance(value, bool) + return True + + +def validate_schema(instance, schema, path: str = "") -> list[str]: + """Return a list of human-readable schema violation strings (empty == valid).""" + errors: list[str] = [] + here = path or "(root)" + + expected_type = schema.get("type") + if expected_type and not _type_ok(instance, expected_type): + errors.append(f"{here}: expected type {expected_type}") + return errors # further checks assume the type matched + + if "enum" in schema and instance not in schema["enum"]: + errors.append(f"{here}: '{instance}' is not one of {schema['enum']}") + + if isinstance(instance, str): + if "minLength" in schema and len(instance) < schema["minLength"]: + errors.append(f"{here}: shorter than minLength {schema['minLength']}") + if "maxLength" in schema and len(instance) > schema["maxLength"]: + errors.append(f"{here}: longer than maxLength {schema['maxLength']}") + if "pattern" in schema and not re.search(schema["pattern"], instance): + errors.append(f"{here}: does not match pattern {schema['pattern']}") + if schema.get("format") == "uri" and not re.match(r"^[a-z][a-z0-9+.\-]*://", instance): + errors.append(f"{here}: not a valid URI") + + if isinstance(instance, list): + if "minItems" in schema and len(instance) < schema["minItems"]: + errors.append(f"{here}: fewer than minItems {schema['minItems']}") + if "maxItems" in schema and len(instance) > schema["maxItems"]: + errors.append(f"{here}: more than maxItems {schema['maxItems']}") + if schema.get("uniqueItems") and len(instance) != len( + {json.dumps(i, sort_keys=True) for i in instance} + ): + errors.append(f"{here}: items are not unique") + item_schema = schema.get("items") + if item_schema: + for idx, item in enumerate(instance): + errors.extend(validate_schema(item, item_schema, f"{here}[{idx}]")) + + if isinstance(instance, dict): + for req in schema.get("required", []): + if req not in instance: + errors.append(f"{here}: missing required property '{req}'") + props = schema.get("properties", {}) + if schema.get("additionalProperties") is False: + for key in instance: + if key not in props: + errors.append(f"{here}: additional property '{key}' not allowed") + for key, subschema in props.items(): + if key in instance: + errors.extend(validate_schema(instance[key], subschema, f"{here}.{key}")) + + return errors + + +# --------------------------------------------------------------------------- # +# Submission validation +# --------------------------------------------------------------------------- # +class Result: + def __init__(self) -> None: + self.errors: list[str] = [] + self.warnings: list[str] = [] + + @property + def passed(self) -> bool: + return not self.errors + + +def validate_submission(folder: Path, schema: dict, clone: bool = False) -> Result: + result = Result() + folder = folder.resolve() + + if not folder.is_dir(): + result.errors.append(f"folder does not exist: {folder}") + return result + + folder_name = folder.name + if "__" not in folder_name: + result.errors.append( + f"folder name must use __ format, got: {folder_name}" + ) + return result + + metadata_path = folder / "metadata.json" + if not metadata_path.exists(): + result.errors.append("metadata.json not found") + return result + + try: + metadata = json.loads(metadata_path.read_text(encoding="utf-8")) + except json.JSONDecodeError as exc: + result.errors.append(f"metadata.json is not valid JSON: {exc}") + return result + + for err in validate_schema(metadata, schema): + result.errors.append(f"schema: {err}") + + author = metadata.get("author") + name = metadata.get("name") + if author and name: + expected = f"{author}__{name}" + if folder_name != expected: + result.errors.append( + f"folder name mismatch: expected '{expected}' from metadata, got '{folder_name}'" + ) + + readme_path = folder / "README.md" + if not readme_path.exists(): + result.errors.append("README.md not found") + else: + content = readme_path.read_text(encoding="utf-8").strip() + if not content: + result.errors.append("README.md is empty") + elif len(content) < 50: + result.warnings.append("README.md is very short — consider adding more detail") + + if metadata.get("icon") is True and not (folder / "icon.png").exists(): + result.errors.append('icon.png not found but metadata has "icon": true') + if metadata.get("banner") is True and not (folder / "banner.png").exists(): + result.errors.append('banner.png not found but metadata has "banner": true') + + if clone and isinstance(metadata.get("repository"), str) and not result.errors: + _clone_and_verify(metadata, result) + + return result + + +def _clone_and_verify(metadata: dict, result: Result) -> None: + repo = metadata["repository"] + tmp = Path(tempfile.mkdtemp(prefix="registry-validate-")) + try: + print(f" cloning {repo} ...") + proc = subprocess.run( + ["git", "clone", "--depth", "1", repo, str(tmp)], + stdout=subprocess.PIPE, + stderr=subprocess.STDOUT, + timeout=60, + text=True, + ) + if proc.returncode != 0: + result.errors.append(f"failed to clone repository: {proc.stdout.strip()[:200]}") + return + sub = metadata.get("path", "") or "" + skill_root = (tmp / sub).resolve() + if not str(skill_root).startswith(str(tmp.resolve())): + result.errors.append(f"path escapes repository root: {sub!r}") + return + if not (skill_root / "SKILL.md").exists(): + suffix = f' at path "{sub}"' if sub else "" + result.errors.append(f"SKILL.md not found in repository{suffix}") + except subprocess.TimeoutExpired: + result.errors.append("timed out cloning repository") + finally: + shutil.rmtree(tmp, ignore_errors=True) + + +# --------------------------------------------------------------------------- # +# CLI +# --------------------------------------------------------------------------- # +def main(argv: list[str] | None = None) -> int: + parser = argparse.ArgumentParser(description="Validate registry skill submissions.") + parser.add_argument("folders", nargs="*", help="submission folder(s) to validate") + parser.add_argument("--all", action="store_true", help="validate every folder under skills/") + parser.add_argument( + "--clone", + action="store_true", + help="clone each repository and verify SKILL.md exists (network required)", + ) + args = parser.parse_args(argv) + + schema = json.loads(SCHEMA_PATH.read_text(encoding="utf-8")) + + targets: list[Path] = [Path(f) for f in args.folders] + if args.all: + targets = sorted( + p for p in SKILLS_DIR.iterdir() if p.is_dir() and "__" in p.name + ) + + if not targets: + parser.error("provide one or more folders, or use --all") + + all_passed = True + for folder in targets: + print(f"\nValidating: {folder}") + result = validate_submission(folder, schema, clone=args.clone) + for err in result.errors: + print(f" x {err}") + for warn in result.warnings: + print(f" ! {warn}") + if result.passed: + print(" ok valid") + else: + all_passed = False + + print() + return 0 if all_passed else 1 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/registry/skills/alirezarezvani__example-skill/README.md b/registry/skills/alirezarezvani__example-skill/README.md new file mode 100644 index 00000000..06cc0f7a --- /dev/null +++ b/registry/skills/alirezarezvani__example-skill/README.md @@ -0,0 +1,19 @@ +# example-skill + +This is a **template submission** that shows the shape of a community entry in +the claude-skills registry. Use it as a starting point for your own skill. + +## How to submit your own + +1. Copy this folder to `registry/skills/__/` +2. Edit `metadata.json`: + - `name` / `author` must match the folder name (`__`) + - `repository` must be a public GitHub repo that contains a `SKILL.md` + - `path` is the subdirectory within that repo where `SKILL.md` lives (omit or `""` for the repo root) +3. Replace this `README.md` with a description of your skill +4. Open a pull request + +CI validates your `metadata.json` against the schema, checks the folder name, +and (in the validate workflow) clones your repo to confirm `SKILL.md` exists. + +See [../../CONTRIBUTING.md](../../CONTRIBUTING.md) for the full guide. diff --git a/registry/skills/alirezarezvani__example-skill/metadata.json b/registry/skills/alirezarezvani__example-skill/metadata.json new file mode 100644 index 00000000..dec75b82 --- /dev/null +++ b/registry/skills/alirezarezvani__example-skill/metadata.json @@ -0,0 +1,14 @@ +{ + "name": "example-skill", + "author": "alirezarezvani", + "description": "Example community submission. Copy this folder, point it at your own public repo that contains a SKILL.md, and open a PR. See registry/CONTRIBUTING.md.", + "repository": "https://github.com/alirezarezvani/claude-skills", + "path": "engineering/caveman/skills/caveman", + "version": "1.0.0", + "category": "productivity", + "tags": ["example", "template", "getting-started"], + "license": "MIT", + "adapters": ["claude-code", "codex", "gemini-cli"], + "icon": false, + "banner": false +}