Publishing a Skill to Skola Marketplace

Skills written for a specific team often have hardcoded values — Jira URLs, Slack channel IDs, package names, repo names — that make them unusable by other teams. Before publishing, these values must be replaced with {{VARIABLE}} placeholders so each team can fill in their own values at install time.

This guide shows you how to port an existing skill and publish it.

What the Skola template requires

Every skill needs two files:

my-skill/
├── SKILL.md        ← skill instructions with {{VARIABLE}} placeholders
└── metadata.yaml   ← registry metadata + context variable definitions

metadata.yaml required fields

Each context variable needs at minimum:

VARIABLE_NAME:
  description: "What this value is"
  example: "an-example-value"
  required: true   # or false

Step 1 — Port your skill using AI

Copy the prompt below into your AI assistant (Claude, ChatGPT, etc.) along with your existing skill content. It will identify hardcoded values, replace them with {{VARIABLE}} placeholders, and generate the metadata.yaml for you.

I have an existing AI skill file that I want to publish to the Skola marketplace.
The skill needs to be portable across teams, so I need you to:

1. Read the skill content below carefully.

2. Identify ALL hardcoded team-specific values, including:
   - URLs (Jira, Slack, Sentry, internal tools)
   - IDs (Slack channel IDs, team IDs, group IDs, app IDs)
   - Keys (Jira project keys, API slugs)
   - Package/app names (e.g. com.company.app)
   - Repository/org names
   - Branch names that are team-specific
   - Credentials or token references
   - File paths that are project-specific
   - Any other value that would differ between teams

3. Replace each hardcoded value with a {{VARIABLE_NAME}} placeholder.
   - Use UPPER_SNAKE_CASE for variable names
   - Be consistent — the same value should use the same variable name everywhere
   - Keep {VERSION}, {MAJOR}, {MINOR}, etc. as-is — these are runtime values, not context variables

4. Produce a rewritten SKILL.md with:
   - Frontmatter at the top (name, description ≤120 chars)
   - All hardcoded values replaced with {{VARIABLE}} placeholders
   - Everything else unchanged

5. Produce a metadata.yaml with:
   name: <skill-name>
   version: "1.0.0"
   description: "<one line, max 120 characters>"
   long_description: >
     <2-3 sentence description>
   author:
     team: <team-name>
     contact: "<slack channel>"
   tags:
     - <relevant tags>
   compatible_with:
     - claude
     - opencode
   context:
     variables:
       VARIABLE_NAME:
         description: "<what this value is>"
         example: "<realistic example>"
         required: true/false
         default: "<default value>"  # only if optional

   For each variable:
   - Write a clear description (what it is, not just what it's called)
   - Provide a realistic example value
   - Mark as required: true unless there's a sensible default
   - Add default: only for optional variables that have a universal fallback

Here is the skill content:

---
<PASTE YOUR SKILL.md CONTENT HERE>
---

Step 2 — Save the output

Create a directory for your skill and save both files:

mkdir my-skill
# paste SKILL.md output → my-skill/SKILL.md
# paste metadata.yaml output → my-skill/metadata.yaml

Step 3 — Validate locally

skola publish skill/my-skill

Skola checks before opening the PR: - metadata.yaml exists and is valid YAML - Required fields (name, description, author, tags) are present - description is ≤ 120 characters - SKILL.md exists and is not empty boilerplate - All context variables have descriptions

Fix any errors reported, then re-run.

Step 4 — Publish

skola --yes publish skill/my-skill

This opens a PR to the marketplace. A reviewer will check: - Context variables have meaningful descriptions and examples - No hardcoded team-specific values remain in SKILL.md - The skill works for teams outside the original team

Tips

Check your own skill after porting — run a mental test: could someone from another team install this and have it work after filling in the prompts? If the answer is no, there's still a hardcoded value somewhere.

Scripts and helper files — if your skill relies on scripts (scripts/*.py), include them in the skill directory. They'll be published alongside SKILL.md.

Presets — if your team wants a one-click install with all values pre-filled, create a preset:

skola create preset my-team
skola publish preset/my-team

Then teammates can install with skola install skill/my-skill --preset my-team.

Author @AgiMaulana-GDT View all contributors →