git:20260820.6c8d428 to git:20260906.e36bbe4

- # Repository Agent Instructions

-

- This repository is the world's most comprehensive curated collection of high-quality AI Agent Skills. It supports automated skill discovery, quality-gated ingestion, and upstream synchronization.

-

- ## Architecture Overview

-

- ```

- skills/<category>/<skill>/SKILL.md ← Canonical categorized source (AI clients read from here)

- openclaw-skills/<skill>/SKILL.md ← Auto-generated flat export for OpenClaw

- docs/sources/in-house.skills.json ← Provenance mapping (every skill tracked)

- docs/catalog.json ← Machine-readable full catalog

- docs/TAGS-INDEX.md ← Cross-category tag-based index

- .github/assets/repo-banner.svg ← Auto-generated README banner from docs/catalog.json

- ```

-

- ## Installation Root By Client

-

- - `OpenClaw`: use `openclaw-skills/` (flat layout)

- - `Codex`, `Claude Code`, `Cursor`, and similar: use `skills/` (categorized layout)

-

- ## Golden Rules

-

- 1. **Never manually edit** `openclaw-skills/`, `skills/*/README.md`, `docs/catalog.json`, `docs/TAGS-INDEX.md`, or `.github/assets/repo-banner.svg` — they are auto-generated.

- 2. **Always run the full pipeline** after any skill change (see §Pipeline below).

- 3. **Every skill must have complete frontmatter** (name, description, zh_description, version, tags, quality, source).

- 4. **Every copied external skill must have an explicit permissive license** (`license: MIT`, `Apache-2.0`, etc.). If the upstream repository has no detectable license but the candidate is high quality, auto-create an original `in-house` rewrite instead of copying upstream text.

- 5. **Every skill must pass quality lint** (`python scripts/lint_skill_quality.py --min-lines 50`).

- 6. **Source provenance must be tracked** — every skill has an entry in `docs/sources/*.skills.json`.

- 7. **Keep bilingual READMEs synchronized** — when updating `README.md`, update `README.en.md` in the same change and run `python scripts/check_readme_sync.py`.

- 8. **Keep all public counts generated from one source of truth** — skill totals in README badges/text, `docs/catalog.json`, and `.github/assets/repo-banner.svg` must match the actual `skills/*/*/SKILL.md` tree. Run `python scripts/refresh_repo_views.py`, `python scripts/build_catalog_json.py`, and `python scripts/check_readme_sync.py`; never hand-edit counts or banner numbers.

- 9. **Prefer authenticated GitHub access for automation** — before running discovery or upstream sync, verify `gh auth status`. If `GITHUB_TOKEN` / `GH_TOKEN` are unset, repository automation should fall back to the locally authenticated `gh` token instead of running unauthenticated searches that cause `401` or premature rate limiting.

- 10. **Treat warning sources differently** — distinguish between actionable repository regressions (quality lint, missing frontmatter, generated diff drift) and external-state noise (GitHub API rate limits, exploratory `404` upstream paths, temporary DNS failures). Fix the former in the same run; report the latter with enough detail to retry or repair provenance later.

- 11. **Chinese public docs must stay Chinese** — every newly added or materially updated skill must include a short, plain `zh_description` frontmatter field. `description` may stay English for Codex/Claude trigger quality, but generated Chinese surfaces (`README.md` and `skills/*/README.md`) must use concise Chinese text, not copied English descriptions.

- 12. **Prefer staged pull requests for recurring maintenance** — if the run includes both a focused additive change (for example a new skill) and a broad upstream sync, split them into separate `codex/` branches and PRs so review and rollback stay manageable.

- 13. **Provenance v2 is mandatory** — active mappings must use explicit `kind`, `origins[]`, `artifacts[]`, owned `managed_files[]`, and dependency locks for composites. Default branches and canary channels are monitor-only; automatic replacement is limited to reviewed stable releases or immutable fixed refs.

-

- ---

-

- ## Automated Operations (SOP for AI Agents)

-

- ### Recurring Run Preflight (每周例行前置检查)

-

- Run this before Operation 1/2/3:

-

- ```bash

- git fetch origin --prune

- gh auth status

- git status --short --branch

- ```

-

- Interpretation:

-

- - If `gh auth status` fails, fix GitHub authentication before discovery/sync work.

