Open source

dot-skills

One .skills/ folder as the source of truth for agent skills, linked out to every coding agent that reads them. Edit a skill once, in one place, and Claude Code, Cursor, GitHub Copilot, Windsurf, Codex CLI, and Gemini CLI all see the update immediately.

dot-skills is the successor to Agent Kit. Anthropic's SKILL.md format is now an open standard read natively by every major coding agent, so format conversion is no longer the problem - the problem is that each agent looks for skills in a different folder. dot-skills solves exactly that, with symlinks.

GitHub dot-skills

Quick start

One command in any project

Creates .skills/, installs two starter meta-skills, and links them into whichever agents you pick.

npx dot-skills init

# Install a skill from any repo with a .skills/ folder
npx dot-skills add levi-putna/dot-skills/creating-skills

# See what's available in a repo before installing
npx dot-skills list owner/repo

# See what's installed, where it's linked, and dependency status
npx dot-skills installed

# Check declared env vars and CLI tools for everything installed
npx dot-skills doctor

How it works

One real copy, symlinked everywhere

dot-skills keeps exactly one real copy of each skill in .skills/ at your project root, and symlinks it into whichever agent folders you actually use. On filesystems without symlink support it falls back to copying and re-copies on dot-skills link.

.skills/my-skill/

SKILL.md - the one real copy

npx dot-skills link

.claude/skills/my-skill

symlink → .skills/my-skill

.cursor/skills/my-skill

symlink → .skills/my-skill

Supported agents

Where each agent looks for skills

Agent	Project skills dir	Global skills dir
Claude Code	.claude/skills/	~/.claude/skills/
Cursor	.cursor/skills/	~/.cursor/skills/
GitHub Copilot	.github/skills/	~/.copilot/skills/
Windsurf (Cascade)	.windsurf/skills/	~/.codeium/windsurf/skills/
OpenAI Codex CLI	.codex/skills/	~/.codex/skills/
Gemini CLI	.gemini/skills/	~/.gemini/skills/

Every command accepts --global to operate on ~/.dot-skills/skills/ and each agent's global directory instead of the current project. Non-interactive flags for scripts and CI: --agents=claude,cursor, --all, and --skills=a,b.

Commands

The full CLI

Command	Does
dot-skills init	Create .skills/ in the current project, install the two starter skills, and link into your chosen agents.
dot-skills add <owner/repo>[/skill][#ref]	Install one or more skills from a repo's .skills/ folder.
dot-skills list [owner/repo]	List skills and descriptions in a repo, or (no args) in the local .skills/. Entries you already have installed are marked, matched by id.
dot-skills installed	Show installed skills: source, linked agents, and dependency status.
dot-skills link [skill...]	(Re)create symlinks for skills already in .skills/ - e.g. after adding a new agent to the project.
dot-skills remove <skill>	Delete a skill from .skills/ and unlink it from every agent it was linked into.
dot-skills doctor	Check every installed skill's declared dependencies against the current environment.

Skill format

A skill is a folder under .skills/

text

.skills/
  my-skill/
    SKILL.md       # required - frontmatter + instructions
    README.md      # optional - human-facing docs
    references/    # optional - long-form docs loaded only when needed
    scripts/       # optional - helper scripts
    assets/        # optional - templates/files used in output

The frontmatter carries the name, a description that tells agents when to reach for the skill, and an optional dependencies list of environment variables and CLI tools the skill needs. dot-skills doctor re-checks those against your shell at any time.

yaml

---
name: my-skill
id: 56824965-a4de-4b74-bf8d-5d04b598de77
author: Your Name
repo: https://github.com/your-name/your-skills-repo
description: >-
  What it does, and when an agent should reach for it. This is the only
  thing most agents see before deciding whether to load the skill, so be
  concrete about trigger phrases.
dependencies:
  - type: env
    name: OPENAI_API_KEY
    required: true
    description: Needed to call the OpenAI API.
    instructions: >-
      Create a key at https://platform.openai.com/api-keys, then
      export OPENAI_API_KEY=sk-... in your shell profile.
  - type: cli
    name: jq
    required: false
    instructions: Install via `brew install jq`.
---

Markdown instructions for the agent go here.

id is a UUID generated once when the skill is first created and never changed afterward - the skill's stable identity, independent of its name or which repo a copy ends up in. dot-skills list uses it to mark entries you already have installed, even if a copy got renamed. It's optional but recommended.

author and repo are optional plain-text attribution: who wrote the skill, and a link back to its canonical, maintained source. Unlike the per-install provenance tracked in the lockfile, they travel with the file itself - they stay attached even when a raw SKILL.md gets copied around by hand.

Bundled skills

Two starters, three more on offer

Two meta-skills ship with dot-skills itself: creating-skills and importing-skills. They're installed into .skills/ on init, and globally to ~/.dot-skills/skills/ the very first time dot-skills runs on a machine - any command, not just init. Because every consuming project ends up carrying a copy, dot-skills list deliberately never shows them, matched by their fixed id even if a copy was renamed.

The dot-skills repo's own .skills/ folder ships three more, opt-in rather than auto-installed: reviewing-code (defect-first review of a diff or PR that reports findings and never edits unilaterally), checking-release-readiness (audits code and docs for drift - stale README claims, broken links, undocumented flags), and preparing-a-release (runs both, proposes a semver bump, updates the changelog, and hands back the exact npm publish command without ever running it itself).

npx dot-skills add levi-putna/dot-skills/reviewing-code
npx dot-skills add levi-putna/dot-skills/checking-release-readiness
npx dot-skills add levi-putna/dot-skills/preparing-a-release

Publishing

Any repo with a .skills/ folder is a source

There is no registry to publish to. Any public GitHub repo with .skills/<name>/SKILL.md folders at its root works as an installable source - including this site's own repo and the dot-skills repo itself.

npx dot-skills add your-name/your-skills-repo
npx dot-skills list your-name/your-skills-repo

Skills

Browse the skills this site runs on

This site's skills

The twelve skills that build twistedbrackets.com - writing, fact-checking, audio, video, and imagery pipelines - stored in the repo's .skills/ folder and installable with dot-skills.

Development harness skills

The original spec-driven development harness collection: design docs, change control, TDD build loops, e2e verification, and shipping.

Coming from Agent Kit? The old docs are still at /agent-kit, and the dot-skills README covers everything above in more depth.