agent-skills

Vendor-neutral Agent Skills in plain SKILL.md directories, readable by any agent.

Everything here is authored against the vendor-neutral stack only: AGENTS.md for instructions, Agent Skills for procedural knowledge, MCP for tools. No Claude Code plugin manifest, no marketplace, no .claude-plugin/ — a skill in this repo works the same in Codex, Cursor, Copilot, Gemini CLI, Zed and the rest.

Start here

Every skill has its own page, written for a person deciding whether to adopt it. If you read four, read these:

• plan-conveyor: design plans kept as plain files in the repo, with a status and a lifecycle, so the next session (and the next agent) picks up where this one stopped.
• research-library: cloned source kept outside your repos, so your agent reads the code instead of a web summary, and judges a dependency before you add it.
• session-harvest: the review to run before compacting or closing a session, which files what matters and finds what was left running.
• skill-fitness: whether your installed skills actually fire, measured rather than guessed.

Install

npx skills add TheodoreAD/agent-skills --global          # every skill, user-level
npx skills add TheodoreAD/agent-skills --global --skill plan-conveyor # just one

The skills CLI copies the skill into the canonical ~/.agents/skills/ hub (or the agent-specific directory for the agents that need one) and links each detected agent at it. Nothing else is required — no manifest to register, no repo to clone.

Or, without installing anything, point your agent at skills/<name>/SKILL.md and let it read the file directly.

Skills

Skill	Use it when	Scope
db-defaults-taudelta	Adding local persistence to a Python project — cache, relational, OLAP, documents, full-text or vector search, job queue, pub/sub, blobs, time series — and you want the default pick rather than an evaluation	Opinionated but general
invoke-task-conventions-taudelta	Adding, renaming or reviewing an inv <namespace>.<task>, and weighing what a rename actually costs across docs, CI and other repos	Opinionated but general
mcp-python-conventions-taudelta	The Python inside a stdio MCP server — where logs may go when stdout carries the protocol, what an exception at a tool boundary becomes, and the tool docstring as an LLM-facing contract	Opinionated but general
mcp-server-shipping	Building, installing or registering a personal MCP server — entry point, uv tool install from git instead of PyPI, claude mcp add scope	Opinionated but general
plan-conveyor	Capturing an idea, drafting a design, or tracking work-in-progress in a repo's plans/ directory — or, for a work repo that can't hold one, in the store outside it — and retiring a plan once it lands	Opinionated but general
polite-mcp-conventions-taudelta	Working in the *-polite-mcp repos — confirming before a first live mutating action against a real account, batching per-item decisions

Scope says how much of the skill is a convention anyone can adopt versus a personal preference: general is portable as written, opinionated but general picks one defensible convention out of several and commits to it, and personal depends on how one particular machine or repo family is set up. No skill here sends anything off the machine on its own. Every skill that ships a script or instructs a write outside your repo says what it reads, runs and writes, under the same heading in its SKILL.md — ## What this skill reads, runs and writes — and declares its environment requirements in the compatibility frontmatter field. In short: research-library writes only inside $RESEARCH_HOME; plan-conveyor writes plan files in your repo and in its stores ($PLANS_HOME and the sensitive sibling, for work repos that can't hold their own plans) and commits only to the store; session-bash-audit reads Claude Code's own transcripts and writes only a baseline you ask for; session-harvest's script writes nothing and its sweep reads transcripts, processes, listening sockets, container images and both stores; skill-fitness writes nothing but a baseline you name. plan-conveyor also describes pushing the shareable half of its store to a remote you configure — behind a content scan, and never the half holding employer or client work.

Python 3.11 or newer is the one requirement every script shares, run by your own python3 with nothing to install. Below it a script exits with a sentence saying so rather than a traceback.

Platform. Everything here was written on a POSIX machine. The scripts are stdlib-only Python, resolve their locations from $XDG_* first and fall back to %APPDATA% / %LOCALAPPDATA% on Windows, and the unit suite runs on a Windows CI leg as well as a Linux one — so what the tests cover is measured on both, and what they cannot cover is declared. Two skills assume more than a path. session-bash-audit measures POSIX-shell idioms (&&, ;, |, cd, sed -n), so it describes a Git Bash or WSL session and says nothing useful about a PowerShell one; session-harvest's sweep reads processes and sockets through ps/ss on Linux and PowerShell's Win32_Process/netstat on Windows, where the parsers are tested against documented output and have never seen a live machine. Both say so in their own bodies. A 0700 mode set at creation is accepted and ignored on Windows, so no skill here treats one as protection.

Layout

skills/<name>/
├── SKILL.md          # the skill itself — YAML frontmatter (name, description) + the instructions
├── references/       # rationale, prior art, evidence — read on demand, not loaded up front
└── scripts/          # anything the skill runs, when it has one

Each skill's references/ is where its reasoning lives — why this convention and not the obvious alternative, what went wrong the last time, which sources it was checked against. That is deliberately inside the skill rather than in a repo-level contributing/ tree, so a skill stays a self-contained unit that can be read, copied or vendored on its own.

License

MIT — see LICENSE.