- - If the worktree is dirty, either stop or isolate the maintenance work on a fresh `codex/` branch after understanding the existing changes.

- - If network or DNS is down, do not trust `0 updates found` as a complete freshness result; record it as a partial check and retry once connectivity is restored.

-

- ### Operation 1: Discover & Add New Skills (全网搜集优秀技能)

-

- **Trigger**: User says "add best skills", "find new skills", "搜集优秀技能", "增加一些好的skills" or similar.

-

- **Procedure**:

-

- ```

- Step 1: DISCOVER — Search all platforms for candidate skills

- ├── Run: python scripts/discover_new_skills.py --output docs/sources/reports/discovery.json

- │ (Uses `GITHUB_TOKEN` / `GH_TOKEN` when present, otherwise should reuse local `gh` authentication)

- ├── Additionally search manually via:

- │ ├── npx skills find "<keyword>" (skills.sh)

- │ ├── clawhub search "<keyword>" (ClawHub)

- │ ├── web_search for GitHub trending repos with SKILL.md

- │ └── Check watched repos: alirezarezvani/claude-skills, opera/superpowers

- └── Collect: skill name, source URL, description, quality indicators

-

- Step 2: EVALUATE — Score and filter candidates

- ├── Dedup against existing skills: compare with skills/*/*/SKILL.md directory names

- ├── Quality criteria (must meet ALL):

- │ ├── Content depth: original SKILL.md ≥ 50 lines (or you will expand it)

- │ ├── Practical value: contains actionable guidance, not just descriptions

- │ ├── Non-overlapping: does not duplicate an existing skill's coverage

- │ └── Well-scoped: focused on one domain, not a vague meta-skill

- ├── License criteria for external skills (must meet ALL):

- │ ├── Check upstream repo license via `gh api repos/<owner>/<repo> --jq .license`

- │ ├── Accept only permissive licenses allowed by `scripts/audit_licenses.py`

- │ ├── Record the accepted license in `SKILL.md` frontmatter

- │ └── If license is missing/unknown and the candidate is high quality, auto-generate an original `in-house` MIT rewrite; never copy unlicensed upstream text

- └── Assign recommended category from the 16 existing categories (see §Categories)

-

- Step 3: INGEST — Download and add to repository

- ├── For each approved skill:

- │ ├── Download SKILL.md from source (GitHub raw URL, skills.sh, etc.)

- │ ├── Verify license before writing files; for missing/unknown license metadata, write only an original in-house rewrite

- │ ├── If content < 80 lines, expand with professional content to ≥ 100 lines

- │ ├── Ensure these sections exist: Trigger/When to Use, Core Capabilities, Common Patterns (with code blocks), Boundaries

- │ ├── Place in: skills/<category>/<skill-name>/SKILL.md

- │ └── If skill has auxiliary files (templates, configs), include them

- └── Run: python scripts/ingest_skill.py --dir skills/<category>/<skill-name> --source "<source_url>"

- (This auto-enriches frontmatter and updates provenance mapping)

-

- Step 4: PIPELINE — Run full refresh and validation

- ├── python scripts/enrich_frontmatter.py

- ├── python scripts/bootstrap_in_house_sources.py --write-json docs/sources/in-house.skills.json

- ├── python scripts/refresh_repo_views.py

- ├── python scripts/generate_tags_index.py

- ├── python scripts/build_catalog_json.py

- ├── python scripts/check_readme_sync.py

- ├── python scripts/lint_skill_quality.py --min-lines 50

- ├── python scripts/audit_skill_portfolio.py --check-policy

- ├── python scripts/audit_licenses.py

- ├── python scripts/validate_skill_sources.py

- ├── python scripts/check_source_coverage.py --min-percent 100

- ├── python -m pytest -q tests

- └── git diff --exit-code (verify generated files are committed)

-

- Step 5: COMMIT & PUSH

- ├── git add -A

- ├── git commit -m "feat: add N new skills from <sources>"

- ├── git push

- └── Prefer a focused PR if the run also includes bulk upstream sync changes

- ```

-

- ### Operation 2: Check & Update Existing Skills (检查并更新现有技能)

-

- **Trigger**: User says "check for updates", "update skills", "检查更新", "同步最新" or similar.

-

- **Procedure**:

-

