Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.selftune.dev/llms.txt

Use this file to discover all available pages before exploring further.

​
The journey

Most skills start as something you built for yourself. At some point, you realize it could help others. The question is: how do you get it from your machine to theirs, and how do you know it works for them? 
Personal skill → Tested skill → Published skill → Community-improved skill

​
Making a skill shareable

If you are publishing a skill others will install, read the Skill Creator Playbook alongside this guide. It covers the before-ship versus after-ship loop in more detail. For the concrete shipping sequence from package creation through safe deploy, use Create, Test, and Deploy a Skill. Before sharing, check these basics:

​
1. Follow the spec

Your skill should conform to the agent skills spec so it works across compatible agents, not just the one you built it for: 
---
name: my-skill           # lowercase, hyphens only, 1-64 chars
description: >           # 1-1024 chars, what + when
  Do X and Y. Use when the user needs to...
compatibility: Requires Node.js 18+    # optional: environment needs
---
Validate your skill structure: 
# Using the spec's reference library
npx skills-ref validate ./my-skill

# Using selftune's lifecycle-first draft verification
selftune verify --skill-path ./my-skill

​
2. Keep it self-contained

A shareable skill should work without assumptions about the user’s environment:
  • Scripts should declare their own dependencies (see Using Scripts)
  • References should be bundled, not linked to local paths
  • Compatibility field should list any requirements (runtimes, tools, API keys)
# Good: explicit about what's needed
compatibility: Requires Python 3.11+ and uv. Optional: OPENAI_API_KEY for enhanced analysis.

# Bad: silent assumptions
# (no compatibility field, but scripts need Python, uv, and an API key)

​
3. Test beyond your own usage

Your skill works for you because you wrote the description to match how you talk. Other people talk differently. 
# Generate evals from your sessions
selftune eval generate --skill my-skill

# Generate cold-start evals to cover broader language patterns
selftune eval generate --skill my-skill --auto-synthetic --skill-path path/to/SKILL.md

# Verify the draft package through the lifecycle surface
selftune verify --skill-path path/to/my-skill

# If verify asks for package-level proof, these are the package steps it will send you to
selftune create replay --skill-path path/to/my-skill --mode package
selftune create baseline --skill-path path/to/my-skill --mode package

# Ship once verify turns green
selftune publish --skill-path path/to/my-skill
See Testing Skill Triggers for the full testing workflow.

​
Distribution channels

​
npx skills (agent skills ecosystem)

The standard way to install skills across compatible agents: 
# Install from a GitHub repo
npx skills add your-org/your-skill

# Install from the skills registry
npx skills add skill-name
Browse available skills at skills.sh — the community registry for agent skills.

​
GitHub

The simplest distribution: push your skill directory to a public repo. Users install with: 
npx skills add your-github-username/your-repo
Structure your repo so the skill is discoverable: 
your-repo/
├── SKILL.md
├── scripts/
├── references/
└── README.md         # For humans browsing GitHub
Or bundle multiple skills: 
your-repo/
├── skill-one/
│   └── SKILL.md
├── skill-two/
│   └── SKILL.md
└── README.md

​
selftune registry

Skills published to the selftune registry get additional benefits:
  • Contributor signals — aggregated (anonymized) trigger and grading data from users who opt in
  • Evolution suggestions — selftune proposes description improvements based on contributor signal patterns
  • Badge — embeddable health badge for your README
# Publish to the selftune registry
selftune registry push my-skill
View contributor signals in selftune Cloud at /cloud/signals.

​
Getting feedback from users

The hardest part of sharing skills is knowing how they perform for others. selftune’s contributor-signal system solves this:

​
How it works

  1. A user installs your skill and uses it normally
  2. selftune observes their sessions locally (all data stays on their machine)
  3. If they opt in, anonymized trigger/grade data is shared back via creator-directed relay signals
  4. You see aggregated results — which queries succeed, which fail, which are missed

​
As a skill author

# Open the signals dashboard
# https://selftune.dev/signals

​
As a skill user

# Opt in to sharing privacy-safe creator-directed signals for a skill
selftune contributions approve their-skill
Contribution data is anonymized — only query patterns, trigger outcomes, and grades are shared, never raw user content.

​
The contributor signal improvement cycle

When enough users contribute data, selftune can run evolution against contributor patterns: 
1. Author publishes skill with description X
2. 50 users install and use it
3. 12 users contribute anonymized session data
4. selftune detects that users say "pitch deck" but description only matches "presentation"
5. selftune proposes evolved description
6. Author reviews and deploys
7. All users benefit from the improved trigger coverage
This is the core value proposition: skills that get better the more people use them.

​
Further reading

Skills Registry

Browse and publish skills in the community registry.

Agent Skills Spec

The open standard your skills should conform to.

selftune Cloud

Team dashboards and contributor signal features.

Iteration Loop

The feedback loop that powers contributor-signal improvement.