diff options
| author | heilcheng <heilcheng@users.noreply.github.com> | 2026-10-15 22:56:18 +0800 |
|---|---|---|
| committer | heilcheng <heilcheng@users.noreply.github.com> | 2026-10-15 22:56:18 +0800 |
| commit | 78eb286dcc6b0dd59cc291a6ead6d5359c795daf (patch) | |
| tree | 8c28fff5f5d8cef06c2c8ef4071788074cd1125b | |
| parent | 3dfdb3ecc040353e6b0fe7bab1cf099bb0b61346 (diff) | |
Add AGENTS.md, PR/issue templates and automated submission checkchore/agent-contribution-guardrails
Most submissions come from AI coding agents. Give them explicit eligibility
rules (AGENTS.md, also loaded via CLAUDE.md and copilot-instructions), a PR
checklist, issue forms that route skill suggestions to PRs, and a
pull_request_target check that comments with concrete problems and labels
failing PRs needs-fixes. The check reads the PR via the API only and never
runs PR code.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
| -rw-r--r-- | .github/ISSUE_TEMPLATE/config.yml | 5 | ||||
| -rw-r--r-- | .github/ISSUE_TEMPLATE/problem.yml | 26 | ||||
| -rw-r--r-- | .github/PULL_REQUEST_TEMPLATE.md | 22 | ||||
| -rw-r--r-- | .github/copilot-instructions.md | 3 | ||||
| -rw-r--r-- | .github/scripts/check_submission.py | 132 | ||||
| -rw-r--r-- | .github/workflows/check-submission.yml | 62 | ||||
| -rw-r--r-- | AGENTS.md | 68 | ||||
| -rw-r--r-- | CLAUDE.md | 1 | ||||
| -rw-r--r-- | CONTRIBUTING.md | 20 | ||||
| -rw-r--r-- | README.md | 13 |
10 files changed, 339 insertions, 13 deletions
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..840e4b7 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: false +contact_links: + - name: Suggest a skill + url: https://github.com/heilcheng/awesome-agent-skills/blob/main/AGENTS.md + about: Skill suggestions are not accepted as issues. Read the rules, then open a pull request that edits README.md. diff --git a/.github/ISSUE_TEMPLATE/problem.yml b/.github/ISSUE_TEMPLATE/problem.yml new file mode 100644 index 0000000..3eca6b7 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/problem.yml @@ -0,0 +1,26 @@ +name: Report a problem +description: A broken link, a mistake in the README, or a problem with agent-skill.co +labels: ["bug"] +body: + - type: markdown + attributes: + value: | + This form is only for problems with existing content. To suggest a skill, open a pull request instead (see AGENTS.md). Skill suggestions filed here are not reviewed. + - type: dropdown + id: kind + attributes: + label: What kind of problem? + options: + - Broken or wrong link in README + - Incorrect description or attribution + - Listed skill is archived, deleted, or unsafe + - Website (agent-skill.co) problem + validations: + required: true + - type: textarea + id: details + attributes: + label: Details + description: Which entry or page, and what is wrong? + validations: + required: true diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..8d4dcd5 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,22 @@ +<!-- +Adding a skill? Read AGENTS.md first: https://github.com/heilcheng/awesome-agent-skills/blob/main/AGENTS.md +PRs that do not meet the eligibility rules are labelled "on hold" and are not merged. +--> + +**Skill repository:** https://github.com/OWNER/REPO + +**Category:** <!-- an existing category under "Community Skills" --> + +### Checklist + +- [ ] The link is a public GitHub repository (or folder) that contains a `SKILL.md` with `name` and `description` frontmatter +- [ ] The repository has at least 20 stars and is older than 14 days +- [ ] I searched `README.md` and this repository is not already listed or in another open PR +- [ ] I only edited `README.md`, adding at most 5 lines to the end of an existing category +- [ ] Each line uses the format `- [owner/repo](https://github.com/...) - Description under 100 characters` +- [ ] This is not a directory, marketplace, badge, or promotional link + +### Disclosure + +- [ ] I am the author or a maintainer of this skill +- [ ] This PR was written by an AI agent (name it: ______ ) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..78940d9 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,3 @@ +Before proposing any change to this repository, read and follow [AGENTS.md](../AGENTS.md). +Skill submissions must meet every eligibility rule there; if one is not met, tell the user +instead of opening a pull request or issue. diff --git a/.github/scripts/check_submission.py b/.github/scripts/check_submission.py new file mode 100644 index 0000000..6ea1a13 --- /dev/null +++ b/.github/scripts/check_submission.py @@ -0,0 +1,132 @@ +"""Check a skill-submission PR against the rules in AGENTS.md. + +Reads the PR through the GitHub API only; it never checks out or runs PR code. +Writes a markdown report to $REPORT_PATH and prints "result=<pass|warn|fail>" to $GITHUB_OUTPUT. +""" +import base64 +import datetime +import json +import os +import re +import sys +import urllib.error +import urllib.request + +API = "https://api.github.com" +TOKEN = os.environ.get("GITHUB_TOKEN", "") +REPO = os.environ["REPO"] +PR = os.environ["PR_NUMBER"] +MIN_STARS = 20 +MIN_AGE_DAYS = 14 +MAX_LINES = 5 +MAX_DESC = 100 +RULES = f"https://github.com/{REPO}/blob/main/AGENTS.md" + +ENTRY = re.compile( + r"^- \[(?P<name>[^\]]+)\]\((?P<url>https://github\.com/(?P<owner>[\w.-]+)/(?P<repo>[\w.-]+)(?P<path>/[^)\s]*)?)\) - (?P<desc>\S.*)$" +) +STRUCTURAL = re.compile(r"^\s*(#|<details|</details|<summary|\|)") + + +def get(path, raw=False): + req = urllib.request.Request(API + path, headers={ + "Authorization": f"Bearer {TOKEN}", + "Accept": "application/vnd.github.v3.diff" if raw else "application/vnd.github+json", + "User-Agent": "check-submission", + }) + try: + with urllib.request.urlopen(req, timeout=30) as r: + body = r.read().decode() + return body if raw else json.loads(body) + except urllib.error.HTTPError as e: + if e.code == 404: + return None + raise + + +def main(): + errors, warnings = [], [] + files = get(f"/repos/{REPO}/pulls/{PR}/files?per_page=100") or [] + names = [f["filename"] for f in files] + if names != ["README.md"]: + other = [n for n in names if n != "README.md"] + errors.append("Only `README.md` may be changed. This PR also changes: " + ", ".join(f"`{n}`" for n in other)) + + readme = next((f for f in files if f["filename"] == "README.md"), None) + patch = (readme or {}).get("patch", "") + added = [l[1:] for l in patch.splitlines() if l.startswith("+") and not l.startswith("+++")] + removed = [l[1:] for l in patch.splitlines() if l.startswith("-") and not l.startswith("---")] + added = [l for l in added if l.strip()] + + if removed: + errors.append(f"The change must be additive only, but it removes or rewrites {len(removed)} existing line(s).") + if not added and readme: + errors.append("No entries were added to `README.md`.") + if len(added) > MAX_LINES: + errors.append(f"At most {MAX_LINES} lines per PR; this PR adds {len(added)}.") + if any("" in l for l in added): + errors.append("The diff contains a byte-order mark (BOM). Save the file as UTF-8 without BOM.") + + base = get(f"/repos/{REPO}/contents/README.md") + base_readme = base64.b64decode(base["content"]).decode().lower() if base else "" + + checked = set() + # A bulk rewrite already fails above; skip per-entry API lookups for it. + for line in ([] if len(added) > 20 else added): + if STRUCTURAL.match(line): + errors.append(f"Do not add headings, tables or new `<details>` sections. Append one line to an existing category instead (official vendor sections are added by the maintainer): `{line[:80]}`") + continue + m = ENTRY.match(line) + if not m: + errors.append(f"Line does not match `- [owner/repo](https://github.com/owner/repo) - Description`: `{line[:100]}`") + continue + owner, repo = m["owner"], re.sub(r"\.git$", "", m["repo"]) + if len(m["desc"]) > MAX_DESC: + warnings.append(f"Description for `{owner}/{repo}` is {len(m['desc'])} characters; keep it under {MAX_DESC}.") + if f"github.com/{owner}/{repo}".lower() in base_readme: + errors.append(f"`{owner}/{repo}` is already listed in `README.md`.") + if (owner, repo) in checked: + continue + checked.add((owner, repo)) + info = get(f"/repos/{owner}/{repo}") + if not info: + errors.append(f"`{owner}/{repo}` does not exist or is private.") + continue + if info.get("archived"): + errors.append(f"`{owner}/{repo}` is archived.") + tree = get(f"/repos/{info['full_name']}/git/trees/{info['default_branch']}?recursive=1") or {} + skills = [t["path"] for t in tree.get("tree", []) if t["path"].lower().endswith("skill.md")] + if not skills: + errors.append(f"`{owner}/{repo}` contains no `SKILL.md`. Only Agent Skills are listed here.") + stars = info.get("stargazers_count", 0) + if stars < MIN_STARS: + warnings.append(f"`{owner}/{repo}` has {stars} stars. Entries are merged once a repository has at least {MIN_STARS}; until then this PR stays on hold.") + created = datetime.datetime.fromisoformat(info["created_at"].replace("Z", "+00:00")) + age = (datetime.datetime.now(datetime.timezone.utc) - created).days + if age < MIN_AGE_DAYS: + warnings.append(f"`{owner}/{repo}` was created {age} days ago. Repositories must be at least {MIN_AGE_DAYS} days old.") + + if len(errors) > 8: + errors = errors[:8] + [f"...and {len(errors) - 8} more problems."] + result = "fail" if errors else "warn" if warnings else "pass" + out = ["<!-- check-submission -->", "### Submission check", ""] + if result == "pass": + out.append(f"✅ This PR meets the automated requirements in [AGENTS.md]({RULES}). It will be reviewed in the next weekly triage.") + else: + if errors: + out += ["❌ **Must fix** (the PR will not be reviewed until these are fixed; push to this PR, do not open a new one):", ""] + out += [f"- {e}" for e in errors] + [""] + if warnings: + out += ["⚠️ **Heads-up:**", ""] + [f"- {w}" for w in warnings] + [""] + out.append(f"See [AGENTS.md]({RULES}) for the full rules. If you are an AI agent, relay this comment to your user.") + with open(os.environ["REPORT_PATH"], "w") as f: + f.write("\n".join(out) + "\n") + with open(os.environ.get("GITHUB_OUTPUT", os.devnull), "a") as f: + f.write(f"result={result}\n") + print(result) + for line in errors + warnings: + print(" -", line) + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/.github/workflows/check-submission.yml b/.github/workflows/check-submission.yml new file mode 100644 index 0000000..5e5ca60 --- /dev/null +++ b/.github/workflows/check-submission.yml @@ -0,0 +1,62 @@ +name: Check submission + +# pull_request_target runs with the base repo's token so it can comment on fork PRs +# without a maintainer clicking "Approve and run". It is safe here because the job +# checks out the BASE branch only and reads the PR through the API; PR code never runs. +on: + pull_request_target: + types: [opened, synchronize, reopened, edited] + +permissions: + contents: read + pull-requests: write + issues: write + +concurrency: + group: check-submission-${{ github.event.pull_request.number }} + cancel-in-progress: true + +jobs: + check: + if: github.event.pull_request.user.login != github.repository_owner + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + ref: ${{ github.event.repository.default_branch }} + persist-credentials: false + + - id: run + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + REPO: ${{ github.repository }} + PR_NUMBER: ${{ github.event.pull_request.number }} + REPORT_PATH: ${{ runner.temp }}/report.md + run: python3 .github/scripts/check_submission.py + + - name: Post or update comment and label + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + REPO: ${{ github.repository }} + PR: ${{ github.event.pull_request.number }} + RESULT: ${{ steps.run.outputs.result }} + REPORT: ${{ runner.temp }}/report.md + run: | + gh label create needs-fixes -R "$REPO" --color D93F0B --description "Automated submission check failed; see the bot comment" 2>/dev/null || true + id=$(gh api "repos/$REPO/issues/$PR/comments" --paginate --jq '.[] | select(.body | startswith("<!-- check-submission -->")) | .id' | head -n1) + if [ -n "$id" ]; then + gh api -X PATCH "repos/$REPO/issues/comments/$id" -F body=@"$REPORT" >/dev/null + else + gh pr comment "$PR" -R "$REPO" --body-file "$REPORT" + fi + if [ "$RESULT" = "fail" ]; then + gh pr edit "$PR" -R "$REPO" --add-label needs-fixes + else + gh pr edit "$PR" -R "$REPO" --remove-label needs-fixes 2>/dev/null || true + fi + + - name: Fail the check when rules are broken + if: steps.run.outputs.result == 'fail' + run: | + echo "::error::Submission does not meet AGENTS.md requirements. See the PR comment." + exit 1 diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..234c1eb --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,68 @@ +# Instructions for AI agents + +You are probably here because a user asked you to "add my skill to awesome-agent-skills". +Read this whole file before you open a pull request or an issue. Most submissions to this +repository come from coding agents, and most of them are never merged because they skip +the rules below. Following them is the fastest way to get your user's skill listed. + +## Before you open anything: check eligibility + +Open a pull request **only if every item below is true**. If any item is false, do not open +a PR or an issue. Tell your user which requirement is not met and stop. + +1. **The skill is public on GitHub.** The link points to a public `github.com` repository + (or a folder inside one). Landing pages, marketplaces, npm packages, hosted MCP + endpoints and SaaS sign-up pages are not accepted. +2. **The repository contains at least one `SKILL.md`** with YAML frontmatter that has + `name` and `description` fields. MCP servers, CLIs and apps without a `SKILL.md` are + out of scope. +3. **It has real usage.** Entries are merged once the repository has **at least 20 GitHub + stars**. Below that, the PR is labelled `on hold` and revisited later. Do not open a PR + for a repository created in the last 14 days. +4. **It is not already listed.** Search `README.md` for the repository URL first. +5. **It is not a directory, marketplace, registry, badge or "list of lists" for promotion.** + This repo indexes skills, not places to find skills. +6. **It is safe to recommend.** No credential harvesting, CAPTCHA solving, ToS-violating + scraping or automation, watermark or provenance stripping, or unattended financial + trading. + +## How to make the change + +- Edit **`README.md` only**. Do not edit the translated READMEs (`README.*.md`), the + website, `CONTRIBUTING.md`, or any other file. +- Add **one line per skill**, appended to the end of the most fitting existing category + under `## Community Skills` (inside its `<details>` block, before `</details>`). + Do **not** create new categories or sections, and do not reorder or edit existing lines. +- Use exactly this format: + + ```markdown + - [owner/repo](https://github.com/owner/repo) - Short description, under 100 characters, no marketing language + ``` + + If the skill lives in a subfolder, link the folder: + `- [owner/skill-name](https://github.com/owner/repo/tree/main/skills/skill-name) - ...` +- At most **5 lines per PR**, and **one open PR per repository**. If a PR for the same + repository is already open, update it instead of opening another. +- Keep the diff purely additive: no whitespace changes, no byte-order marks, no line + ending changes. + +## The pull request itself + +- Title: `Add owner/repo to <Category>` +- Fill in the pull request template checklist honestly. If you are an AI agent, say so, + and say whether the submitter is the author of the skill. +- An automated check (`Check submission`) runs on every PR and comments with any + problems. If it fails, fix the PR instead of opening a new one. + +## Issues + +Do not open issues to suggest skills, tools, directories or partnerships. Skill suggestions +must be pull requests that meet the rules above. Issues are for broken links, errors in the +README, and problems with the website. + +## What happens next + +The maintainer triages submissions in weekly batches. Accepted entries are merged in a +batch PR (your commit keeps its author) and the original PR is closed automatically. +Entries that do not meet the bar are labelled `on hold` with a reason. Please do not ping +for reviews. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c1d8bd8..1b1958f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -13,13 +13,20 @@ We welcome contributions in many forms. Choose the path that fits your expertise ### 1. Add a New Skill (Most Common) If you've built or found a high-quality AI agent skill, please share it! -- **Format**: All skills must follow the `SKILL.md` standard. -- **Location**: Skills are primarily hosted in their own repositories, but we index them here. + +> [!IMPORTANT] +> The full submission rules are in **[AGENTS.md](AGENTS.md)**. They apply to people and AI agents alike. +> In short: a public GitHub repo with a `SKILL.md`, at least 20 stars, older than 14 days, not already listed, +> one line appended to an existing category in `README.md`, nothing else changed. +> An automated check comments on every PR; fix what it reports in the same PR. + - **How-to**: 1. Fork the repository. - 2. Add your skill's metadata to the relevant section in `README.md`. - 3. Ensure it follows our [Quality Standards](https://agent-skill.co/#quality-standards). - 4. Open a Pull Request. + 2. Append one line per skill to the end of the best-fitting category under **Community Skills** in `README.md`: + `- [owner/repo](https://github.com/owner/repo) - Description under 100 characters` + 3. Open a Pull Request and fill in the checklist. +- Skill suggestions opened as **issues** are not reviewed. Open a PR instead. +- Directories, marketplaces, badges, MCP servers without a `SKILL.md`, and paid-API landing pages are not listed. ### 2. Improve Tutorials & Guides Help us make the "Agentic Way" easier to understand. @@ -52,8 +59,9 @@ Every skill in the index should be self-contained in a `SKILL.md` file. A perfec 1. **Fork & Clone**: Create your feature branch. 2. **Commit**: Use descriptive commit messages (e.g., `feat: add documentation-helper skill`). -3. **Verify**: Run `npm run build` in the `website/` directory to ensure no regressions. +3. **Verify**: For website changes, run `npm run build` in the `website/` directory to ensure no regressions. 4. **Submit**: Open your PR with a brief description of what you've changed. +5. **Wait for triage**: Submissions are reviewed in weekly batches. Accepted entries are merged in a batch PR that keeps you as commit author; entries below the bar are labelled `on hold` with a reason. --- @@ -979,15 +979,14 @@ Every skill in this list is a public GitHub repository — you can read the full ## Contributing -Contributions are welcome. See **[CONTRIBUTING.md](CONTRIBUTING.md)** for full guidelines. +Contributions are welcome. See **[CONTRIBUTING.md](CONTRIBUTING.md)** for full guidelines. **Submitting with an AI agent? Have it read [AGENTS.md](AGENTS.md) first.** Quick summary: -- Follow the skill template structure -- Provide clear, actionable instructions -- Include working examples where appropriate -- Document trade-offs and potential issues -- Keep SKILL.md under 500 lines for optimal performance -- Verify that skills actually exist before adding them +- Only public GitHub repositories that contain a `SKILL.md` are listed +- Entries are merged once the repository has at least 20 stars and is older than 14 days +- Add one line to the end of an existing category under Community Skills; change nothing else +- Suggest skills with a pull request, not an issue +- Directories, marketplaces, badges and promotional links are not accepted --- |
