Claude Skill

open-sourcing

This skill should be used when the user asks to "open source this project", "prepare this repository for public release", "make this repo public", "check open-source readiness", "choose a license for this project", or "set up release automation" ahead of a public launch. Provides

LLM Mart · 0 points · 7 views 0 listing impressions 0 install-command copies
Virus-scanned Reviewed automatically before listing.

Full trust report

Download trailofbits-skills-plugins_open-sourcing_skills_open-sourcing-321ccfe.zip · 18 KB
trailofbits/skills 7234 616 forks CC-BY-SA-4.0 Updated 9h ago
Part of trailofbits/skills — 100 skills

Install

skills CLI npx skills add https://github.com/trailofbits/skills/tree/main/plugins/open-sourcing/skills/open-sourcing
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install trailofbits-skills@llmmart
Git git clone https://github.com/trailofbits/skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole trailofbits/skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Open-Sourcing a Repository

Prepare a repository for public release so that an outsider with no prior context can build, use, and contribute to it — and so that nothing sensitive ships with it. Work through the steps in order; the secrets audit comes first because its outcome (keeping vs. recreating the repository) affects everything after it.

When to Use

  • Making a private repository public
  • Auditing an existing public repository for release quality ("make it official")
  • Choosing a license for a project
  • Setting up packaging, versioning, or release automation ahead of a public launch

When NOT to Use

  • Routine development on an already-released project (no release event)
  • Auditing third-party code for vulnerabilities (use a security-review skill)
  • Publishing a package from a repository that will stay private — only the release-management steps apply; skip the rest

Workflow

Step 1: Detect the organization profile

bash {baseDir}/scripts/detect_org.sh

The script inspects git remotes and recent committer emails, and prints a profile name. If it prints trailofbits, read references/trailofbits.md now and apply its license policy, publishing accounts, and process notes throughout the remaining steps. If it prints generic, proceed with the generic guidance alone. If the user says the detection is wrong, trust the user.

Step 2: Audit for secrets — before anything else

A repository that has ever contained secrets (API keys, credentials, client data) should not be flipped public. History rewriting is error-prone and does not reach forks, caches, or CI artifacts. The reliable fix is a fresh repository: copy the current tree over, commit, and archive the old repository privately.

  1. Ask whether the project ever handled secrets or client-confidential material. For a security consultancy's tooling, also ask whether test fixtures or example data came from client engagements.
  2. Scan the full history with a dedicated tool if available — gitleaks git . or trufflehog git file://. — rather than eyeballing.
  3. Check beyond the git tree: GitHub Actions logs and artifacts, old releases, issue and PR history, and the repository wiki all become public with the repository.
  4. After going public, enable GitHub secret scanning and push protection in the repository settings.

Reject these rationalizations — this is the one step that cannot be fixed after publication:

  • "The key was revoked, so the history is fine." Revoked credentials still leak infrastructure names, internal URLs, and patterns attackers use for targeting.
  • "We'll rewrite history with git-filter-repo." Rewrites miss forks, clones, caches, and CI artifacts; the fresh-repository approach does not.
  • "It's only test data." Fixtures derived from client engagements or production systems are confidential regardless of how they are labeled.

Step 3: Run the readiness check

bash {baseDir}/scripts/check_readiness.sh

The script prints a checklist of presence indicators (README, LICENSE, CONTRIBUTING, SECURITY.md, CI, tests, semver tags, ...) and warns about tracked files that commonly contain secrets. Treat unchecked items as discussion prompts, not hard failures — a research prototype does not need everything a flagship library needs. Walk through the gaps with the user and fix the ones that matter for this project.

Step 4: Documentation

The README is the project's front door. Confirm it explains:

  • What the project is and what problem it solves (first paragraph)
  • How to install it — package manager, container image, or build from source; a fresh-clone build must work using only what is in the repository
  • How to use it — at least one concrete, copy-pasteable example
  • How to contribute — inline or via CONTRIBUTING.md
  • The license — a short section naming it

Also add:

  • SECURITY.md with vulnerability-reporting instructions (a contact address or GitHub private vulnerability reporting). For security tooling this is table stakes.
  • API documentation, built and hosted (GitHub Pages via CI is the usual route), linked from the README and the repository website field. See the language references below for per-ecosystem doc tooling.
  • A code of conduct if the project expects outside contributors.

Step 5: Licensing

No license means not open source, regardless of visibility. Read references/licensing.md for selection criteria and mechanics. The short version:

  1. Apply the organization's policy if one was detected in Step 1.
  2. Otherwise: Apache 2.0 as the permissive default, AGPLv3 when private modification by competitors is a real concern, Creative Commons for non-code artifacts.
  3. Add the LICENSE file, set SPDX identifiers in package metadata, state the license in the README, and verify all three agree.

Step 6: Tests and CI

  • Confirm the test suite exists and passes; a public repository with a failing default branch signals abandonment.
  • Ensure CI runs the tests on every PR, across the supported language-version and platform matrix.
  • Enforce formatting and linting in CI (per-language tooling in the references below), so style debates never reach review.
  • Respect existing tooling. Do not replace a working formatter, linter, or type checker as part of open-sourcing. If it lags the current generation (the language references name the current tools), warn the maintainer and let them decide; only when a category is missing entirely — no type checker, no formatter — add the current default.
  • Consider a coverage gate that fails CI when coverage drops.
  • Harden the workflows themselves before they become public attack surface:
    • Pin third-party actions to full commit SHAs; enable Dependabot for github-actions so pins stay current.
    • Set least-privilege permissions: blocks (start from permissions: {}).
    • Audit with zizmor .github/workflows/ and lint with actionlint.

