Refined README & Contrib guides

X-Lovable-Edit-ID: edt-02052f77-9c7a-4d9d-a135-431fd54fdcc0
Co-authored-by: criptogus <128640021+criptogus@users.noreply.github.com>

Author: lovable-dev[bot]

CONTRIBUTING.md

@@ -1,74 +1,152 @@
 # Contributing to Super Agent Skill
 
-Thanks for wanting to make agents smarter. There are three kinds of contributions we love:
+> **First time here? Welcome.** This is one of the friendliest places to ship your first open-source contribution — most PRs land within 72h, and every accepted package goes live to thousands of agents through MCP.
 
-1. **New packages** — a skill, playbook, soul or guardrail in `content/`.
-2. **Improvements to existing packages** — better prompts, tighter rules, more examples, fixed edge cases.
-3. **Code & docs** for the platform itself (in `src/`).
+There are four flavors of contribution we love:
+
+1. 🛠 **New packages** — a Skill, Playbook, Soul or Guardrail in [`content/`](content/).
+2. ✨ **Improvements to existing packages** — sharper prompts, tighter rules, more examples, fixed edge cases, better adversarial coverage.
+3. 💻 **Code & docs** for the platform itself (in [`src/`](src/)).
+4. 🐛 **Bug reports, ideas, security disclosures** — issues are contributions too.
 
 By submitting a contribution you agree to license your work under the project's licenses (Apache 2.0 for code, CC BY-SA 4.0 for content).
 
-## Contributing a package
+---
+
+## 🚀 Fast path: ship a Skill in 15 minutes
+
+```bash
+# 1. Fork on GitHub, then:
+git clone git@github.com:<you>/agent-evolve-network.git
+cd agent-evolve-network
+bun install
+
+# 2. Copy a template
+cp content/skills/_template.yaml content/skills/my-skill.yaml
 
-### 1. Pick the right type
+# 3. Fill in: name, slug, description, system prompt, rules, examples
+$EDITOR content/skills/my-skill.yaml
 
-| You want to... | Use |
+# 4. Validate (same script CI runs)
+bun run validate:content
+
+# 5. Commit, push, open a PR using the "Package submission" template
+```
+
+That's it. A maintainer reviews for quality, safety and overlap with existing packages. Accepted packages are imported into the hosted registry on the next sync, where **SkillForge** evaluates them and serves the strongest version through MCP.
+
+---
+
+## 📦 Contributing a package
+
+### Step 1 — Pick the right type
+
+| You want to… | Use a… |
 | --- | --- |
 | Encapsulate a single capability with a contract (input → output) | **Skill** |
 | Codify a multi-step workflow that calls skills/tools in sequence | **Playbook** |
 | Define a persona, voice and value system for an agent | **Soul** |
 | Add safety, compliance or policy rules | **Guardrail** |
 
-### 2. Copy the template
+When in doubt, **split**. Two small skills beat one bloated one.
+
+### Step 2 — Copy the template
 
 ```bash
-cp content/skills/_template.yaml content/skills/my-skill.yaml
+cp content/<type>/_template.yaml content/<type>/<your-slug>.yaml
 ```
 
-Templates live next to the examples in each folder.
+Templates live next to working examples in each folder — read those first; they're the best docs we have.
 
-### 3. Fill it in — quality bar
+### Step 3 — Hit the quality bar
 
-A package will only be accepted if it:
+A package is accepted when it:
 
