summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorheilcheng <heilcheng@users.noreply.github.com>2026-10-15 22:56:18 +0800
committerheilcheng <heilcheng@users.noreply.github.com>2026-10-15 22:56:18 +0800
commit78eb286dcc6b0dd59cc291a6ead6d5359c795daf (patch)
tree8c28fff5f5d8cef06c2c8ef4071788074cd1125b
parent3dfdb3ecc040353e6b0fe7bab1cf099bb0b61346 (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.yml5
-rw-r--r--.github/ISSUE_TEMPLATE/problem.yml26
-rw-r--r--.github/PULL_REQUEST_TEMPLATE.md22
-rw-r--r--.github/copilot-instructions.md3
-rw-r--r--.github/scripts/check_submission.py132
-rw-r--r--.github/workflows/check-submission.yml62
-rw-r--r--AGENTS.md68
-rw-r--r--CLAUDE.md1
-rw-r--r--CONTRIBUTING.md20
-rw-r--r--README.md13
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.
---
diff --git a/README.md b/README.md
index 08847d8..bd589b2 100644
--- a/README.md
+++ b/README.md
@@ -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
---