- ```

- Step 1: CHECK UPSTREAM — Scan for updated skills

- ├── Run: python scripts/sync_upstream.py --check-only

- │ (Reads docs/sources/in-house.skills.json, checks upstream repos for new commits, and should reuse local `gh` auth if env tokens are absent)

- │ (`--check-only` is strictly read-only; add `--record-check` only when timestamps should be persisted)

- └── Output: list of skills with available updates and their diffs

-

- Step 2: APPLY UPDATES

- ├── Stable release / immutable fixed ref: run python scripts/sync_upstream.py --apply

- │ (Downloads the reviewed artifact set, replaces managed files, updates metadata)

- ├── Default branch / canary: monitor the commit range and record the curation decision;

- │ never automatically replace canonical content

- ├── For each updated skill:

- │ ├── Preserve local frontmatter enrichments (tags, quality, etc.)

- │ ├── Update: updated_at, version (bump patch)

- │ ├── Verify content quality after merge

- │ └── If upstream becomes too thin for repository standards, add a local quality supplement instead of reverting the upstream body wholesale

- └── If conflicts exist, prefer upstream content but keep local frontmatter

-

- Step 3: QUALITY CHECK

- ├── python scripts/lint_skill_quality.py --min-lines 50

- ├── Fix WARN/FAIL items caused by repository quality policy in the same branch

- └── Record external-state blockers separately (e.g. raw-path `404`, GitHub API `403 rate limit exceeded`)

-

- Step 4: PIPELINE — Same as Operation 1, Step 4

-

- Step 5: COMMIT & PUSH

- ├── git add -A

- ├── git commit -m "chore: sync upstream updates for N skills"

- └── git push

- ```

-

- ### Operation 3: Combined — Discover + Update (搜集新技能并更新旧技能)

-

- **Trigger**: User says "add new and update existing", "全面更新", "搜集新的并更新旧的" or similar.

-

- **Procedure**: Execute Operation 2 first (update existing), then Operation 1 (add new). This ensures the baseline is current before adding new skills.

-

- **Preferred PR strategy**:

-

- - PR 1: small, focused additions or warning fixes

- - PR 2: bulk upstream sync

- - Merge only after each PR has passed the local full pipeline cleanly

-

- ---

-

- ## Categories (16 total)

-

- | Category Directory | Description | Example Skills |

- |---|---|---|

- | `developer-engineering` | Programming languages, frameworks, dev tools | kubernetes-specialist, nextjs-app-router, rust-engineer |

- | `ai-workflow` | Agent workflows, planning, context engineering, review, verification | context-engineering, agent-workflow-designer, test-driven-development |

- | `ai-agent-platform` | Agent platforms, orchestration, MCP, memory systems | agent-hub, hermes-agent, self-improving-agent |

- | `engineering-workflow-automation` | Git workflows, CI/CD automation, browser testing, code generation | yeet, gh-fix-ci, playwright |

- | `devops-sre` | Infrastructure, CI/CD, monitoring, reliability | senior-devops, senior-architect |

- | `finance-investing` | Financial analysis, trading, portfolio management | financial-analyst, saas-metrics-coach |

- | `growth-operations-xiaohongshu` | Marketing, SEO, social media, growth | seo-audit, campaign-manager |

- | `office-white-collar` | Document processing, spreadsheets, presentations, office workflows | spreadsheet, pptx, docx |

- | `knowledge-and-pm-integrations` | Knowledge bases and project-management integrations | notion-spec-to-implementation, linear, obsidian |

- | `operations-general` | Productivity, search, communication, utilities | confidence-check, fact-checker |

- | `product-design` | UX/UI, product management, design systems | figma, ux-researcher-designer |

- | `security-and-reliability` | Security auditing, compliance, threat modeling | security-best-practices, skill-security-auditor |

- | `multimodal-media` | Images, speech, video, screenshots, summaries, transcription | imagegen, sora, transcribe |

- | `deployment-platforms` | Platform-specific deployment guides | cloudflare-workers, vercel |

- | `openclaw-memory-and-safety` | Memory, input guards, RAG, runbooks | honcho, input-guard, rag-architect |

- | `task-understanding-decomposition` | Task understanding support, live search, reflection | tavily-search, reflect-learn |

-

- **Category selection rules**:

- - Match primary function, not secondary use case

- - If a skill spans two categories, choose the one with fewer skills to balance distribution

- - If uncertain, use `operations-general` as default

-

- ---

-

