Repository navigation
Open
Labels
area:buildCI/CD workflows, releases, build targets, packaging, and artifact publication.CI/CD workflows, releases, build targets, packaging, and artifact publication.topic:documentationArchitecture docs, READMEs, project website updates, and automated documentation generation.Architecture docs, READMEs, project website updates, and automated documentation generation.topic:dxMaking OpenShell easy to contribute to for humans and agents.Making OpenShell easy to contribute to for humans and agents.
Description
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:
- Fork the project.
- Open an agent in your local checkout.
- 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 issuework 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 issueimplemented 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.mdexplains the vouch gate and thestate:acceptedrequirement for PRs. It doesn't explain how to choose and claim work, and the two requirements sit about 400 lines apart.CONTRIBUTING.mdsends newcomers togood first issue, but no open issues carry that label today.CONTRIBUTING.mdmentions the CNCF Slack channel without a link.
Out of scope, possible follow-ups:
- Having
triage-issuerecommendgood first issuefor small, well-scoped accepted issues. - Applying
good first issueto existing issues.
Definition of Done
-
.agents/skills/getting-started-with-openshell/SKILL.mdexists withmetadata.internal: trueand covers the interest, learn, and involvement phases described above. - The skill takes no GitHub write actions.
- The
CONTRIBUTING.mdcontributor skill table lists the skill. - The First-Time Contributors section of
CONTRIBUTING.mdpoints newcomers to the skill. -
CONTRIBUTING.mdlinks 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.
Metadata
Metadata
Assignees
Labels
area:buildCI/CD workflows, releases, build targets, packaging, and artifact publication.CI/CD workflows, releases, build targets, packaging, and artifact publication.topic:documentationArchitecture docs, READMEs, project website updates, and automated documentation generation.Architecture docs, READMEs, project website updates, and automated documentation generation.topic:dxMaking OpenShell easy to contribute to for humans and agents.Making OpenShell easy to contribute to for humans and agents.
Activity
feat(skills): orient getting-started on Slack, community call, and gr…