From 7209e5b0c92e65cab71ea1d5b71eda1993d82d1c Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sat, 29 Nov 2025 18:01:04 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 12 +++++ README.md | 3 ++ plugin.lock.json | 44 +++++++++++++++++++ skills/github-repo-skill/SKILL.md | 73 +++++++++++++++++++++++++++++++ 4 files changed, 132 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 plugin.lock.json create mode 100644 skills/github-repo-skill/SKILL.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..dc5fa4e --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,12 @@ +{ + "name": "github-repo-skill", + "description": "Best practice for repository creation, maintenance, and hygeiebe", + "version": "0.0.0-2025.11.28", + "author": { + "name": "Chris Mungall", + "email": "cjmungall@lbl.gov" + }, + "skills": [ + "./skills/github-repo-skill" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..40ea550 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# github-repo-skill + +Best practice for repository creation, maintenance, and hygeiebe diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..93ad32b --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,44 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:berkeleybop/bbop-skills:github-repo-skill", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "942b61788414168b0461511ed9c3c4de350ade94", + "treeHash": "8d2ac831ce44cf55d7ddc94ecdc88886b017f5e5ccf81a8dbcc4fad5ef83cd34", + "generatedAt": "2025-11-28T10:14:15.158361Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "github-repo-skill", + "description": "Best practice for repository creation, maintenance, and hygeiebe" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "909224dc16ff174c874e3321109f10c908e5af0ac42251c2d09514195b9c84dd" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "22597a4132b5e1e1d18467ce0dbadf6830b971b33a085bd6eee236c657bb7134" + }, + { + "path": "skills/github-repo-skill/SKILL.md", + "sha256": "0e70a33bf76c37d0a608258f2ba8ae917004851c31322749d54796a64e8e8143" + } + ], + "dirSha256": "8d2ac831ce44cf55d7ddc94ecdc88886b017f5e5ccf81a8dbcc4fad5ef83cd34" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/github-repo-skill/SKILL.md b/skills/github-repo-skill/SKILL.md new file mode 100644 index 0000000..f2011b0 --- /dev/null +++ b/skills/github-repo-skill/SKILL.md @@ -0,0 +1,73 @@ +--- +name: github-repo-skill +description: Guide for creating new GitHub repos and best practice for existing GitHub repos, applicable to both code and non-code projects +license: CC-0 +--- + +# github-repo-skill + +## overview + +To create and maintain high-quality repos that conform to Mungall group / BBOP best practice, use this skill. Use this skill regardless of whether the repo is for code or non-code (ontology, linkml schemas, curated content, analyses, websites). Use this skill for both new repos, for migrating legacy repos, or for ongoing maintenance. + +--- + +# Principles + +## Follow existing copier templates + +The Mungall group favors the use of [copier](https://copier.readthedocs.io/) and blesses the following templates: + +* For LinkML schemas: https://github.com/linkml/linkml-project-copier +* For code: https://github.com/monarch-initiative/monarch-project-copier +* For ontologies: https://github.com/INCATools/ontology-development-kit (uses bespoke framework, not copier) + +These should always be used for new repos. Pre-existing repos should try and follow these or migrate towards them. + +Additionally the group uses additional drop-in templates for AI integrations: + +* https://github.com/ai4curation/github-ai-integrations + +## Favored tools + +These are included in the templates above but some general over-arching preferences: + +* modern python dev stack: `uv`, `ruff` +* for builds, both `just` and `make` are favored, with `just` favored for non-pipeline cases + +## Engineering best practice + +* pydantic or pydantic generated from LinkML for data models and data access objects (dataclasses are fine for engine objects) +* always use typing +* testing: + * follow TDD, use pytest-style tests, `@pytest.mark.parametrize` is good for combinatorial testing + * always use doctests: make them informative for humans but also serving as additional tests + * ensure unit tests and tests that depend on external APIs, infrastructure etc are separated (e.g. `pytest.mark.integration`) + * do not create mock tests unless explicitly requested + * for data-oriented projects, yaml, tsvs, etc can go in `tests/input` or smilar + * for schemas, following the linkml templates, and ensure schemas and example test data is validated + * for ontologies, follow ODK best practice and ensure ontologies are comprehensively axiomatized to allow for reasoner-based checking +* jupyter notebooks are good for documentation, dashboards, and analysis, but ensure that core logic is separated out and has unit tests +* CLIs, APIs, and MCPs should be shims on top of core logic, and should have their own tests +* Every library should have a fully featured CLI. typer is favored, but click is also good. + +## Dependency management + +* `uv add` to add new dependencies (or `uv add --dev` or similar for dev dependencies) +* libraries should allow somewhat relaxed dependencies to avoid diamond dependency problems. applications and infra can pin more tightly. + +## Git and GitHub Practices + +* always work on branches, commit early and often, make PRs early +* in general, ne PR = one issue (avoid mixing orthogonal concerns). Always reference issues in commits/PR messages +* use `gh` on command line for operations like finding issues, creating PRs +* all the group copier templates include extensive github actions for ensuring PRs are high quality +* github repo should have adequate metadata, links to docs, tags + +## Documentation + +* Follow [Diátaxis framework](https://diataxis.fr/): tutorial, how-to, reference, explanation +* Use examples extensively - examples can double as tests +* frameworks: mkdocs is generally favored due to simplicity but sphinx is ok for older projects +* Every project must have a comprehensive up to date README.md (or the README.md can point to site generated from mkdocs) +