Merge pull request #334 from jonathanhefner/juice-up-readme

Flesh out `README.md` with content from `home.mdx`

README.md

@@ -1,21 +1,58 @@
 # Agent Skills
 
-[Agent Skills](https://agentskills.io) are a simple, open format for giving agents new capabilities and expertise.
+[![Discord](https://img.shields.io/badge/Discord-Join-5865F2?logo=discord&logoColor=white)](https://discord.gg/MKPE9g8aUy)
 
-Skills are folders of instructions, scripts, and resources that agents can discover and use to perform better at specific tasks. Write once, use everywhere.
+A standardized way to give AI agents new capabilities and expertise.
 
-## Getting Started
+## What are Agent Skills?
+
+Agent Skills are a lightweight, open format for extending AI agent capabilities with specialized knowledge and workflows.
+
+At its core, a skill is a folder containing a `SKILL.md` file. This file includes metadata (`name` and `description`, at minimum) and instructions that tell an agent how to perform a specific task. Skills can also bundle scripts, reference materials, templates, and other resources.
+
+```
+my-skill/
+├── SKILL.md          # Required: metadata + instructions
+├── scripts/          # Optional: executable code
+├── references/       # Optional: documentation
+├── assets/           # Optional: templates, resources
+└── ...               # Any additional files or directories
+```
+
+## Why Agent Skills?
+
+Agents are increasingly capable, but often don't have the context they need to do real work reliably. Skills solve this by packaging procedural knowledge and company-, team-, and user-specific context into portable, version-controlled folders that agents load on demand. This gives agents:
+
+- **Domain expertise**: Capture specialized knowledge — from legal review processes to data analysis pipelines to presentation formatting — as reusable instructions and resources.
+- **Repeatable workflows**: Turn multi-step tasks into consistent, auditable procedures.
+- **Cross-product reuse**: Build a skill once and use it across any skills-compatible agent.
+
+## How do Agent Skills work?
+
+Agents load skills through **progressive disclosure**, in three stages:
+
+1. **Discovery**: At startup, agents load only the name and description of each available skill, just enough to know when it might be relevant.
+
+2. **Activation**: When a task matches a skill's description, the agent reads the full `SKILL.md` instructions into context.
+
+3. **Execution**: The agent follows the instructions, optionally executing bundled code or loading referenced files as needed.
+
+Full instructions load only when a task calls for them, so agents can keep many skills on hand with only a small context footprint.
+
+## Where can I use Agent Skills?
+
+Agent Skills are supported by a large number of AI tools and agentic clients — see the [Client Showcase](https://agentskills.io/clients) to explore some of them!
+
+## Getting started
 
 - **[Documentation](https://agentskills.io)** — Guides and tutorials
 - **[Specification](https://agentskills.io/specification)** — Format details
 - **[Example Skills](https://github.com/anthropics/skills)** — See what's possible
-- **[Discord](https://discord.gg/MKPE9g8aUy)** — Join the discussion!
+- **[Discord](https://discord.gg/MKPE9g8aUy)** — Share what you're building!
 
-This repo contains the specification, documentation, and reference SDK. Also see a list of example skills [here](https://github.com/anthropics/skills).
+## Open development
 
-## About
-
-Agent Skills is an open format maintained by [Anthropic](https://anthropic.com) and open to contributions from the community.
+The Agent Skills format was originally developed by [Anthropic](https://www.anthropic.com/), released as an open standard, and has been adopted by a growing number of agent products. The standard is open to contributions from the broader ecosystem — see [`CONTRIBUTING.md`](CONTRIBUTING.md) for how to get involved.
 
 ## License