From dd417fcc61a2d3f57fee6209d72ea71145a095e2 Mon Sep 17 00:00:00 2001 From: Jim Meyer Date: Wed, 4 Nov 2026 15:05:56 -0800 Subject: [PATCH 1/2] feat(skills): add getting-started-with-openshell skill for prospective contributors Guides a newcomer from stated interest to hands-on use of OpenShell, and toward Discussions, Slack, a vouch request, and good first issues only once they show real engagement. Takes no GitHub write actions. Refs #5284 Signed-off-by: Jim Meyer --- .../getting-started-with-openshell/SKILL.md | 61 +++++++++++++++++++ CONTRIBUTING.md | 3 + 2 files changed, 64 insertions(+) create mode 100644 .agents/skills/getting-started-with-openshell/SKILL.md diff --git a/.agents/skills/getting-started-with-openshell/SKILL.md b/.agents/skills/getting-started-with-openshell/SKILL.md new file mode 100644 index 0000000000..e6c1fa93b5 --- /dev/null +++ b/.agents/skills/getting-started-with-openshell/SKILL.md @@ -0,0 +1,61 @@ +--- +name: getting-started-with-openshell +description: Guide a prospective OpenShell contributor from first interest to hands-on use, and toward community involvement once they show real engagement. Use when someone asks how to get started, how to contribute, what to work on first, or how to get involved with OpenShell. Trigger keywords - getting started, get started, how do I contribute, first contribution, get involved, new contributor, onboarding. +metadata: + internal: true +--- + +# Getting Started with OpenShell + +Help a prospective contributor turn interest into hands-on experience, then point them toward the community. OpenShell values contributors who use it and understand it. Someone shopping for any issue to implement is not ready to contribute yet. Your job is to guide them, not to do their onboarding for them. + +## Ground rules + +- Take no GitHub write actions. Do not comment on issues, claim or assign work, open PRs, or start discussions on the person's behalf. +- Never draft a vouch request. [CONTRIBUTING.md](../../../CONTRIBUTING.md#first-time-contributors) denies AI-generated vouch requests; the person must write it in their own words. +- Ask one or two questions at a time and listen. Adapt to what they tell you; this is a conversation, not a form. +- Let them do the work. Explain commands and concepts, but have them run things and read the output themselves. + +## 1. Learn their interest + +Ask: + +- What do they want to do with OpenShell? Which agent do they run, and what should it be able, or unable, to do? +- What environment do they use: a laptop with Docker or Podman, Kubernetes, or a VM? +- What draws them to the project: security, policy, agent tooling, infrastructure, or something else? + +If they only want "something to work on," say plainly that the project looks for contributors who use OpenShell first, then continue to the next phase. + +## 2. Build and learn + +Guide them through hands-on use that matches their interest. Prefer the published docs at for product concepts and `openshell --help` for command syntax. + +1. Install OpenShell, or build it from source following Prerequisites and Getting Started in [CONTRIBUTING.md](../../../CONTRIBUTING.md#prerequisites). +2. Run their own agent in a sandbox with the [Run Your First Agent](https://docs.nvidia.com/openshell/latest/about/run-your-first-agent) guide. +3. Write or adjust a policy for their real use case. Have them trigger an allowed and a denied request. +4. Read the sandbox logs with `openshell logs ` and find the OCSF events for those decisions. See [Accessing Logs](https://docs.nvidia.com/openshell/latest/observability/accessing-logs). +5. Point them to background for their area: the architecture table in [AGENTS.md](../../../AGENTS.md#architecture-overview), the relevant crate `README.md`, and related RFCs in [rfc/](../../../rfc/README.md). + +Ask what surprised them, what was hard, and what they would change. Their answers are the start of a perspective worth bringing to the community. + +## 3. Assess engagement + +Look for evidence in the conversation and their workspace. Strong signals: + +- A sandbox running a real workload, not only the hello-world example. +- A policy they wrote and can explain. +- Specific friction, a bug, or a missing feature they hit themselves. +- A clear area of interest they can connect to code, docs, or an RFC. + +Weak signals: wanting any open issue, choosing issues by label or title alone, or being unable to describe what they did with OpenShell. With only weak signals, encourage more hands-on use from phase 2 and stop there. Do not suggest issues to claim. + +## 4. Point toward involvement + +When the evidence is strong, explain the path in [CONTRIBUTING.md](../../../CONTRIBUTING.md#first-time-contributors): + +1. Join the community. Introduce themselves in [GitHub Discussions](https://github.com/NVIDIA/OpenShell/discussions) or the CNCF Slack channel with what they use OpenShell for. File bugs or feature requests from their own experience with the issue templates. +2. Request a vouch in their own words. Unvouched PRs are closed automatically. +3. Find work. Look for open [`good first issue`](https://github.com/NVIDIA/OpenShell/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) issues in their area. A PR from someone without write access must link an issue labeled `state:accepted` (see Pull Requests in `CONTRIBUTING.md`). Check for an existing assignee, branch, or PR first. Comment once on the issue they choose, saying why they want it and how they would approach it, and wait for a maintainer. +4. Earn the badge of honor. Implement the first issue with an agent running inside an OpenShell sandbox, and include OCSF log excerpts from that session in the PR as evidence. Redact anything sensitive. + +If no matching `good first issue` exists, suggest staying engaged through Discussions and Slack rather than picking an unrelated issue. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3e800debdf..a33d13f22c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,6 +20,8 @@ OpenShell is agent-first, not agent-only. The distinction matters: ## First-Time Contributors +Start by using OpenShell. To get guided help, fork the repository, open your agent in your local checkout, and run the `getting-started-with-openshell` skill. It asks what you want to do with OpenShell, helps you run your own agent in a sandbox, and points you toward the community and first issues once you have hands-on experience. + We use a vouch system. This exists because AI makes it trivial to generate plausible-looking but low-quality contributions, and we can no longer trust by default. 1. Open a [Vouch Request](https://github.com/NVIDIA/OpenShell/discussions/new?category=vouch-request) discussion. @@ -99,6 +101,7 @@ Contributor and maintainer skills live in `.agents/skills/`. They are marked int | Category | Skill | Purpose | | --------------- | ------------------------- | --------------------------------------------------------------------------------------------------- | +| Contributing | `getting-started-with-openshell` | Guide a prospective contributor from first use to community involvement | | Contributing | `create-spike` | Investigate a problem, produce a structured GitHub issue | | Contributing | `create-rfc` | Create RFC proposals from the repository template | | Contributing | `build-from-issue` | Plan and implement work from a GitHub issue (maintainer workflow) | From a34d1e9bfc9d91cceb15f6909729637142cfb729 Mon Sep 17 00:00:00 2001 From: Jim Meyer Date: Wed, 4 Nov 2026 17:49:15 -0800 Subject: [PATCH 2/2] feat(skills): orient getting-started on Slack, community call, and grounded vouch drafts Point newcomers to CNCF Slack (slack.cncf.io) and the community call instead of Discussions. Allow the skill to help draft a vouch request built only from the person's own answers and hands-on usage, and align the CONTRIBUTING vouch guidance with that. Rename the first-PR evidence to a contributor's badge. Refs #5284 Signed-off-by: Jim Meyer --- .../getting-started-with-openshell/SKILL.md | 22 +++++++++---------- CONTRIBUTING.md | 6 ++--- 2 files changed, 14 insertions(+), 14 deletions(-) diff --git a/.agents/skills/getting-started-with-openshell/SKILL.md b/.agents/skills/getting-started-with-openshell/SKILL.md index e6c1fa93b5..4274277117 100644 --- a/.agents/skills/getting-started-with-openshell/SKILL.md +++ b/.agents/skills/getting-started-with-openshell/SKILL.md @@ -1,6 +1,6 @@ --- name: getting-started-with-openshell -description: Guide a prospective OpenShell contributor from first interest to hands-on use, and toward community involvement once they show real engagement. Use when someone asks how to get started, how to contribute, what to work on first, or how to get involved with OpenShell. Trigger keywords - getting started, get started, how do I contribute, first contribution, get involved, new contributor, onboarding. +description: Guide a prospective OpenShell contributor from first interest to hands-on use, and toward community involvement once they show real engagement. Use when someone asks how to get started, how to contribute, what to work on first, or how to get involved with OpenShell. Trigger keywords - getting started, get started, how do I contribute, first contribution, get involved, new contributor, onboarding, vouch request. metadata: internal: true --- @@ -11,20 +11,20 @@ Help a prospective contributor turn interest into hands-on experience, then poin ## Ground rules -- Take no GitHub write actions. Do not comment on issues, claim or assign work, open PRs, or start discussions on the person's behalf. -- Never draft a vouch request. [CONTRIBUTING.md](../../../CONTRIBUTING.md#first-time-contributors) denies AI-generated vouch requests; the person must write it in their own words. +- Take no GitHub write actions. Do not comment on issues, claim or assign work, open PRs, or post a vouch request on the person's behalf. - Ask one or two questions at a time and listen. Adapt to what they tell you; this is a conversation, not a form. - Let them do the work. Explain commands and concepts, but have them run things and read the output themselves. +- Keep track of their answers and what they actually did. Phase 4 builds on that record, and nothing else. ## 1. Learn their interest -Ask: +Use questions to choose what they should learn first, not to screen them. Ask: - What do they want to do with OpenShell? Which agent do they run, and what should it be able, or unable, to do? - What environment do they use: a laptop with Docker or Podman, Kubernetes, or a VM? - What draws them to the project: security, policy, agent tooling, infrastructure, or something else? -If they only want "something to work on," say plainly that the project looks for contributors who use OpenShell first, then continue to the next phase. +Use the answers to pick the sandbox, policy, and background reading for phase 2. If they only want "something to work on," say plainly that the project looks for contributors who use OpenShell first, then continue to phase 2. ## 2. Build and learn @@ -47,15 +47,15 @@ Look for evidence in the conversation and their workspace. Strong signals: - Specific friction, a bug, or a missing feature they hit themselves. - A clear area of interest they can connect to code, docs, or an RFC. -Weak signals: wanting any open issue, choosing issues by label or title alone, or being unable to describe what they did with OpenShell. With only weak signals, encourage more hands-on use from phase 2 and stop there. Do not suggest issues to claim. +Weak signals: wanting any open issue, choosing issues by label or title alone, or being unable to describe what they did with OpenShell. With only weak signals, encourage more hands-on use from phase 2 and stop there. Do not suggest issues to claim or help with a vouch request. ## 4. Point toward involvement When the evidence is strong, explain the path in [CONTRIBUTING.md](../../../CONTRIBUTING.md#first-time-contributors): -1. Join the community. Introduce themselves in [GitHub Discussions](https://github.com/NVIDIA/OpenShell/discussions) or the CNCF Slack channel with what they use OpenShell for. File bugs or feature requests from their own experience with the issue templates. -2. Request a vouch in their own words. Unvouched PRs are closed automatically. -3. Find work. Look for open [`good first issue`](https://github.com/NVIDIA/OpenShell/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) issues in their area. A PR from someone without write access must link an issue labeled `state:accepted` (see Pull Requests in `CONTRIBUTING.md`). Check for an existing assignee, branch, or PR first. Comment once on the issue they choose, saying why they want it and how they would approach it, and wait for a maintainer. -4. Earn the badge of honor. Implement the first issue with an agent running inside an OpenShell sandbox, and include OCSF log excerpts from that session in the PR as evidence. Redact anything sensitive. +1. **Join the community.** Get an invite to CNCF Slack at , find the OpenShell channel, and introduce themselves with what they use OpenShell for and what they learned. Join the [OpenShell Community Google Group](https://groups.google.com/a/ai-openshell.org/g/openshell-community/about) to get the community call invitation and agenda, and attend a call. File bugs or feature requests from their own experience with the issue templates. +2. **Request a vouch.** Offer to help draft a [Vouch Request](https://github.com/NVIDIA/OpenShell/discussions/new?category=vouch-request). Build the draft only from their answers in phase 1 and what they did in phases 2 and 3: their use case, the sandbox and policy they ran, and the friction or interest they found. Do not add experience they did not describe or skills they did not show. Have them review the draft and rewrite it in their own voice, then post it themselves. Unvouched PRs are closed automatically. +3. **Find work.** Look for open [`good first issue`](https://github.com/NVIDIA/OpenShell/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) issues in their area. A PR from someone without write access must link an issue labeled `state:accepted` (see Pull Requests in `CONTRIBUTING.md`). Check for an existing assignee, branch, or PR first. Comment once on the issue they choose, saying why they want it and how they would approach it, and wait for a maintainer. +4. **Earn a contributor's badge.** Implement the first issue with an agent running inside an OpenShell sandbox, and include OCSF log excerpts from that session in the PR as evidence. Redact anything sensitive. -If no matching `good first issue` exists, suggest staying engaged through Discussions and Slack rather than picking an unrelated issue. +If no matching `good first issue` exists, suggest asking in Slack or on a community call where help is wanted, rather than picking an unrelated issue. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a33d13f22c..ab4f179610 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,13 +20,13 @@ OpenShell is agent-first, not agent-only. The distinction matters: ## First-Time Contributors -Start by using OpenShell. To get guided help, fork the repository, open your agent in your local checkout, and run the `getting-started-with-openshell` skill. It asks what you want to do with OpenShell, helps you run your own agent in a sandbox, and points you toward the community and first issues once you have hands-on experience. +Start by using OpenShell. To get guided help, fork the repository, open your agent in your local checkout, and run the `getting-started-with-openshell` skill. It asks what you want to do with OpenShell, helps you run your own agent in a sandbox, and once you have hands-on experience, points you toward [CNCF Slack](https://slack.cncf.io), the community call, and first issues. We use a vouch system. This exists because AI makes it trivial to generate plausible-looking but low-quality contributions, and we can no longer trust by default. 1. Open a [Vouch Request](https://github.com/NVIDIA/OpenShell/discussions/new?category=vouch-request) discussion. 2. Describe what you want to change and why. -3. Write in your own words. AI-generated vouch requests will be denied. +3. Write in your own words, based on your own use of OpenShell. An agent may help you organize what you did and learned, but vouch requests that are generic or don't reflect your own experience will be denied. 4. A maintainer will comment `/vouch` if approved, and the request discussion will close automatically. 5. **Get vouched before opening a PR.** Once vouched, you can submit pull requests. @@ -76,7 +76,7 @@ Pull requests that touch the enforcement machinery or reviewer routing — anyth Use exactly one `area:` label and any relevant `topic:` labels on your pull request. The [reviewer routing workflow](.github/workflows/review-readiness.yml) requests all matching members of [REVIEWERS.md](REVIEWERS.md), excluding the author, when a PR opens ready for review, leaves draft status, or gains or loses an area/topic label. Reviewers do not need repository write access to receive requests or review PRs. Manual reviewer choices and people who have commented or reviewed are preserved. Propose roster membership changes through a reviewed PR. -If your pull request has been idle, ask for a reviewer in the pull request or in the CNCF Slack channel rather than waiting. +If your pull request has been idle, ask for a reviewer in the pull request or in the OpenShell channel on [CNCF Slack](https://slack.cncf.io) rather than waiting. ## Agent Skills