Step 7: Repository settings

  • Branch protection on the default branch: no force pushes, PRs required. Prefer rulesets for new repositories; classic branch protection remains supported.
  • Merge protection: required status checks so PRs cannot merge with failing tests.
  • Dependabot or Renovate for dependency and Actions updates. Group updates to cut PR noise, and set a cooldown window (e.g., 7 days) so freshly published — and occasionally hijacked — versions age before adoption.
  • .editorconfig so contributors' editors agree on whitespace basics.
  • Labels: create them as soon as more than one issue or PR needs one; prefixes for facets scale well (C: component, P: platform). See blight's labels for a worked example.

Step 8: Releases and versioning

  • Tag every release vX.Y.Z, following semver; use -rc.N / -pre.N suffixes for release candidates and prereleases.
  • Make releases CI-driven: pushing a tag (or publishing a GitHub Release) triggers build, packaging, and upload with no manual steps. A release should be git tag vX.Y.Z && git push origin vX.Y.Z.
  • Publish packages under an organization-owned account, not a personal one, and use trusted publishing (OIDC) instead of long-lived tokens wherever the index supports it.

Step 9: Language-specific practices

Identify the project's languages from its marker files and read the matching reference for packaging, publishing, and quality tooling:

Marker file Reference
pyproject.toml, setup.py references/python.md — defers to the modern-python skill for tooling
CMakeLists.txt, Makefile (C/C++) references/c-cpp.md
Cargo.toml references/rust.md
go.mod references/go.md
package.json references/javascript.md
Gemfile, *.gemspec references/ruby.md

For other ecosystems, apply the cross-cutting principles: reproducible builds from a fresh clone, CI-driven releases, trusted publishing or organization-owned accounts, and license metadata in the package manifest.

Final Review

Before the visibility switch is flipped, verify from an outsider's perspective:

  1. Clone into a clean directory and follow the README's build instructions verbatim — do they work with no tribal knowledge?
  2. Re-run {baseDir}/scripts/check_readiness.sh and confirm the remaining gaps are deliberate choices, stated to the user.
  3. Confirm the secrets audit (Step 2) actually happened; it is the one step that cannot be fixed after publication.

Making the repository public is then a repository-settings change. Pair the release with an announcement where the organization has a process for one.

Additional Resources

Reference Files

Scripts

  • scripts/detect_org.sh — prints the organization profile (trailofbits or generic) from git remotes and committer emails
  • scripts/check_readiness.sh — prints presence indicators for release-readiness files and flags tracked files that commonly hold secrets