-- Has a clear, scoped purpose (do one thing well — split it if it doesn't fit on a page).
-- Includes **at least 2 worked examples** with realistic input and the exact expected output.
-- States `must` and `must_not` rules explicitly.
-- Uses a unique kebab-case `slug` not already in the registry.
-- Is original work, public-domain, or properly attributed.
-- Contains no secrets, PII, or copyrighted prompts pulled from a paid product.
+- ✅ Has a **clear, scoped purpose** — does one thing well.
+- ✅ Includes **at least 2 worked examples** with realistic input and the exact expected output.
+- ✅ States **`must` and `must_not`** rules explicitly (no hand-waving).
+- ✅ Uses a **unique kebab-case `slug`** not already in the registry.
+- ✅ Is **original work**, public domain, or properly attributed.
+- ✅ Contains **no secrets, PII, or copyrighted prompts** pulled from a paid product.
+- ✅ Passes `bun run validate:content` locally.
 
-### 4. Validate
+### Step 4 — Validate
+
+```bash
+bun run validate:content
+```
+
+The validator checks schema, slug uniqueness, file naming and example count. CI runs the same script on every PR.
+
+### Step 5 — Open a pull request
+
+Use the **Package submission** PR template. Include:
+
+- Why this package exists (the problem it solves in one sentence).
+- How you tested it — at minimum, paste 1 real run from a real agent.
+- Any prior art / inspirations / overlap with existing packages.
+
+A maintainer reviews within **72 hours**. Expect tiny nits — we're picky on purpose, because every package gets amplified across the network.
+
+---
+
+## 🛠 Improving an existing package
+
+- For **prompt tweaks, new examples, edge-case fixes** — just open a PR. Bump the `version` field (semver).
+- For **structural changes** (rename, breaking rule changes) — open an issue first so we can coordinate with downstream agents already depending on the slug.
+- For **drift fixes** flagged by SkillForge — mention the drift alert ID in your PR; we'll close it automatically on merge.
+- Always describe in the PR: **what got better, how you tested, what regressed (if anything)**.
+
+---
+
+## 💻 Code contributions
+
+- Match existing style — Prettier + ESLint run automatically.
+- Keep PRs focused: **one concern per PR**.
+- For non-trivial changes (>200 LOC or new dependencies), open an issue first to align on direction.
+- Add or update tests next to changed logic.
+- If you touch the MCP surface, update [`docs/mcp.md`](src/routes/docs.mcp.tsx) too.
+
+Local dev:
 
 ```bash
 bun install
+bun run dev          # http://localhost:5173
+bun test             # unit tests
 bun run validate:content
 ```
 
-The validator checks the schema, slug uniqueness and example count. CI runs the same script on your PR.
+---
+
+## 🐛 Reporting issues
+
+| Type | How |
+| --- | --- |
+| Bug in the platform | Open an issue with the **Bug** template |
+| Problem with a package | Open an issue with the **Content** template + the slug |
+| Feature idea | **Feature request** template — describe the user, not the solution |
+| Security vulnerability | **Please do NOT open a public issue.** See [SECURITY.md](SECURITY.md) |
+
+---
 
-### 5. Open a pull request
+## 🏷 Good first issues
 
-Use the **Package submission** PR template. A maintainer will review for quality, safety and overlap. Accepted packages are imported into the hosted registry on the next sync, where SkillForge starts evolving them.
+New contributors: filter issues by [`good first issue`](https://github.com/criptogus/agent-evolve-network/labels/good%20first%20issue) and [`help wanted`](https://github.com/criptogus/agent-evolve-network/labels/help%20wanted). Most are mergeable in one focused afternoon.
 
-## Improving an existing package
+If something's labeled but unclear, **comment first** and a maintainer will scope it down before you start.
 
-- Open an issue first if the change is structural (rename, breaking rules, etc.).
-- For prompt tweaks and new examples, just open a PR.
-- Bump the package's `version` field following semver.
-- Note the change in the PR description — what got better and how you tested it.
+---
 
-## Code contributions
+## 🤝 Code of Conduct
 
-- Match existing style (Prettier + ESLint).
-- Keep changes focused — one concern per PR.
-- For non-trivial changes, open an issue first to align on direction.
+All participation — issues, PRs, Discord, comments — is governed by the [Code of Conduct](CODE_OF_CONDUCT.md). Be kind. Critique ideas, not people. We enforce it.
 
-## Reporting issues
+---
 
-- **Bug or content problem:** use the matching issue template.
-- **Security vulnerability:** see [SECURITY.md](SECURITY.md) — please do **not** open a public issue.
+## 🌟 Recognition
 
-## Code of Conduct
+- Every merged contributor is listed in the [`AUTHORS`](AUTHORS) file and on the [public marketplace](https://www.superagentskill.com/marketplace/rankings).
+- Top contributors get the **Skill Architect** role on Discord, early access to new features, and a small monthly grant from the platform revenue pool.
+- **Found a robustness issue?** It's published as a public finding (e.g. `SAS-2026-0042`) with your handle credited — CVE-style.
 
-All participation is governed by the [Code of Conduct](CODE_OF_CONDUCT.md).
+Thanks for making agents smarter — together. ⭐

README.md

@@ -1,83 +1,154 @@
 <div align="center">
 
+<img src="https://www.superagentskill.com/og.png" alt="Super Agent Skill" width="640" />
+
 # Super Agent Skill
 
-**Open registry of Skills, Playbooks, Souls and Guardrails for AI agents — distributed over MCP.**
+### One command. Your agent becomes a genius.
+
+**The open MCP layer that turns any AI agent — Claude, Cursor, Codex, Continue — into a specialist, instantly.**
+
+[![Website](https://img.shields.io/badge/website-superagentskill.com-0A66FF?style=flat-square)](https://www.superagentskill.com)
+[![MCP](https://img.shields.io/badge/MCP-live-22c55e?style=flat-square)](https://www.superagentskill.com/api/mcp)
+[![Marketplace](https://img.shields.io/badge/marketplace-browse-8b5cf6?style=flat-square)](https://www.superagentskill.com/marketplace)
+[![License: Apache 2.0](https://img.shields.io/badge/code-Apache_2.0-000?style=flat-square)](LICENSE)
+[![License: CC BY-SA 4.0](https://img.shields.io/badge/content-CC_BY--SA_4.0-000?style=flat-square)](LICENSES/CONTENT-CC-BY-SA-4.0.txt)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-ff4f8b?style=flat-square)](CONTRIBUTING.md)
 
-[Website](https://www.superagentskill.com) · [Marketplace](https://www.superagentskill.com/marketplace) · [Docs](https://www.superagentskill.com/docs) · [MCP endpoint](https://www.superagentskill.com/api/mcp)
+[**Website**](https://www.superagentskill.com) · [**Marketplace**](https://www.superagentskill.com/marketplace) · [**Docs**](https://www.superagentskill.com/docs) · [**MCP endpoint**](https://www.superagentskill.com/api/mcp) · [**Discord**](https://www.superagentskill.com/community)
 
 </div>
 
 ---
 
-Super Agent Skill is two things:
+## Why Super Agent Skill?
 
-1. **A hosted platform** at [superagentskill.com](https://www.superagentskill.com) that runs the *SkillForge* evolution loop — it scores skills, finds weaknesses, patches them, and serves the best version through MCP to any compatible agent (Claude, Cursor, Codex, Continue, etc.).
-2. **An open registry** (this repo) of community-maintained `skills/`, `playbooks/`, `souls/` and `guardrails/`. Anything in `content/` is free to download, fork, remix and embed — under [CC BY-SA 4.0](LICENSES/CONTENT-CC-BY-SA-4.0.txt). The application code is [Apache 2.0](LICENSE).
+Generic agents are jacks of all trades, masters of none. They hallucinate, drift, and forget the rules your team actually cares about.
 
-> **Why open source it?** The MCP improvement loop only matters if there is a thriving catalog to improve. We want the catalog to belong to the community.
+**Super Agent Skill fixes that with three ingredients:**
 
-## What lives in `content/`
+- 🧠 **A growing open registry** of battle-tested **Skills**, **Playbooks**, **Souls** and **Guardrails** — community-owned, MIT-friendly, embeddable anywhere.
+- ⚙️ **SkillForge**, our continuous evolution loop — it benchmarks every skill against adversarial cases, finds weaknesses, and ships patches automatically.
+- 🔌 **One MCP endpoint** that streams the strongest version of every skill to any compatible agent — no copy-paste, no version drift.
 
-| Folder | What it is | Schema |
-| --- | --- | --- |
-| [`content/skills/`](content/skills) | A focused capability with a system prompt, rules, examples, and a runnable contract | [`schemas/skill.schema.json`](content/schemas/skill.schema.json) |
-| [`content/playbooks/`](content/playbooks) | A multi-step procedure that orchestrates skills/tools to reach an outcome | [`schemas/playbook.schema.json`](content/schemas/playbook.schema.json) |
-| [`content/souls/`](content/souls) | A persona/identity bundle — voice, values, defaults — that wraps any agent | [`schemas/soul.schema.json`](content/schemas/soul.schema.json) |
-| [`content/guardrails/`](content/guardrails) | Safety, compliance and policy rules attached to a skill or soul | [`schemas/guardrail.schema.json`](content/schemas/guardrail.schema.json) |
+> *Think GitHub for prompts × npm for agent capabilities × Wikipedia for AI behavior — all under MCP.*
+
+## 60-second quickstart
 
-Each item is a single self-contained YAML or JSON file. Browse the folders for working examples.
+**Option A — Plug it into your agent (recommended).** Point any MCP-compatible client at:
 
-## Use a package
+```
+https://www.superagentskill.com/api/mcp
+```
 
-**Download directly** (no account needed):
+That's it. Your agent now has discover / install / evaluate tools and live access to every skill in the registry.
+
+**Option B — Download a skill as a file.** Free, no account:
 
 ```bash
-curl -O https://raw.githubusercontent.com/<org>/super-agent-skill/main/content/skills/code-reviewer.yaml
+curl -O https://raw.githubusercontent.com/criptogus/agent-evolve-network/main/content/skills/code-reviewer.yaml
 ```
 
-**Or stream the live, evolving version through MCP** — point your agent at:
+**Option C — Run the whole platform locally:**
 
+```bash
+bun install
+bun run dev
 ```
-https://www.superagentskill.com/api/mcp
-```
-
-The hosted version is continuously evaluated and patched by SkillForge, so you always get the strongest variant.
 
-## Contribute a package
+## The four building blocks
 
-1. Fork this repo.
-2. Copy a template from `content/<type>/_template.yaml` into the same folder and rename it (`my-skill.yaml`).
-3. Fill it in. Validate locally:
-   ```bash
-   bun install
-   bun run validate:content
-   ```
-4. Open a pull request. CI runs the validator, and a maintainer reviews for quality, safety and overlap with existing packages.
+| | What it is | Use it when… |
+| --- | --- | --- |
+| 🛠 **Skills** | A focused capability with system prompt, rules, examples and a runnable input → output contract | You want the agent to *do one thing* very well (review code, write SQL, summarize a meeting). |
+| 📘 **Playbooks** | A multi-step decision graph that orchestrates skills + tools | The task has a recurring shape (triage bug → reproduce → propose fix → open PR). |
+| 🎭 **Souls** | A persona / value bundle — voice, taste, defaults — that wraps any agent | You need a consistent brand, tone or worldview across all tasks. |
+| 🛡 **Guardrails** | Refusal, safety and compliance policies enforced before output | You ship to real users and need hard "must / must not" rules. |
 
-Detailed rules are in [CONTRIBUTING.md](CONTRIBUTING.md). Please also read the [Code of Conduct](CODE_OF_CONDUCT.md).
+Each one is a single self-contained YAML file. **Read it, fork it, ship it.**
 
-## Run the platform locally
+```
+content/
+├── skills/         → Single capabilities
+├── playbooks/      → Multi-step workflows
+├── souls/          → Personas and values
+├── guardrails/     → Safety and compliance
+└── schemas/        → JSON Schemas (every package validates against these)
+```
 
-The app is a TanStack Start + Lovable Cloud project.
+## Ship your first skill in 4 steps
 
 ```bash
-bun install
-bun run dev
+# 1. Fork & clone
+git clone git@github.com:<you>/agent-evolve-network.git
+cd agent-evolve-network && bun install
+
+# 2. Start from a template
+cp content/skills/_template.yaml content/skills/my-killer-skill.yaml
+
+# 3. Validate locally (same script CI runs)
+bun run validate:content
+
+# 4. Open a PR — a maintainer reviews within 72h
 ```
 
-You will need a Lovable Cloud project (Supabase) — see [`supabase/`](supabase) for the schema. The marketplace UI, MCP endpoint, SkillForge loop and admin tools all live in [`src/`](src).
+A merged skill is automatically imported into the hosted registry, where **SkillForge starts evolving it against adversarial benchmarks** and serving the best variant through MCP to every connected agent on day one.
+
+➡️ Full quality bar in [**CONTRIBUTING.md**](CONTRIBUTING.md).
+
+## Why contribute?
+
+Your work isn't just merged — it's *amplified*.
+
+- 🌐 **Reach.** Every accepted package is served live through MCP to thousands of agents.
+- 🏆 **Reputation.** Public **Trust Score**, model compatibility matrix and leaderboard rankings on the [marketplace](https://www.superagentskill.com/marketplace/rankings).
+- 💸 **Revenue share.** Premium packages earn 80–85% of sales + recurring usage bonuses.
+- 🤖 **AI co-author.** SkillForge proposes patches when your skill drifts — you stay in control, accept or reject.
+- 🪪 **CVE-style credit.** Robustness findings (e.g. `SAS-2026-0001`) are publicly attributed.
+
+> **First-time contributor?** Look for [`good first issue`](https://github.com/criptogus/agent-evolve-network/labels/good%20first%20issue) and [`help wanted`](https://github.com/criptogus/agent-evolve-network/labels/help%20wanted) — most are mergeable in one afternoon.
+
+## What makes this different
+
+|  | Super Agent Skill | A prompt library on GitHub | A walled-garden GPT store |
+| --- | :---: | :---: | :---: |
+| Open content (CC BY-SA) | ✅ | ✅ | ❌ |
+| Schema-validated quality bar | ✅ | ❌ | ⚠️ opaque |
+| Works in *any* MCP agent | ✅ | ⚠️ manual paste | ❌ single vendor |
+| Continuous adversarial evolution | ✅ | ❌ | ❌ |
+| Public trust + compatibility scores | ✅ | ❌ | ❌ |
+| Revenue share for authors | ✅ | ❌ | ⚠️ limited |
 
 ## Roadmap
 
-- [ ] CLI to scaffold and publish packages straight from the terminal
-- [ ] Content signing so consumers can verify a package version
-- [ ] Versioned releases of the registry as downloadable bundles
-- [ ] Public leaderboard for the highest-scoring community packages
+- [x] MCP server with discover / install / evaluate / report-execution tools
+- [x] SkillForge evolution loop (eval → patch → re-score)
+- [x] Public **Trust Score**, model compatibility matrix, drift detection
+- [ ] CLI (`npx sas init`, `sas publish`, `sas eval`)
+- [ ] Cryptographically signed package releases
+- [ ] Versioned downloadable registry bundles
+- [ ] Community-curated **collections** (curated bundles around a use case)
+
+Track everything on the [public board](https://github.com/criptogus/agent-evolve-network/projects).
+
+## Community
+
+- 💬 **Discord** — [join here](https://www.superagentskill.com/community) for help, design reviews, and weekly skill-jam events.
+- 🐦 **X / Twitter** — [@superagentskill](https://twitter.com/superagentskill) for releases and benchmarks.
+- 📰 **Changelog** — every accepted package is announced in [GitHub Releases](https://github.com/criptogus/agent-evolve-network/releases).
+- 🛡 **Security** — please disclose responsibly via [SECURITY.md](SECURITY.md).
 
 ## License
 
-- **Code** in this repo: [Apache License 2.0](LICENSE)
-- **Content** in `content/`: [Creative Commons Attribution-ShareAlike 4.0](LICENSES/CONTENT-CC-BY-SA-4.0.txt)
+- **Code** (this repo, outside `content/`): [Apache License 2.0](LICENSE)
+- **Content** (everything in `content/`): [Creative Commons Attribution-ShareAlike 4.0](LICENSES/CONTENT-CC-BY-SA-4.0.txt)
+
+By contributing you agree your work is licensed under the same terms — and that it gets to make millions of agent conversations a little smarter every day.
+
+---
+
+<div align="center">
 
-By contributing you agree your contribution is licensed under the same terms.
+**Built by makers, for makers. Star the repo ⭐ if you believe agents should belong to everyone.**
+
+</div>

content/README.md

@@ -29,7 +29,7 @@ Each package is a single YAML file. Filename = `<slug>.yaml`.
 
 ```bash
 # raw download
-curl -O https://raw.githubusercontent.com/<org>/super-agent-skill/main/content/skills/code-reviewer.yaml
+curl -O https://raw.githubusercontent.com/criptogus/agent-evolve-network/main/content/skills/code-reviewer.yaml
 
 # or stream the live, evolving version through MCP
 # https://www.superagentskill.com/api/mcp