- ## Frontmatter Schema (Required)

-

- Every `SKILL.md` must have this frontmatter:

-

- ```yaml

- ---

- name: skill-name # Must match directory name

- description: "One-line description" # Quoted if contains special chars

- zh_description: "简洁中文说明" # Required for Chinese README/category README display

- version: "1.0.0" # Semver

- author: seaworld008 # Contributor GitHub ID

- source: in-house # in-house | skills.sh | clawhub | github:<owner>/<repo> | community

- source_url: "" # Original URL if from external source

- license: MIT # Required for every external source; omit only for in-house

- tags: [tag1, tag2, tag3] # Cross-category searchable tags

- created_at: "2026-03-27" # YYYY-MM-DD

- updated_at: "2026-03-27" # YYYY-MM-DD

- quality: 4 # 1-5 (1=stub, 3=acceptable, 5=best-in-class)

- complexity: intermediate # beginner | intermediate | advanced

- ---

- ```

- ## Quality Standards

- | Rating | Lines | Requirements |

- |--------|-------|-------------|

- | 5 (Best) | ≥200 | Comprehensive guide with multiple code examples, edge cases, anti-patterns |

- | 4 (Good) | ≥100 | Solid coverage with code examples and practical templates |

- | 3 (OK) | ≥80 | Basic coverage with at least 1 code block |

- | 2 (Thin) | ≥50 | Minimal viable content, needs expansion |

- | 1 (Stub) | <50 | Placeholder only — should not be committed |

- **Minimum for commit**: quality ≥ 2, lines ≥ 50

- ---

- ## Script Reference

- | Script | Purpose | When to Run |

- |--------|---------|-------------|

- | `discover_new_skills.py` | Search GitHub/skills.sh/ClawHub for new skills | Operation 1, Step 1 |

- | `ingest_skill.py` | Register a new skill's provenance and enrich metadata | Operation 1, Step 3 |

- | `sync_upstream.py` | Read-only checks, explicit check recording, and policy-gated apply | Operation 2 |

- | `migrate_provenance_v2.py` | Migrate source mappings and explicitly refresh managed digests | After provenance changes |

- | `enrich_frontmatter.py` | Auto-fill missing frontmatter fields | After any skill addition |

- | `bootstrap_in_house_sources.py` | Regenerate provenance mapping | After any skill addition |

- | `refresh_repo_views.py` | Regenerate category READMEs + openclaw export | After any change |

- | `generate_tags_index.py` | Regenerate docs/TAGS-INDEX.md | After any change |

- | `build_catalog_json.py` | Regenerate docs/catalog.json and README banner | After any change |

- | `generate_repo_banner.py` | Regenerate .github/assets/repo-banner.svg from docs/catalog.json | Usually via build_catalog_json.py |

- | `check_readme_sync.py` | Verify Chinese and English READMEs match the skill tree | After README or skill list changes |

- | `lint_skill_quality.py` | Quality gate check | Before commit |

- | `audit_skill_portfolio.py --check-policy` | Prevent retired/redundant skills from being reintroduced | Before commit |

- | `audit_licenses.py` | License gate for external skills | Before commit |

- | `generate_changelog.py` | Auto-generate CHANGELOG.md | Before release |

- ### One-liner: Full Pipeline

- ```bash

- python scripts/enrich_frontmatter.py && \

- python scripts/bootstrap_in_house_sources.py --write-json docs/sources/in-house.skills.json && \

- python scripts/refresh_repo_views.py && \

- python scripts/generate_tags_index.py && \

- python scripts/build_catalog_json.py && \

- python scripts/check_readme_sync.py && \

- python scripts/lint_skill_quality.py --min-lines 50 && \

- python scripts/audit_skill_portfolio.py --check-policy && \

- python scripts/audit_licenses.py && \

- python -m pytest -q tests

- ```

- Windows (PowerShell):

- ```powershell

- python scripts/enrich_frontmatter.py; python scripts/bootstrap_in_house_sources.py --write-json docs/sources/in-house.skills.json; python scripts/refresh_repo_views.py; python scripts/generate_tags_index.py; python scripts/build_catalog_json.py; python scripts/check_readme_sync.py; python scripts/lint_skill_quality.py --min-lines 50; python scripts/audit_skill_portfolio.py --check-policy; python scripts/audit_licenses.py; python -m pytest -q tests

- ```