Files (skills)
  • references
    • c-cpp.md 2.4 KB
      # C/C++ Release Practices
      
      ## Build system
      
      Use modern CMake. For new projects,
      [cmake-init](https://github.com/friendlyanon/cmake-init) generates a
      well-structured project with presets, warnings, and packaging support:
      
      ```sh
      git init && cmake-init <project-name>
      ```
      
      Plain GNU Make is acceptable for small projects; anything intended for
      downstream packaging (vcpkg, distro packages) should use CMake.
      
      ## Language standard and portability
      
      - Use **C++17 as the minimum** for new code; prefer C++20 or newer where the
        supported toolchains allow.
      - Write standard C++, not compiler-specific dialects. Limit extensions to
        those with broad support across Clang, GCC, and (if targeted) MSVC, and
        build in CI with more than one compiler to keep the code honest.
      
      ## Testing and quality engineering
      
      - **Unit tests:** [GoogleTest](https://github.com/google/googletest), run
        through CTest for build-system integration.
      - **Sanitizers in CI:** build and run the test suite under ASan and UBSan at
        minimum; add TSan for concurrent code. Sanitizer CI jobs catch memory bugs
        reviewers miss.
      - **Valgrind** remains useful for leak detection where sanitizers cannot run.
      - **Fuzzing:** for code that parses untrusted input, add libFuzzer or AFL++
        harnesses, and consider [OSS-Fuzz](https://github.com/google/oss-fuzz)
        enrollment once public.
      - Enable a strict warning baseline (`-Wall -Wextra`, warnings-as-errors in
        CI).
      
      ## Formatting and linting
      
      Use the latest stable **clang-format** and **clang-tidy**, each enforced in
      CI. Defaults are fine; a repository may commit its own `.clang-format` and
      `.clang-tidy` configurations. Examples:
      [pe-parse](https://github.com/trailofbits/pe-parse/blob/master/.clang-format),
      [winchecksec](https://github.com/trailofbits/winchecksec/blob/master/.clang-format).
      
      ## Documentation
      
      [Doxygen](https://www.doxygen.nl/) for API documentation, published to GitHub
      Pages from CI.
      
      ## Packaging and distribution
      
      - **vcpkg** is the most common route for distributing C++ libraries; Conan is
        a reasonable alternative if the audience already uses it.
      - For tools, attach prebuilt binaries to GitHub Releases from CI, and
        consider a container image. Keep images small: multi-stage builds with a
        minimal base (alpine, distroless).
      - See [pe-parse's release workflow](https://github.com/trailofbits/pe-parse/blob/master/.github/workflows/release.yml)
        for an example of CI-managed release packaging.
      
    • go.md 2.4 KB
      # Go Release Practices
      
      Use the standard `go` toolchain for everything.
      
      ## Module setup
      
      - Initialize with the canonical repository path:
        `go mod init github.com/<org>/<project>`. The module path is the import
        path, so set it correctly before anyone depends on the project.
      - Set the `go` directive in `go.mod` to the latest stable release for
        greenfield code.
      
      ## Project layout
      
      - `cmd/<appname>/main.go` for each binary entry point.
      - `internal/` for packages that must not be imported by other modules — use
        it liberally; exporting a package is an API commitment.
      - Do not create a `pkg/` directory reflexively; the
        [official module layout guidance](https://go.dev/doc/modules/layout)
        recommends putting importable packages at the repository root unless there
        is a concrete conflict.
      - Keep packages focused on a single responsibility, handle every error, and
        reserve `panic` for unrecoverable states. Follow
        [Effective Go](https://go.dev/doc/effective_go) and the
        [Go style guide](https://google.github.io/styleguide/go/).
      
      ## Testing, formatting, and linting
      
      - `go test ./...` in CI, with `-race` enabled — the race detector is cheap
        insurance for any code with goroutines.
      - `gofmt` (or `go fmt`) before committing; enforce in CI.
      - [golangci-lint](https://golangci-lint.run/) with a committed configuration.
      - [govulncheck](https://go.dev/blog/vuln) in CI to flag known-vulnerable
        dependencies actually reachable from the code.
      
      ## Documentation
      
      Write doc comments for every exported identifier — complete sentences
      beginning with the identifier name. [pkg.go.dev](https://pkg.go.dev/) renders
      them automatically once the module is public and tagged.
      
      ## Publishing and releases
      
      - There is no central upload step: pushing a semver tag (`vX.Y.Z`) to the
        public repository *is* publishing. The module proxy and pkg.go.dev pick it
        up automatically. See [developing modules](https://go.dev/doc/modules/developing).
      - Because tags are immutable once fetched through the module proxy, never
        retag; publish a new patch version instead.
      - For binaries, use [goreleaser](https://goreleaser.com/) to build
        multi-platform artifacts, generate release notes from commits, and attach
        everything to the GitHub Release on each tag. Consider GitHub
        [artifact attestations](https://docs.github.com/en/actions/security-for-github-actions/using-artifact-attestations)
        for provenance on released binaries.
      
    • javascript.md 1.5 KB
      # JavaScript/TypeScript Release Practices
      
      ## Supported versions
      
      Support the active and maintenance Node.js LTS lines, and declare the floor
      in `engines.node`. Dropping an EOL Node version is routine maintenance.
      
      ## Package metadata
      
      - Set `license` (SPDX identifier), `repository`, and `engines` in
        `package.json`; registries and tooling surface these directly.
      - Commit the lockfile (`package-lock.json`, `pnpm-lock.yaml`, or
        `yarn.lock`) so fresh clones build reproducibly.
      - Publish under an npm **organization scope** (`@org/package`) rather than
        a personal account so ownership survives maintainer turnover.
      
      ## Formatting, linting, and type checking
      
      Keep an existing ESLint + Prettier or Biome setup; if none exists, add
      Biome (a single tool) or ESLint + Prettier, and enforce them in CI. For
      TypeScript, run `tsc --noEmit` in CI even when a bundler performs the
      builds — bundlers typically skip type checking.
      
      ## Documentation
      
      [TypeDoc](https://typedoc.org/) generates API documentation from TypeScript
      sources; publish it to GitHub Pages from CI and link it from the README.
      
      ## Publishing to npm
      
      - Use npm [trusted publishing](https://docs.npmjs.com/trusted-publishers/)
        (OIDC from GitHub Actions or GitLab CI, generally available since July
        2025) instead of long-lived tokens.
      - Under trusted publishing, the npm CLI publishes **provenance attestations
        by default** — no `--provenance` flag needed.
      - Run `npm audit` (or the equivalent for pnpm/yarn) in CI to flag
        dependencies with known advisories.
      
    • licensing.md 4.3 KB
      # Choosing and Applying an Open-Source License
      
      A repository is not open source until it has a license. Without one, default
      copyright applies and nobody can legally use, modify, or redistribute the code
      regardless of it being publicly visible.
      
      ## Decision criteria
      
      Choose a license based on the answers to these questions, in order:
      
      1. **Does the organization have a license policy?** Apply it. If an
         organization profile was loaded in Step 1 of the workflow, its policy
         takes precedence over the generic guidance below.
      2. **Is this software at all?** Datasets, detection rulesets, documentation,
         and publications are often better served by Creative Commons licenses than
         software licenses.
      3. **Would competitors gain a significant advantage by modifying this work
         without contributing changes back?** If yes, a network-copyleft license
         (AGPLv3) protects against service providers privatizing improvements.
      4. **Do the project's dependencies constrain the choice?** A project that
         statically links GPL code cannot be released under a permissive license.
         Check dependency licenses before deciding.
      5. **What does the ecosystem expect?** Libraries intended for broad adoption
         (especially ones businesses must get legal approval to use) see far more
         uptake under permissive licenses.
      
      ## Common choices
      
      | License | Type | Choose when |
      |---------|------|-------------|
      | [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0) | Permissive | Default for libraries and tools; includes an explicit patent grant, which MIT lacks |
      | [MIT](https://opensource.org/license/mit) | Permissive | Maximum simplicity; ecosystem convention (e.g., much of npm) |
      | [AGPLv3](https://www.gnu.org/licenses/agpl-3.0.en.html) | Network copyleft | The project offers competitors a significant advantage if modified privately, including as a hosted service |
      | [GPLv3](https://www.gnu.org/licenses/gpl-3.0.en.html) | Copyleft | Copyleft desired but the network-use clause is not needed |
      | [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) | Share-alike (non-software) | Publications and documentation; allows commercial use with attribution |
      | [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/) | Non-commercial (non-software) | Rulesets or datasets where commercial use should require a separate agreement |
      
      Avoid novel, custom, or "source-available" licenses (BSL, custom
      non-competes) unless legal counsel is driving that decision; they create
      adoption friction and are not open source under the
      [OSD](https://opensource.org/osd).
      
      ## Applying the license
      
      Choosing is half the job. Then:
      
      - **Add a `LICENSE` file** at the repository root containing the full license
        text. For Apache 2.0, fill in the copyright notice; for CC licenses, link
        the legal code and state the license clearly in the README.
      - **Set the license in package metadata** using SPDX identifiers so package
        indexes display it correctly:
        - Python: `license = "Apache-2.0"` (SPDX expression, PEP 639) in `pyproject.toml`
        - Rust: `license = "Apache-2.0"` in `Cargo.toml`
        - Ruby: `spec.license = "Apache-2.0"` in the gemspec
        - Node: `"license": "Apache-2.0"` in `package.json`
      - **State the license in the README**, typically a short section at the end.
      - **Keep all of these consistent.** A `LICENSE` file that says AGPLv3 with
        `pyproject.toml` metadata that says MIT is a real (and common) bug.
      
      ## Copyright lines
      
      A copyright line uses the current year only; open-ended ranges
      ("2020-present") add nothing legally:
      
      ```
      Copyright (c) 2026 Example Org <opensource@example.org>
      ```
      
      ## Forks and adopted projects
      
      When taking over maintenance of an existing open-source project:
      
      - **Keep the existing license** and add a copyright line for the new
        maintainer below the original:
      
        ```
        Copyright (c) 2019 John Q. Public <john@example.com>
        Copyright (c) 2026 Example Org <opensource@example.org>
        ```
      
      - **Do not relicense** unless every copyright holder agrees or the original
        license explicitly permits it. Permissively licensed projects may be
        *re-released* under a stronger license for new contributions, but the
        original code remains under its original terms and the original notices
        must be preserved.
      
      When in doubt about any licensing question, consult whoever handles legal or
      open-source policy for the organization before publishing.
      
    • python.md 5 KB
      # Python Release Practices
      
      For project scaffolding, dependency management (uv), formatting/linting
      (ruff), and type checking (ty), use the **modern-python skill** from this
      marketplace — do not duplicate its guidance. If that skill is not installed,
      apply the toolchain directly with standard configurations: uv for
      dependencies and builds, `ruff format`/`ruff check` for style, ty for type
      checking (note: ty is pre-1.0 with breaking changes between releases — pin
      a version rather than an open floor), pytest for tests.
      
      Per the tooling principle in SKILL.md Step 6: leave an existing working
      toolchain in place, warning the maintainer about the current equivalents
      (black → `ruff format`, mypy → ty, pre-commit → prek); adopt the modern
      tools only for categories the project lacks entirely.
      
      This file covers only what the modern-python skill does not:
      supported-version policy, documentation, and publishing.
      
      ## Supported Python versions
      
      - Greenfield projects: target the latest stable Python.
      - If broader compatibility is needed, use the **N-3 rule**: support no more
        than three minor versions behind current (e.g., with 3.14 current, the
        floor is 3.11). Declare the floor with `requires-python` in
        `pyproject.toml` and test the full range in CI.
      
      ## Documentation
      
      - **API docs:** [pdoc](https://github.com/mitmproxy/pdoc) — note *pdoc*, not
        *pdoc3*, which is a hostile fork.
      - **Full documentation sites:** [Sphinx](https://www.sphinx-doc.org/) with the
        [furo](https://github.com/pradyunsg/furo) theme, or
        [MkDocs with Material](https://squidfunk.github.io/mkdocs-material/).
      - Deploy to GitHub Pages from CI
        ([actions/deploy-pages](https://github.com/actions/deploy-pages) or
        [actions-gh-pages](https://github.com/peaceiris/actions-gh-pages)) and link
        the site from the README and the repository's website field.
      
      ## Packaging
      
      `pyproject.toml` is the only packaging file needed unless building native
      CPython extensions (`setup.py` for C, maturin/`Cargo.toml` for Rust). Build
      distributions with `uv build`.
      
      ## Publishing to PyPI
      
      Use [trusted publishing](https://docs.pypi.org/trusted-publishers/) — an OIDC
      trust relationship between PyPI and the GitHub Actions workflow — instead of
      API tokens. Configure it on PyPI under the project's publishing settings,
      restricted to a dedicated `pypi` environment in the repository.
      
      Example release workflow. Actions are pinned to full commit SHAs per the CI
      hardening notes in SKILL.md; the SHAs below correspond to the tags in the
      trailing comments and will drift — resolve current ones before use, and let
      Dependabot keep them updated:
      
      ```yaml
      name: release
      
      on:
        release:
          types: [published]
      
      permissions: {}
      
      jobs:
        build:
          name: Build distributions
          runs-on: ubuntu-latest
          steps:
            - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
              with:
                persist-credentials: false
      
            - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
      
            - name: Build distributions
              run: uv build
      
            - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
              with:
                name: distributions
                path: dist/
      
        provenance:
          name: Generate SLSA provenance
          runs-on: ubuntu-latest
          needs: [build]
          permissions:
            id-token: write
            attestations: write
          steps:
            - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
              with:
                name: distributions
                path: dist/
      
            - uses: actions/attest-build-provenance@0f67c3f4856b2e3261c31976d6725780e5e4c373 # v4.1.1
              with:
                subject-path: dist/*
      
        publish:
          name: Publish to PyPI
          runs-on: ubuntu-latest
          needs: [build, provenance]
          environment:
            name: pypi
          permissions:
            id-token: write  # required for trusted publishing and attestations
          steps:
            - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
              with:
                name: distributions
                path: dist/
      
            - uses: pypa/gh-action-pypi-publish@ba38be9e461d3875417946c167d0b5f3d385a247 # v1.14.1
              with:
                attestations: true
      ```
      
      `attestations: true` generates [PEP 740](https://peps.python.org/pep-0740/)
      publish attestations — the default since gh-action-pypi-publish v1.11, kept
      explicit here for clarity — and the provenance job attaches
      [SLSA build provenance](https://docs.github.com/en/actions/security-for-github-actions/using-artifact-attestations)
      to the built distributions.
      
      ## Quality extras worth adding before release
      
      - Property-based tests with
        [Hypothesis](https://hypothesis.readthedocs.io/) for parsing- or
        algorithm-heavy code (see the property-based-testing skill in this
        marketplace).
      - Docstring coverage enforcement with
        [interrogate](https://interrogate.readthedocs.io/) or ruff's `D` rules so
        public APIs stay documented as the project grows.
      - Dependency auditing in CI with `uv audit` (currently in preview) or
        [pip-audit](https://github.com/pypa/pip-audit).
      
    • ruby.md 1.2 KB
      # Ruby Release Practices
      
      ## Supported versions
      
      Ruby releases a minor version yearly and the community supports roughly the
      last three. Support those three; going lower buys little and costs CI matrix
      time. Declare the floor with `required_ruby_version` in the gemspec.
      
      ## Dependencies
      
      Use [Bundler](https://bundler.io/). Configure it to install into a vendor
      directory rather than the user's global gem store, and keep that directory
      out of git:
      
      ```sh
      bundle config set --local path vendor/bundle
      echo vendor/bundle/ >> .gitignore
      ```
      
      ## Formatting and linting
      
      Use [RuboCop](https://github.com/rubocop/rubocop). The default cops are
      reasonable; projects commonly relax the metrics cops (method length,
      complexity) in `.rubocop.yml` rather than fighting them. Enforce in CI.
      
      ## Publishing to RubyGems
      
      - Publish to [RubyGems.org](https://rubygems.org/).
      - Use RubyGems [trusted publishing](https://guides.rubygems.org/trusted-publishing/)
        from GitHub Actions instead of API keys.
      - Add the organization's shared account as a gem **co-owner**
        (`gem owner <gem> --add <email>`) so the package survives maintainer
        turnover.
      - Set `spec.license` (SPDX identifier) and `spec.metadata` links
        (`source_code_uri`, `changelog_uri`) in the gemspec.
      
    • rust.md 2.3 KB
      # Rust Release Practices
      
      Use `cargo` for everything: building, testing (`cargo test`), formatting
      (`cargo fmt`), linting (`cargo clippy`), and documentation (`cargo doc`).
      
      ## Toolchain and edition
      
      - Prefer the latest stable compiler and the latest edition for new code.
      - If older-compiler support matters, declare it explicitly with
        `package.rust-version` in `Cargo.toml` and test that version in CI.
      
      ## Crate-level lints
      
      Add these to `lib.rs`/`main.rs` before release:
      
      ```rust
      #![forbid(unsafe_code)]
      #![deny(missing_docs)]
      #![deny(rustdoc::broken_intra_doc_links)]
      ```
      
      - `forbid(unsafe_code)` prevents direct `unsafe` (transitive uses through
        dependencies are still allowed). Omit only for crates that genuinely need
        `unsafe`, and isolate those blocks with `// SAFETY:` comments.
      - `deny(missing_docs)` fails the build when a public API lacks a rustdoc
        comment.
      - Optionally forbid explicit panics in library code with
        `#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic)]` — but
        note panics are often appropriate; apply this only where callers need
        `Result`-based error handling throughout.
      
      ## Supply-chain checks
      
      - [`cargo audit`](https://github.com/rustsec/rustsec) in CI flags
        dependencies with known advisories.
      - [`cargo deny`](https://github.com/EmbarkStudios/cargo-deny) additionally
        enforces license and source policies on the dependency tree — useful for
        catching a copyleft dependency slipping into a permissively licensed
        project.
      
      ## Publishing to crates.io
      
      - Use crates.io [trusted publishing](https://crates.io/docs/trusted-publishing)
        (OIDC from GitHub Actions) instead of long-lived API tokens.
      - [`cargo release`](https://github.com/crate-ci/cargo-release) manages
        version bumps, tagging, and pushing. A common configuration in
        `Cargo.toml`, with the actual publish performed by CI:
      
      ```toml
      [package.metadata.release]
      publish = false # handled by GitHub Actions
      push = true
      ```
      
      - Set `license` (SPDX expression), `description`, `repository`, and
        `documentation` in `Cargo.toml`; crates.io and docs.rs surface these
        directly. docs.rs builds documentation automatically on publish.
      
      ## Binary distribution
      
      For tools with end-user binaries, use
      [cargo-dist](https://github.com/axodotdev/cargo-dist) or
      [goreleaser](https://goreleaser.com/) to build multi-platform release
      artifacts and installers from CI on each tag.
      
    • trailofbits.md 3.6 KB
      # Trail of Bits Profile
      
      Apply this guidance **in addition to** the generic workflow when
      `scripts/detect_org.sh` prints `trailofbits`. Everything in this file is
      public information; internal process details (credentials, announcement
      workflow, release sign-off) live in Trail of Bits' internal documentation,
      which the maintainer should consult directly.
      
      ## License policy
      
      - **Default to [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0)**
        for nearly all projects.
      - **Use [AGPLv3](https://www.gnu.org/licenses/agpl-3.0.en.html)** when the
        project would offer a significant advantage to competitors who modify it
        without contributing changes back.
      - **Use Creative Commons for non-code work:**
        - [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/)
          for rulesets (e.g., [semgrep-rules](https://github.com/trailofbits/semgrep-rules))
        - [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) for
          publications and informational material (e.g.,
          [publications](https://github.com/trailofbits/publications))
      - When in doubt, confirm with the project manager or an existing open-source
        maintainer before publishing.
      
      Copyright line convention (current year only, no ranges):
      
      ```
      Copyright (c) 2026 Trail of Bits <opensource@trailofbits.com>
      ```
      
      For forks and adopted projects, add this line under the existing copyright
      rather than relicensing, unless the changes involve the company's competitive
      interests (see the AGPLv3 criterion above).
      
      ## Repository location
      
      Official projects live in the [trailofbits](https://github.com/trailofbits)
      GitHub organization. Related ecosystems use
      [lifting-bits](https://github.com/lifting-bits) (binary lifting) and
      [crytic](https://github.com/crytic) (smart contract tooling). Move personal
      repositories into the appropriate organization before announcing them.
      
      ## Package publishing
      
      Publish under the company's shared accounts so ownership survives individual
      departures:
      
      - **PyPI:** add the [trailofbits organization](https://pypi.org/org/trailofbits/)
        as an owner of the package.
      - **RubyGems:** add the [trailofbits account](https://rubygems.org/profiles/trailofbits)
        as a gem co-owner.
      - Prefer **trusted publishing** (OIDC from GitHub Actions) over long-lived
        API tokens on every index that supports it (PyPI, RubyGems, crates.io).
      
      Account access is handled internally; consult the internal documentation
      rather than creating parallel accounts.
      
      ## Project scaffolding
      
      - **Python:** generate new projects with
        [cookiecutter-python](https://github.com/trailofbits/cookiecutter-python),
        which encodes current company practices: uv, ruff, ty, prek, pdoc,
        SHA-pinned CI audited by zizmor, trusted publishing with SLSA provenance,
        and 100% coverage and docstring-coverage gates. Generated projects also
        ship `AGENTS.md` agent instructions. The `modern-python` skill in this
        marketplace covers the same toolchain.
      - Example repositories for release automation:
        [pe-parse](https://github.com/trailofbits/pe-parse/blob/master/.github/workflows/release.yml)
        (C++/CI-managed packaging) and
        [pip-audit](https://github.com/pypa/pip-audit/blob/main/.github/workflows/release.yml)
        (Python/trusted publishing).
      
      ## Before flipping the repository public
      
      Beyond the generic checklist, Trail of Bits maintainers should:
      
      1. Confirm the license choice with their project manager if it deviates from
         Apache 2.0.
      2. Follow the internal public-release checklist and announcement process
         (blog post, social media) documented internally — public release is often
         paired with an announcement, and coordinating that before the repository
         goes public preserves the option.
      
  • scripts
    • check_readiness.sh 2.4 KB
      #!/usr/bin/env bash
      # Reports release-readiness indicators for the current repository.
      # Informational only: an unchecked item is a discussion prompt, not a
      # hard failure. Run from the repository root.
      # -e is intentionally omitted: check commands are expected to fail.
      set -uo pipefail
      
      exists_any() {
        local f
        for f in "$@"; do
          [ -e "$f" ] && return 0
        done
        return 1
      }
      
      check() {
        local label="$1"
        shift
        if "$@" >/dev/null 2>&1; then
          printf '  [x] %s\n' "$label"
        else
          printf '  [ ] %s\n' "$label"
        fi
      }
      
      has_ci_workflows() {
        exists_any .github/workflows/*.yml .github/workflows/*.yaml
      }
      
      has_dependency_updates() {
        exists_any .github/dependabot.yml .github/dependabot.yaml \
          renovate.json renovate.json5 .github/renovate.json .github/renovate.json5
      }
      
      has_tests() {
        exists_any tests test spec ||
          git ls-files 2>/dev/null | grep -E '(_test\.(go|py|rb)$|\.test\.(ts|js|tsx|jsx)$|_spec\.rb$)' >/dev/null
      }
      
      has_semver_tags() {
        git tag --list 'v[0-9]*' 2>/dev/null | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+' >/dev/null
      }
      
      list_suspicious_files() {
        git ls-files 2>/dev/null |
          grep -iE '(^|/)(\.env(\..+)?|.*\.pem|.*\.p12|.*\.pfx|.*\.keystore|id_(rsa|dsa|ecdsa|ed25519).*|.*credentials.*\.(json|xml|yml|yaml))$' |
          grep -vE '\.(example|sample|template)(\.|$)'
      }
      
      main() {
        if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
          echo "error: not inside a git repository" >&2
          exit 1
        fi
      
        echo "Release-readiness indicators:"
        check "README" exists_any README.md README.rst README.txt README
        check "LICENSE" exists_any LICENSE LICENSE.md LICENSE.txt COPYING COPYING.md
        check "CONTRIBUTING" exists_any CONTRIBUTING.md CONTRIBUTING.rst .github/CONTRIBUTING.md
        check "SECURITY policy" exists_any SECURITY.md .github/SECURITY.md
        check "Code of conduct" exists_any CODE_OF_CONDUCT.md .github/CODE_OF_CONDUCT.md
        check ".gitignore" exists_any .gitignore
        check ".editorconfig" exists_any .editorconfig
        check "CI workflows" has_ci_workflows
        check "Automated dependency updates (Dependabot/Renovate)" has_dependency_updates
        check "Tests" has_tests
        check "Semver release tags (vX.Y.Z)" has_semver_tags
      
        local suspicious
        suspicious=$(list_suspicious_files)
        if [ -n "${suspicious}" ]; then
          echo
          echo "WARNING: tracked files that commonly contain secrets:"
          printf '%s\n' "${suspicious}" | sed 's/^/  - /'
          echo "Review these (and full history) before making the repository public."
        fi
      }
      
      main "$@"
      
    • detect_org.sh 741 B
      #!/usr/bin/env bash
      # Detects whether the current repository belongs to an organization with an
      # additional guidance profile in references/. Prints the profile name
      # ("trailofbits" or "generic") to stdout.
      set -euo pipefail
      
      TOB_ORGS='trailofbits|lifting-bits|crytic'
      
      remote_matches_tob() {
        git remote -v 2>/dev/null | grep -qiE "github\.com[:/](${TOB_ORGS})/"
      }
      
      commits_match_tob() {
        git log --format='%ae%n%ce' -n 200 2>/dev/null | grep '@trailofbits\.com$' >/dev/null
      }
      
      main() {
        if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
          echo "error: not inside a git repository" >&2
          exit 1
        fi
      
        if remote_matches_tob || commits_match_tob; then
          echo "trailofbits"
        else
          echo "generic"
        fi
      }
      
      main "$@"
      
  • SKILL.md 10.2 KB
    ---
    name: open-sourcing
    description: This skill should be used when the user asks to "open source this project", "prepare this repository for public release", "make this repo public", "check open-source readiness", "choose a license for this project", or "set up release automation" ahead of a public launch. Provides a release-readiness workflow covering secrets hygiene, licensing, documentation, CI, and language-specific packaging.
    ---
    
    # Open-Sourcing a Repository
    
    Prepare a repository for public release so that an outsider with no prior
    context can build, use, and contribute to it — and so that nothing sensitive
    ships with it. Work through the steps in order; the secrets audit comes first
    because its outcome (keeping vs. recreating the repository) affects
    everything after it.
    
    ## When to Use
    
    - Making a private repository public
    - Auditing an existing public repository for release quality ("make it
      official")
    - Choosing a license for a project
    - Setting up packaging, versioning, or release automation ahead of a public
      launch
    
    ## When NOT to Use
    
    - Routine development on an already-released project (no release event)
    - Auditing third-party code for vulnerabilities (use a security-review skill)
    - Publishing a package from a repository that will stay private — only the
      release-management steps apply; skip the rest
    
    ## Workflow
    
    ### Step 1: Detect the organization profile
    
    ```sh
    bash {baseDir}/scripts/detect_org.sh
    ```
    
    The script inspects git remotes and recent committer emails, and prints a
    profile name. If it prints `trailofbits`, read
    [references/trailofbits.md](references/trailofbits.md) now and apply its
    license policy, publishing accounts, and process notes throughout the
    remaining steps. If it prints `generic`, proceed with the generic guidance
    alone. If the user says the detection is wrong, trust the user.
    
    ### Step 2: Audit for secrets — before anything else
    
    A repository that has **ever** contained secrets (API keys, credentials,
    client data) should not be flipped public. History rewriting is error-prone
    and does not reach forks, caches, or CI artifacts. The reliable fix is a
    fresh repository: copy the current tree over, commit, and archive the old
    repository privately.
    
    1. Ask whether the project ever handled secrets or client-confidential
       material. For a security consultancy's tooling, also ask whether test
       fixtures or example data came from client engagements.
    2. Scan the full history with a dedicated tool if available —
       `gitleaks git .` or `trufflehog git file://.` — rather than eyeballing.
    3. Check beyond the git tree: GitHub Actions logs and artifacts, old
       releases, issue and PR history, and the repository wiki all become public
       with the repository.
    4. After going public, enable GitHub secret scanning and push protection in
       the repository settings.
    
    Reject these rationalizations — this is the one step that cannot be fixed
    after publication:
    
    - *"The key was revoked, so the history is fine."* Revoked credentials still
      leak infrastructure names, internal URLs, and patterns attackers use for
      targeting.
    - *"We'll rewrite history with git-filter-repo."* Rewrites miss forks,
      clones, caches, and CI artifacts; the fresh-repository approach does not.
    - *"It's only test data."* Fixtures derived from client engagements or
      production systems are confidential regardless of how they are labeled.
    
    ### Step 3: Run the readiness check
    
    ```sh
    bash {baseDir}/scripts/check_readiness.sh
    ```
    
    The script prints a checklist of presence indicators (README, LICENSE,
    CONTRIBUTING, SECURITY.md, CI, tests, semver tags, ...) and warns about
    tracked files that commonly contain secrets. Treat unchecked items as
    discussion prompts, not hard failures — a research prototype does not need
    everything a flagship library needs. Walk through the gaps with the user and
    fix the ones that matter for this project.
    
    ### Step 4: Documentation
    
    The README is the project's front door. Confirm it explains:
    
    - **What the project is** and what problem it solves (first paragraph)
    - **How to install it** — package manager, container image, or build from
      source; a fresh-clone build must work using only what is in the repository
    - **How to use it** — at least one concrete, copy-pasteable example
    - **How to contribute** — inline or via `CONTRIBUTING.md`
    - **The license** — a short section naming it
    
    Also add:
    
    - **`SECURITY.md`** with vulnerability-reporting instructions (a contact
      address or GitHub private vulnerability reporting). For security tooling
      this is table stakes.
    - **API documentation**, built and hosted (GitHub Pages via CI is the usual
      route), linked from the README and the repository website field. See the
      language references below for per-ecosystem doc tooling.
    - A **code of conduct** if the project expects outside contributors.
    
    ### Step 5: Licensing
    
    No license means not open source, regardless of visibility. Read
    [references/licensing.md](references/licensing.md) for selection criteria and
    mechanics. The short version:
    
    1. Apply the organization's policy if one was detected in Step 1.
    2. Otherwise: Apache 2.0 as the permissive default, AGPLv3 when private
       modification by competitors is a real concern, Creative Commons for
       non-code artifacts.
    3. Add the `LICENSE` file, set SPDX identifiers in package metadata, state
       the license in the README, and verify all three agree.
    
    ### Step 6: Tests and CI
    
    - Confirm the test suite exists and passes; a public repository with a
      failing default branch signals abandonment.
    - Ensure CI runs the tests on every PR, across the supported
      language-version and platform matrix.
    - Enforce formatting and linting in CI (per-language tooling in the
      references below), so style debates never reach review.
    - **Respect existing tooling.** Do not replace a working formatter, linter,
      or type checker as part of open-sourcing. If it lags the current
      generation (the language references name the current tools), warn the
      maintainer and let them decide; only when a category is missing entirely —
      no type checker, no formatter — add the current default.
    - Consider a coverage gate that fails CI when coverage drops.
    - Harden the workflows themselves before they become public attack surface:
      - Pin third-party actions to full commit SHAs; enable Dependabot for
        `github-actions` so pins stay current.
      - Set least-privilege `permissions:` blocks (start from `permissions: {}`).
      - Audit with `zizmor .github/workflows/` and lint with `actionlint`.
    
    ### Step 7: Repository settings
    
    - **Branch protection** on the default branch: no force pushes, PRs
      required. Prefer rulesets for new repositories; classic branch protection
      remains supported.
    - **Merge protection**: required status checks so PRs cannot merge with
      failing tests.
    - **Dependabot or Renovate** for dependency and Actions updates. Group
      updates to cut PR noise, and set a cooldown window (e.g., 7 days) so
      freshly published — and occasionally hijacked — versions age before
      adoption.
    - **`.editorconfig`** so contributors' editors agree on whitespace basics.
    - **Labels**: create them as soon as more than one issue or PR needs one;
      prefixes for facets scale well (`C:` component, `P:` platform). See
      [blight's labels](https://github.com/trailofbits/blight/labels) for a
      worked example.
    
    ### Step 8: Releases and versioning
    
    - Tag every release `vX.Y.Z`, following [semver](https://semver.org/); use
      `-rc.N` / `-pre.N` suffixes for release candidates and prereleases.
    - Make releases CI-driven: pushing a tag (or publishing a GitHub Release)
      triggers build, packaging, and upload with no manual steps. A release
      should be `git tag vX.Y.Z && git push origin vX.Y.Z`.
    - Publish packages under an organization-owned account, not a personal one,
      and use **trusted publishing** (OIDC) instead of long-lived tokens wherever
      the index supports it.
    
    ### Step 9: Language-specific practices
    
    Identify the project's languages from its marker files and read the matching
    reference for packaging, publishing, and quality tooling:
    
    | Marker file | Reference |
    |-------------|-----------|
    | `pyproject.toml`, `setup.py` | [references/python.md](references/python.md) — defers to the modern-python skill for tooling |
    | `CMakeLists.txt`, `Makefile` (C/C++) | [references/c-cpp.md](references/c-cpp.md) |
    | `Cargo.toml` | [references/rust.md](references/rust.md) |
    | `go.mod` | [references/go.md](references/go.md) |
    | `package.json` | [references/javascript.md](references/javascript.md) |
    | `Gemfile`, `*.gemspec` | [references/ruby.md](references/ruby.md) |
    
    For other ecosystems, apply the cross-cutting principles: reproducible
    builds from a fresh clone, CI-driven releases, trusted publishing or
    organization-owned accounts, and license metadata in the package manifest.
    
    ## Final Review
    
    Before the visibility switch is flipped, verify from an outsider's
    perspective:
    
    1. Clone into a clean directory and follow the README's build instructions
       verbatim — do they work with no tribal knowledge?
    2. Re-run `{baseDir}/scripts/check_readiness.sh` and confirm the remaining
       gaps are deliberate choices, stated to the user.
    3. Confirm the secrets audit (Step 2) actually happened; it is the one step
       that cannot be fixed after publication.
    
    Making the repository public is then a repository-settings change. Pair the
    release with an announcement where the organization has a process for one.
    
    ## Additional Resources
    
    ### Reference Files
    
    - **[references/licensing.md](references/licensing.md)** — license selection
      criteria, SPDX metadata, forks and relicensing
    - **[references/trailofbits.md](references/trailofbits.md)** — Trail of Bits
      policy overlay (loaded only when detected in Step 1)
    - **[references/python.md](references/python.md)**,
      **[references/c-cpp.md](references/c-cpp.md)**,
      **[references/rust.md](references/rust.md)**,
      **[references/go.md](references/go.md)**,
      **[references/javascript.md](references/javascript.md)**,
      **[references/ruby.md](references/ruby.md)** — per-language packaging,
      publishing, and quality tooling
    
    ### Scripts
    
    - **`scripts/detect_org.sh`** — prints the organization profile
      (`trailofbits` or `generic`) from git remotes and committer emails
    - **`scripts/check_readiness.sh`** — prints presence indicators for
      release-readiness files and flags tracked files that commonly hold secrets
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.

Related