3.6 KiB
Contributing to SkillHub
Scope
SkillHub is a self-hosted registry for agent skills. Contributions should
preserve the existing architecture and product direction documented in
docs/.
AI coding agents working in this repository should follow the rules in
AGENTS.md, which routes to the engineering conventions in
.trellis/spec/index.md. These documents can be read
without installing Trellis or any engineering Skill. Architecture and business
design remain in docs/; execution tools and task records remain local.
Before You Start
- Read
README.mdfor local development commands. - Check the relevant design docs before changing behavior.
- Open an issue for non-trivial changes before sending a large pull request.
Development Setup
Prerequisites:
- Docker and Docker Compose
- Java 21
- Node.js and
pnpm
Start the local stack:
make dev-all
Useful commands:
make test
make typecheck-web
make build-web
make generate-api
./scripts/check-openapi-generated.sh
./scripts/smoke-test.sh
Stop the stack:
make dev-all-down
Change Guidelines
- Keep changes focused. Avoid mixing refactors with behavior changes.
- Follow existing module boundaries across
server/,web/, anddocs/. - Add or update tests when behavior changes.
- Update docs when APIs, auth flows, deployment, or operator workflows change.
- Regenerate and commit
web/src/api/generated/schema.d.tswhen backend OpenAPI contracts change. - Prefer backward-compatible changes unless the issue explicitly allows a break.
Pull Requests
Before opening a pull request, make sure:
- The branch is rebased or merged cleanly from the target branch.
- Relevant backend tests pass.
- Frontend checks follow the change-impact matrix. Changes limited to existing translation display text use its narrow exception; frontend behavior or tooling changes require the applicable typecheck/build checks. This does not waive required CI checks or failures in relevant existing tests.
make generate-apior./scripts/check-openapi-generated.shhas been run when backend API contracts changed.- Smoke coverage is updated when operator-facing workflows change.
- The pull request description explains motivation, scope, and rollout impact.
- Every commit is signed off and the CLA is signed (see below).
Commit Style
Conventional-style subjects are preferred, for example:
feat(auth): add local account loginfix(ops): align smoke test with csrf flowdocs(deploy): clarify runtime image usage
Sign-off and CLA
Two checks must pass before a pull request can be merged:
- DCO: every commit needs a
Signed-off-bytrailer that matches the commit author, certifying the Developer Certificate of Origin. Usegit commit -swhen committing. To sign off commits you already pushed, rungit commit --amend -s --no-editfor the last commit, orgit rebase --signoff <base>for several, thengit push --force-with-lease. - CLA: sign the Contributor License Agreement once through the
license/clalink that the CLA assistant posts on your first pull request.
Both are your own attestations, so maintainers cannot complete them for you. Workflow runs on a first-time contributor's pull request also wait for a maintainer to approve them; that pending state is not a test failure.
Reporting Security Issues
Do not open public issues for suspected security vulnerabilities.
Use GitHub Security Advisories or your internal security process to report them privately to the maintainers.