Pelagora — The Open Source Commerce Network

What is a Skill?

Skills are Markdown files. That's it. They contain structured instructions that an AI agent can read and execute to extend a Beacon's capabilities.

The canonical example is pelagora.md — the bootstrap Skill that installs and configures a Beacon from scratch. But Skills can do anything: add auction logic, manage rental calendars, run group buys, handle escrow.

Who writes Skills?

Three kinds of people tend to reach for Skill authoring:

Developers building commerce apps on Pelagora. If you're building a rental platform, a local marketplace, or anything on top of the network, you'll eventually want logic that lives outside your Beacon's core — bidding rules, escrow flows, access control. Skills let you package that logic in a way that AI agents can execute without custom integrations.

AI power users who want to automate buying or selling. If you already use Claude, ChatGPT, or another agent day-to-day, a Skill is how you give it Pelagora-specific superpowers. Instead of explaining Pelagora's API every time, you write the Skill once and hand it to your agent whenever you need it.

Community contributors. The Skills registry is community-driven. If you've figured out a workflow — reverse auctions, subscription gating, group buys — packaging it as a Skill lets anyone else on the network use it with a single download.

You don't need to be a seasoned engineer. If you can write clear instructions and basic JSON, you can write a Skill.

Anatomy of a Skill

A Skill file has three sections:

1. Context block

# Pelagora Reverse Auction Skill

**Version:** 1.2.0
**Requires:** Pelagora Beacon ≥ 0.8.0
**Author:** ReffoAI

2. Instructions

Plain English steps the AI follows. Be explicit — your agent will read this literally.

## Setup

1. Check that the Beacon is running: GET /api/status
2. Register the auction extension: POST /api/skills/register { "skill": "reverse-auction" }
3. Confirm registration: GET /api/skills → array should include "reverse-auction"

3. API reference

Inline OpenAPI-style docs so the agent knows the exact shape of requests:

### POST /api/auction/create

Creates a reverse auction where sellers compete to offer the lowest price.

**Body:**
```json
{
  "item": "string",       // what the buyer wants
  "budget": "number",     // buyer's max price
  "deadline": "ISO8601"   // when the auction closes
}


## Testing your Skill

The fastest way to test is to paste the Skill file into Claude and say:

> "Follow this Skill against a Beacon running at localhost:3000."

Watch what the agent does. If it gets confused or makes a wrong API call, rewrite that section of the Skill to be more explicit.

## Publishing

Once your Skill works, open a PR to the [ReffoAI Skills registry](https://github.com/ReffoAI/skills). Community members can then install it with a single line:

```bash
curl https://skills.pelagora.org/reverse-auction.md > reverse-auction.md
# Then hand it to your agent

Tip: Keep Skills focused. A Skill that does one thing well is far more reliable than one that tries to do everything.