Merge pull request #25 from entireio/claude/strange-driscoll-873c0f · Entire

Merge pull request #25 from entireio/claude/strange-driscoll-873c0f

6b321b7→main

Add first-time contributors guide

Changes

Before you start

Fork the repo:

If you add, remove, rename, or materially change a skill, update README.md when the public list or examples change.

Using AI

It is fine to use coding agents while contributing to this repo, and you do not need to disclose that you did. Use whatever agent and workflow you like.

You are still responsible for the final wording, examples, and metadata. Review the diff yourself before opening a PR. Watch for vague "when to use" descriptions, instructions that read like marketing instead of a concrete workflow, and generic advice that does not match this repo's style. PRs that look generated, unreviewed, or "vibe coded" may be closed.

Validation

Before opening a PR, check that the skills installer can discover the repo.

First-Time Contributors

Welcome. This guide is for people who are new to Entire, new to open source, or just want a careful path through their first contribution to this repository.

The main contribution rules live in CONTRIBUTING.md. Treat that file as the source of truth. This page slows the process down and explains where to start, what to say, what to run, and what to expect after you open a pull request.

Who This Is For

Start here if any of these are true:

If you are already comfortable with this repo, use the shorter workflow in CONTRIBUTING.md.

What This Repo Contains

This repo is intentionally small. Each skill lives in skills/<skill-name>/SKILL.md, with a few plugin and extension metadata files that make the same skills installable across different agents (Claude Code, Codex, Cursor, Copilot, Gemini, OpenCode).

A skill is a short Markdown file with YAML front matter that tells a coding agent when to run a specific workflow and how to run it. Most contributions are edits to a SKILL.md file, a small new skill, or a wording fix to the README or contributor docs.

Choose a First Contribution

Start by browsing GitHub Issues for issues that describe behavior you can reproduce, mention a skill or prompt you can try locally, or feel concrete enough that you can explain the problem back in your own words. You can also ask in the Entire Community Discord. You do not need to understand the whole project before asking about an issue.

Good first contributions are small, clear, and easy to review. For this repo, that usually means one of these:

When looking at an issue, favor ones where you can explain the problem back in your own words. It is okay if you do not know the fix yet. If an issue is broad, comment with the part you think you can tackle and ask whether that slice would be useful.

As a first PR, avoid sweeping rewrites of multiple skills, renaming existing skills, or changing plugin or marketplace metadata across all the agent integrations at once. Those changes are worth doing, but they are easier as follow-ups once a maintainer has helped define the scope.

Comment Before You Start

Before starting non-trivial work, leave a short comment on the issue or open a new one. This avoids duplicated effort and gives maintainers a chance to redirect you before you spend time on the wrong approach.

A good first comment is specific:

Hi, I am new to Entire and would like to work on this.

I tried the `search` skill in my own repo and the agent could not tell whether `entire login` was required. My plan is to update skills/search/SKILL.md so the agent explains the missing prerequisite before falling back. Does that sound like the right direction?

If you are not starting from an existing issue, open one with the smallest concrete problem you can describe:

I hit confusing behavior while asking my agent to `explain` a function.

Expected: the agent would tell me when no Entire session was found.
Actual: the agent guessed an explanation from the code only.

Would a small PR that tightens the "when not to use" section of skills/explain/SKILL.md be useful?

You do not need a perfect plan. Showing what you have tried and where you are headed is usually enough.

Set Up the Repository

Fork the repository on GitHub, then clone your fork:

git clone git@github.com:YOUR-USERNAME/skills.git
dcd skills

Add the upstream repository so you can pull in maintainer changes later:

git remote add upstream git@github.com:entireio/skills.git
git fetch upstream

There is no build step. The skills are plain Markdown files plus a small amount of JSON metadata, so you do not need a toolchain beyond git and node (used only for validation below).

Create a Branch

Create a branch from the latest main:

git switch main
git pull upstream main
git switch -c docs/clarify-search-prereqs

Use a branch name that describes the change. Examples:

Make a Small Change

Keep your first pull request narrow. A focused PR is easier to review and easier to finish.

Good first PR shapes:

If you are adding or editing a skill, read one existing skill that is similar to your change first. For example, skills/explain/SKILL.md and skills/what-happened/SKILL.md are good references for tone and level of detail.

Every SKILL.md needs YAML front matter with at least:

---
name: skill-name
description: A short description of when an agent should use this skill.
---

Avoid bundling unrelated cleanup with your first PR. If you notice extra things while working, leave yourself a note and open a follow-up issue or PR later.

Use AI Carefully

It is completely normal to use coding agents while contributing to this repo. We hope you like Goose, of course. There is no need to tell us that you used AI in your work.

Use whatever agent and workflow you like. The important rule is that you are responsible for the final wording, examples, and metadata. Before submitting a PR, review the diff yourself. PRs that look generated, unreviewed, or "vibe coded" without a human pass may be closed.

Quick responsible AI tips:

Run the Right Checks

For wording-only Markdown changes, a quick sanity check is enough:

git diff --check

For changes to a SKILL.md or new skills, confirm the installer can still discover the skills in this repo:

npx -y skills@latest add . --list --yes

If you changed any JSON metadata, validate that the JSON still parses:

node -e 'for (const f of ["package.json","gemini-extension.json",".codex-plugin/plugin.json",".claude-plugin/plugin.json",".cursor-plugin/plugin.json",".agents/plugins/marketplace.json"]) JSON.parse(require("fs").readFileSync(f, "utf8"))'

If you changed the OpenCode plugin shim, check its syntax:

node --check .opencode/plugins/entire.js

For Markdown-only changes, read the rendered Markdown or preview it in GitHub before submitting.

Commit Your Work

Commit with a short, descriptive message:

git add <files you changed>
git commit -m "Clarify search skill prerequisites"

If you have the Entire CLI installed and enabled in this repository, the git hook may add an Entire-Checkpoint trailer to your commit message automatically. That is expected.

Open a Pull Request

Push your branch to your fork:

git push -u origin docs/clarify-search-prereqs

Then open a pull request against entireio/skills on GitHub.

In the PR description, include:

If your PR is not ready for final review yet, open it as a draft. Draft PRs are useful when you want early feedback on direction.

Respond to Review

Review is part of the contribution, not a sign that you did something wrong.

For each review comment:

After pushing updates, leave a short comment saying what changed. GitHub does not always make it obvious which comments were addressed by a new commit.

If You Get Stuck

Ask early, and include context. Good help requests include:

Useful places to ask:

Quick Checklist

Before opening your first PR:

Thank you for taking the time to contribute. Small, careful improvements make the project easier for the next person too.