Skip to content

feat(skills): add a getting-started-with-openshell skill for prospective contributors #5284

Open

Description

@purp

User Story

I'm an OpenShell maintainer on triage duty. I regularly see first-time contributors comment on several unrelated issues asking to implement them, without having used OpenShell or engaged with the community first. I need a consistent, low-effort answer to "how do I get started?" that steers that enthusiasm toward using OpenShell and joining the community, so that first contributions come from people with real context instead of blind PRs.

Description

Add a lightweight contributor skill, getting-started-with-openshell, under .agents/skills/. The answer to "How do I get started?" would become:

  1. Fork the project.
  2. Open an agent in your local checkout.
  3. Run /getting-started-with-openshell.

The skill would:

  • Ask about the person's interest: what they want to do with OpenShell, what agent and environment they use, and what draws them to the project. These questions decide what the person learns first; they are not a screen.
  • Help them build and learn: install or build OpenShell, run their own agent in a sandbox, write a policy for their use case, and read the resulting logs, including OCSF events. It would point them to the docs, RFCs, and crate READMEs for the area they care about.
  • Direct them toward involvement only when it sees evidence of engagement. Evidence would include a sandbox running a real workload, a policy they wrote and can explain, specific friction or a bug they hit, or a clear area of interest. Involvement would mean joining CNCF Slack and the community call, requesting a vouch, and looking for unowned good first issue work that has maintainer acceptance.
  • Help draft a vouch request built only from the person's own answers and hands-on usage. The person would rewrite it in their own voice and post it themselves.
  • Suggest a contributor's badge as the first PR: a good first issue implemented by an agent running inside an OpenShell sandbox, with OCSF log excerpts from that session in the PR.
  • Without that evidence, encourage more hands-on use instead of suggesting issues to claim.

The skill would not post comments, claim issues, open PRs, or post a vouch request on the person's behalf.

Context

  • CONTRIBUTING.md explains the vouch gate and the state:accepted requirement for PRs. It doesn't explain how to choose and claim work, and the two requirements sit about 400 lines apart.
  • CONTRIBUTING.md sends newcomers to good first issue, but no open issues carry that label today.
  • CONTRIBUTING.md mentions the CNCF Slack channel without a link.

Out of scope, possible follow-ups:

  • Having triage-issue recommend good first issue for small, well-scoped accepted issues.
  • Applying good first issue to existing issues.

Definition of Done

  • .agents/skills/getting-started-with-openshell/SKILL.md exists with metadata.internal: true and covers the interest, learn, and involvement phases described above.
  • The skill takes no GitHub write actions.
  • The CONTRIBUTING.md contributor skill table lists the skill.
  • The First-Time Contributors section of CONTRIBUTING.md points newcomers to the skill.
  • CONTRIBUTING.md links CNCF Slack to its inviter, and its vouch guidance allows an agent to help organize a request grounded in the person's own usage.
  • Links in the skill resolve.

Activity

  1. added
    area:buildCI/CD workflows, releases, build targets, packaging, and artifact publication.
    topic:documentationArchitecture docs, READMEs, project website updates, and automated documentation generation.
    topic:dxMaking OpenShell easy to contribute to for humans and agents.
    on Nov 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:buildCI/CD workflows, releases, build targets, packaging, and artifact publication.topic:documentationArchitecture docs, READMEs, project website updates, and automated documentation generation.topic:dxMaking OpenShell easy to contribute to for humans and agents.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions