Skip to content

DIY: build your own skill

A practical guide to authoring, testing, and publishing a skill or plugin marketplace for any coding agent (Claude Code, Codex, Gemini CLI, and others) — including what to do if a skill already exists for a different platform than the one you're using.

Building for a different platform? Check port-skill first

Before writing something from scratch, search this site (/search) for a skill that already does what you need — it may just exist for a different coding agent platform (Claude Code, Codex, Gemini CLI, Antigravity, Cursor, etc.) than the one you're using.

port-skill is a skill that ports a skill, plugin, or slash command between Claude Code, Codex, Antigravity, and Gemini CLI. If you find something close to what you need but built for the "wrong" platform, this is usually faster than writing your own from scratch.

  1. Install `port-skill` in the coding agent you already have it working in.
  2. Point it at the skill/plugin directory (or repo) you want to port, and tell it which platform to target.
  3. Review the generated output — conventions differ enough between platforms (tool names, frontmatter fields, permission models) that a quick read-through catches anything that didn't translate cleanly.
  4. Once it works, consider submitting the ported version here too (/submit) so the next person searching for it on that platform finds it.

Skill-building tools by platform

Most coding-agent platforms converged on a similar shape: a directory with a manifest (frontmatter or JSON) describing when the skill applies, plus instructions/scripts the agent loads on demand. The tooling for authoring one varies by platform:

Claude Code

Use the built-in skill-creator skill (bundled with Claude Code) to scaffold a new SKILL.md, get guidance on writing a good trigger description, and run evals against it. Anthropic's own example skills and the SKILL.md format are documented in anthropics/skills — a good reference for structure and frontmatter conventions.

Codex, Gemini CLI, Cursor, and others

Each platform has its own conventions for where skill/instruction files live (e.g. AGENTS.md, custom command/prompt directories) and its own scaffolding support, which changes faster than a static guide can reliably track. Check that platform's own docs for the current convention, or — per the section above — port an existing Claude Code skill with port-skill rather than starting from an unfamiliar format.

Publishing & deployment

Git repo basics

  • One skill (or one tightly-related family of skills) per repo — keeps versioning and issue tracking clean.
  • Commit the skill's manifest/frontmatter file at a predictable path so tooling (including this site's submission auto-fill) can find it without guessing.
  • Include a license file — an unlicensed public repo is technically "all rights reserved," which discourages adoption.

Set the right GitHub topic tags

A repo with a good description but no topics is invisible to topic-based discovery tools (including the one that populates this site) — `gh search repos --topic <topic>` only finds repos that actually carry that topic. Set these via gh repo edit --add-topic <topic> or the repo's Settings page:

  • Claude Code skill: claude-code-skill, claude-skills
  • Claude Code plugin: claude-code-plugin
  • Codex skill: codex-skill
  • Gemini CLI skill: gemini-cli-skill
  • Any of the above: always add agent-skills too — it's the cross-platform umbrella tag some discovery tooling searches on directly instead of every platform-specific tag individually.
  • Multi-platform project? Add every platform-specific tag that applies, plus agent-skills once.

If you use git-release to publish, it checks and sets these topics automatically as part of its release workflow.

README.md

  • Lead with what the skill does and when it triggers — the first paragraph is what most people actually read.
  • Show a real installation command and a real usage example, not just a feature list.
  • Document any required permissions, API keys, or external services up front — surprises here cost trust.

Versioning

  • Use semantic versioning (MAJOR.MINOR.PATCH) in the manifest — bump MAJOR for breaking changes to the skill's interface/behavior, MINOR for new capability, PATCH for fixes.
  • Keep a CHANGELOG.md — there's no shared cross-marketplace update-notification convention today (see findsafeskills's own origin story), so a changelog is the most reliable way for adopters to know what changed.
  • Tag releases in git (`git tag v1.2.0`) so a specific version can be pinned or referenced.
  • Consider a versions.json file (a pattern borrowed from Obsidian's community plugins) — a small structured JSON mapping each version to a short changelog note. A CHANGELOG.md is fine for humans, but a structured file lets tooling (including findsafeskills's own crawler) read your version history programmatically instead of trying to parse prose — this is exactly the kind of shared convention that's missing across the coding-agent skill ecosystem today, and findsafeskills will surface this history on a listing's detail page when present.

Getting into a marketplace

  • For Claude Code, add a `.claude-plugin/marketplace.json` (for a collection) or `plugin.json` (for a single plugin) at the repo root — this is also what this site's submission form auto-detects.
  • Submit it here (/submit) so it's discoverable by topic/function search, not just by people who already know your repo name.
  • Consider a PR to a well-known awesome-list for extra visibility — several are indexed on this site already.

Things to consider when building your skill

  • Scope it tightly. A skill that does one thing well and triggers reliably beats one that tries to cover many loosely-related cases and triggers inconsistently.
  • Write the trigger description for the agent, not the human. The description is what decides whether your skill activates at the right moment — be concrete about when it applies and when it doesn't.
  • Test the failure paths, not just the happy path. What happens when a required tool/API is unavailable, or the input is malformed?
  • Be explicit about permissions and side effects. If the skill can write files, call external APIs, or spend money, say so clearly in the README — this is exactly the kind of thing that erodes trust if discovered after the fact rather than disclosed up front.
  • Don't over-engineer for hypothetical futures. YAGNI applies to skills too — build for the use case in front of you, and extend later if a real second use case shows up.
  • Keep it DRY across your own skills. If you find yourself copy-pasting logic between two skills you maintain, that's usually a sign it belongs in a shared helper script or library both skills reference.

Best-practices checklist: findable, trustworthy, maintainable

The habits below make a skill easier to find, easier to trust, and easier to keep working. Where findsafeskills itself uses something, we say so.

Make it findable

  • Write the repo description (the one-line "About" text on GitHub): what the skill does and for which agent. When a manifest has no description of its own, this is what we fall back to.
  • Set repo topics — the platform tags plus agent-skills (details under Publishing above). Topic search is how most discovery tooling, including ours, finds repos.
  • Put a clear description in the manifest (SKILL.md frontmatter, plugin.json, or marketplace.json). It should say when to use the skill, written so an agent can decide — and it becomes your listing's description here.
  • Add a standard LICENSE file that GitHub recognizes (MIT, Apache-2.0, and so on). Search here can filter to listings with a recognized license, so a missing or unrecognized one hides you from those searches.
  • Keep it maintained. Search can also filter to recently updated repos; a skill untouched for a year looks abandoned, even if it works.

A solid README.md

  • Open with one paragraph on what it does and when it triggers. If there is no manifest description and no repo description, we derive the listing text from this paragraph.
  • Give an install command and a usage example that can be pasted and run as written.
  • State requirements, permissions, network calls, files it writes, and any cost up front, plus how to uninstall it.
  • Link the CHANGELOG, the license, and how to report a problem.

Version it and keep a changelog

  • Use semantic versioning in the manifest and keep a CHANGELOG.md; tag each release (v1.2.0). When a listed repo's manifest version changes, our nightly check records it in the site's public changelog feed.
  • Keep one source of truth for the version, and make anything executable report that same number with --version.
  • Optionally add a versions.json (see Versioning above) so tools can read your history without parsing prose.

If your skill ships scripts, CLIs, or an MCP server

Agents and people both learn how to call a tool by asking it. Give every executable these, where they make sense:

  • --help: usage, every option, a couple of examples, and what the exit codes mean.
  • --version: print the name and version (matching the manifest), then exit 0.
  • --dry-run: for anything that writes or deletes files, calls a paid or external API, or sends data somewhere, show exactly what would happen without doing it. (Spelled --dry-run in git, rsync, and npm; follow that convention.)
  • --yes / --no-input so it can run without prompting when an agent drives it, and --json when its output is meant to be parsed.
  • Exit non-zero on failure, make repeat runs safe where you can, take secrets from environment variables rather than arguments, and never print them.
$ mytool --version
mytool 1.2.0
$ mytool sync --dry-run
Would write 3 files: notes/a.md, notes/b.md, notes/c.md
No changes made (dry run).

Stay on the right side of safety scans

Our safety scan reads a listing's manifest and README. Authors can avoid most false alarms, and earn trust, by:

  • Never committing real keys or tokens, and using obviously fake placeholders in examples.
  • Not telling people to pipe a download straight into a shell: download it, say how to verify it, then run it.
  • Avoiding hidden characters and encoded blobs in instructions; if you need one, explain what it is next to it.
  • Keeping instructions about the task, not about overriding the agent's rules.
  • Asking for the least access needed (only the tools and permissions the skill uses), pinning dependency versions, and committing a lockfile.
  • Adding a SECURITY.md that says how to report a vulnerability.

If a finding on your listing is a false positive, sign in and dispute it from the listing page.

And finally

  • Test the skill against realistic prompts and keep those examples in the repo so changes can be re-checked.
  • Respond to issues; an open, answered issue tracker is a trust signal in itself.