Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
77 lines (50 loc) · 4.31 KB

CONTRIBUTING.md

File metadata and controls

77 lines (50 loc) · 4.31 KB
Raw

Contributing

Two kinds of skills

Skills in this repo come in two flavours:

  1. Externally-authored — the skill is authored in another Checkly repo and mirrored here automatically. Listed in skills.config.ts. Do not edit these files in this repo — the entire skills/<name>/ directory is wiped and rewritten on every sync, so your changes will be overwritten. Open a PR against the source repo instead.
  2. Plugin-native — the skill is authored here directly. Anything under skills/<name>/ that is not listed in skills.config.ts falls into this bucket.

For example, the checkly skill is externally-authored; it lives at checkly/checkly-cli.

Heads up: in checkly-cli, the skills/ directory at the repo root is itself generated at prepare time from packages/cli/dist/ai-context/public-skills/. The package source is the ultimate source of truth, but the committed skills/<name>/ directory is what we pull from — that's what end users see.

Adding an externally-authored skill

  1. Add an entry to the skills array in skills.config.ts: 
    {
  name: "<skill-name>",
  source: {
    repo: "<owner>/<repo>",
    path: "<path/to/skill/dir>",
    ref: "<tag-branch-or-sha>",
  },
}
    The sync mirrors the entire source.path directory — every file under it, including nested directories like references/. There is no per-file list to maintain; files added or removed upstream flow through on the next sync. ref is required: point it at a branch (e.g. main) to track the latest, or a tag/SHA to pin a fixed version.
  2. Run npm run sync to pull the files locally.
  3. Commit skills.config.ts and skills/<skill-name>/ together.

Adding a plugin-native skill

  1. Create skills/<skill-name>/SKILL.md with valid frontmatter (at minimum name and description).
  2. Add any references it needs in the same directory.
  3. Commit. No skills.config.ts entry needed.

Adding an agent or command

These are listed explicitly in .claude-plugin/plugin.json (Claude Code requires file arrays). Cursor and the generic plugin discover them by convention from agents/ and commands/ at the repo root.

To add one:

  1. Drop the file under agents/<name>.md or commands/<name>.md.
  2. Add the path to the corresponding array in .claude-plugin/plugin.json.

How syncing works

scripts/sync.ts reads skills.config.ts and, for each skill, lists every file under source.path at source.ref via the GitHub git-trees API, then fetches each file from raw.githubusercontent.com. It wipes and rewrites skills/<name>/ so files removed upstream are removed here too. There is no transform — what's upstream lands here verbatim. If the git tree comes back truncated (a very large repo), the sync fails loudly rather than mirror an incomplete skill.

Set GITHUB_TOKEN in the environment to authenticate the git-trees calls and avoid the low anonymous rate limit. CI passes the Actions token automatically; locally it is only needed if you hit the limit.

To change the ref a synced skill tracks, edit its source.ref in skills.config.ts and run:

npm run sync

The sync also runs in CI via .github/workflows/sync.yml, on a daily schedule plus manual workflow_dispatch. The workflow runs npm run sync against whatever refs are pinned in skills.config.ts and commits any changes directly to main. CI does not change the refs — that's a manual edit to skills.config.ts.

Git hooks

simple-git-hooks installs two hooks, wired up automatically by the postinstall script the first time you run npm install:

  • pre-commit runs npm run lint, npm run format:check, and npm run typecheck.
  • commit-msg runs commitlint against the Conventional Commits spec (header capped at 100 chars). See commitlint.config.js.

If the pre-commit hook fails on format:check, run npm run format and re-stage. To bypass the hooks for a single commit (rarely needed), set SKIP_SIMPLE_GIT_HOOKS=1.

Version bumping

Each of the three plugin manifests carries its own version field:

  • .claude-plugin/plugin.json
  • .cursor-plugin/plugin.json
  • .plugin/plugin.json

Keep them in sync with the version in package.json when cutting a release.