PTENES
MODULE 5.2 · END OF COURSE

🚀 Publish, Version, and Measure

The skill is written and tested. Now take it to the world: repo structure, versioning via git, discovery on skills.sh, trigger evals, security, and the lifecycle that never ends.

6
Topics
43
Minutes
Advanced
Level
Practice
Type
1

📁 Repository structure for publishing

For a skill to be installable and indexable, the repo needs to follow the convention: a folder skills/ at the root, and inside it each skill with its own SKILL.md plus optional resources. Outside this structure, the CLI and skills.sh find nothing.

layout for a publishable repo:

meu-repo-de-skills/
├── README.md
└── skills/
    ├── react-component-scaffold/
    │   ├── SKILL.md          # frontmatter + corpo (<500 linhas)
    │   ├── scripts/          # scripts executáveis sob demanda
    │   │   └── scaffold.sh
    │   ├── references/       # docs longas carregadas só quando preciso
    │   │   └── patterns.md
    │   └── assets/           # templates, imagens
    │       └── component.tpl
    └── git-commit-style/
        └── SKILL.md

Progressive disclosure in 3 levels

①

Metadata (name + description)

~100 words, always in context. That's the trigger. Permanent cost — keep it lean.

②

SKILL.md body (<500 lines)

Loaded only when the skill is triggered. The actual instructions.

③

Bundled resources

scripts/, references/, assets/ — read on demand, when the body points to them.

💡 Repository tip

A single repo can host multiple atomic skills—that’s how vercel-labs/skills e anthropics/skills work. The installer chooses the repo (owner/repo), and the CLI pulls the skills from the folder skills/.

2

🔀 Version with git

Skills live in git and are installed as symlinks, not copies. This changes everything: when you give git push and the user runs npx skills update, your new version propagates to everyone. You don’t control just your repo—you control the behavior of those who installed it.

1

Commit + push

Git is the source of truth. Edit SKILL.md, commit with a clear message, and push. Done—the published version has changed.

2

Symlink on the user's side

By default, the skill is symlinked from the cloned repo. There’s no frozen copy—the installation points to the source.

3

npx skills update

One command fetches the latest versions of all installed skills. That’s what keeps the ecosystem alive—and what calls for your care.

✗ Careless versioning

  • ✗Push directly to main without testing the trigger
  • ✗Change the description and break anything that depended on it
  • ✗No changelog—nobody knows what changed

✓ Responsible versioning

  • ✓Run evals before the push
  • ✓Documented trigger changes
  • ✓CHANGELOG.md with each release

💡 The power of the symlink

The symlink is why skills update for free — but also why a bad push affects everyone immediately. Treat the skills repo’s main branch like production.

3

🌐 Appear on skills.sh

O skills.sh indexes public repos and shows the install count as a social metric—the signal of discovery and trust. But the numbers are stark: of the 39.366 skills of the catalog (5.075 source repos, 53,9M combined installs), the distribution follows a brutal power law.

60,2%
<100 installs
30,8%
100–999
7,7%
1k–9,9k
0,3%
100k+ (131 skills)
60,2% 30,8% 7,7% 1,1% 0,3% <100 100k+

The top 100 = 43,7% of all installs

The concentration is extreme. find-skills alone has 1.802.925 installs (vercel-labs). frontend-design 488.299 (anthropics), vercel-react-best-practices 443.261. Being at the top is rare—but install count is still your best discovery signal.

The lesson: don’t chase the leaderboard. Solve a real problem well, with clear naming and a clear description, and people will find you within your niche.

4

📊 Measure triggering

The question that separates amateur skills from professional ones: Does the description trigger in the right cases? You don’t guess — you measure, with trigger evals. List queries that should trigger, queries that shouldn’t, and the tricky near-misses.

trigger eval (example):

skill: react-component-scaffold

should_trigger:
  - "cria um componente de card"
  - "preciso de uma nova tela de login em React"
  - "refatora esse JSX em componentes"

should_not_trigger:
  - "qual a sintaxe de um for em Python?"
  - "explica o que é o virtual DOM"   # near-miss: fala de React mas não pede componente

# meça: % de acerto em cada lista

✓ Should-trigger

The cases where the skill needs to show up. If it disappears here, your description is too vague or too timid.

Failure here = under-triggering (low recall).

✗ Should-not-trigger

The cases where it needs to stay quiet. Near-misses (they touch on the topic but not the trigger) are the most revealing.

Failure here = wrong trigger (low precision).

💡 The trigger-tuning loop

Run the evals → see where it failed → adjust only the description (not the body) → run again. The near-misses tell you exactly which words to add or remove. Triggering is the KPI almost nobody measures—and what most determines whether a skill is useful.

5

🛡️ The principle of no surprises

Skills run with the user’s trust. The golden rule: the skill shouldn’t do anything the user wouldn’t expect when reading the description. No deleting files, sending data outside, or running destructive commands as a silent side effect.

✗ Surprise (breaks trust)

  • ✗"format the code" and while you're at it, do git push --force
  • ✗Script in scripts/ that sends hidden telemetry
  • ✗rm -rf hidden in a “cleanup” step
  • ✗Accesses secrets without the user asking

✓ No surprises (reliable)

  • ✓Does exactly what the description promises
  • ✓Destructive actions require explicit confirmation
  • ✓Least privilege: only touches what it needs
  • ✓Auditable and transparent scripts

Why this is existential for the ecosystem

Because skills are installed via symlink and updated with one command, a malicious or careless repo can affect many people at once. The reputation of all of skills.sh depends on every author respecting the no-surprises principle. Audit your own resources as if you were a wary user installing them.

6

♻️ The lifecycle

Publishing isn’t the end—it’s the start of the cycle. The skill is a living product: you publish → monitor installs and feedback → iterate in the description and body → republish. And repeat. The catalog of 53.9M installs is made up of skills that have iterated.

🚀 📈 🔧 Publish Observe Iterate
🚀

Publish

Repo with a skills/ folder, push to GitHub, indexing on skills.sh. v1 is out in the world.

📈

Observe

Track install count, issues, and how the skill behaves in real-world use. The data tells you where the trigger fails and where the body is confusing.

🔧

Iterate

Refine the description based on real near-misses, trim the body, extract repeated scripts. Commit, push, and the cycle starts again.

💡 Where to learn more

You’ve completed all 5 tracks: overview, quality, anatomy, the creation loop, and mental models. The next step is to publish your first real skill — and keep improving it. Find more courses, examples, and the community at INEMA.CLUB.

✅ Module Summary · End of Course

✓
Repo structure — skills/ folder with SKILL.md + scripts/ references/ assets/, progressive disclosure in 3 levels
✓
Version via git — symlinks make npx skills update propagate everything; treat main as production
✓
skills.sh and install count — power law: top 100 = 43.7% of installs; solve a real problem in your niche
✓
Measure triggering — should-trigger / should-not-trigger / near-miss evals refine the description
✓
Principle of no surprises — the skill never does what the description doesn't promise; least privilege
✓
Lifecycle — publish → observe → iterate, always; a skill is a living product

You’ve completed the course! 🎉

Five tracks, from the ecosystem overview to publishing and measurement. Now it's your turn: choose a repeatable workflow from your day-to-day, write your first skill, publish it, and iterate. Keep learning on the portal.

← Back to Track 5 Next → 5.3