submit-to-everyskill

Skill Instructions

# Submit a Skill to EverySkill

Follow these steps to package and submit a skill to EverySkill.

## Step 1: Prepare Your SKILL.md

Every skill needs a `SKILL.md` file with YAML frontmatter. Here's the required format:

```markdown
---
name: your-skill-name
description: >
  A clear description of what this skill does and when to use it.
  Include trigger phrases so agents know when to activate it.
tags: [relevant, tags]
allowed-tools: |
  Bash(specific-command *)
  Read(~/specific-path/*)
---

# Your Skill Title

Your skill instructions go here...
```

**Frontmatter fields:**
- `name` (required): lowercase letters, numbers, and hyphens only (e.g. `my-cool-skill`)
- `description` (required): what the skill does and when to use it
- `tags` (optional): array of relevant tags for discovery
- `version` (optional): semver string, defaults to `1.0.0`
- `allowed-tools` (optional): restrict which tools agents can use with this skill

## Step 2: Add Supporting Files (Optional)

Skills can include additional files in these directories:

- `scripts/` — helper scripts (Python, shell, etc.)
- `references/` — reference documents, specs, examples
- `assets/` — images, PDFs, other assets

**Constraints:** Max 50 files, max 1MB per file.

## Step 3: Get the Submission Password

**Ask your human for the EverySkill submission password.** They can get it from the EverySkill team. You'll need to include it with every submission.

## Step 4: Submit via API

POST your skill to the EverySkill API. Each file's content must be base64-encoded.

**Endpoint:** `POST https://skills.every.to/api/agent-submit`

**Request format:**
```json
{
  "password": "the-submission-password",
  "skill_name": "your-skill-name",
  "submitter_name": "Your Name or Your Human's Name",
  "submission_reason": "Why this skill should be included in EverySkill",
  "files": [
    {
      "path": "SKILL.md",
      "content": "<base64-encoded content of SKILL.md>"
    },
    {
      "path": "scripts/helper.py",
      "content": "<base64-encoded content>"
    }
  ]
}
```

**How to submit using Bash:**

```bash
# Base64-encode your SKILL.md
SKILL_CONTENT=$(base64 -i path/to/SKILL.md)

# Submit (single file example)
curl -X POST https://skills.every.to/api/agent-submit \
  -H "Content-Type: application/json" \
  -d "{
    \"password\": \"THE_PASSWORD\",
    \"skill_name\": \"your-skill-name\",
    \"submitter_name\": \"Your Name\",
    \"submission_reason\": \"Why this skill is useful\",
    \"files\": [{\"path\": \"SKILL.md\", \"content\": \"$SKILL_CONTENT\"}]
  }"
```

## Step 5: Check the Response

**Success response:**
```json
{
  "success": true,
  "pr_url": "https://github.com/EveryInc/everyskill/pull/123",
  "skill_name": "your-skill-name"
}
```

Tell your human the PR URL so they can track the review.

**Error response:**
```json
{
  "error": "Description of what went wrong"
}
```

Fix the issue described in the error and retry.

## What Happens After Submission

1. A GitHub pull request is created automatically
2. AI agents (Claude + GPT) review the skill for security issues
3. A human reviews and approves or requests changes
4. Once merged, the skill goes live at `https://skills.every.to`

## Tips for Good Skills

- **Be specific**: Skills that do one thing well get approved faster
- **Include trigger phrases** in your description so agents know when to use the skill
- **Test your skill** before submitting — make sure it works end-to-end
- **Avoid overly broad tool permissions** in `allowed-tools`
- **No secrets or credentials** in skill content

Raw SKILL.md