What is a SKILL.md?

A SKILL.md file is a Markdown document with a small YAML header. It defines a procedure in clear language: what the agent must do, what it must not do, and how to check the result. No vague suggestions — just concrete rules.

Skills are invoked by name:

@skill migrate-to-uv
/migrate-to-uv

What skills are included?

The repository ships six skills across three areas:

Repository governance

• repo-bootstrap — creates AGENTS.md and the initial skill structure in a new repository.
• skill-authoring — rules for writing new skills that don't conflict with existing ones.

Development workflow

• update-documentation — finds and fixes mismatches between code and docs, treating code as the source of truth.
• doc-codeblock-tests — runs Python code blocks in Markdown files through pytest-codeblock. If it's copyable, it must work.

Python project management

• migrate-to-uv — migrates from pip, setup.py, or requirements files to a uv-managed pyproject.toml, including Makefile and pre-commit templates.
• migrate-from-mypy-to-ty — replaces mypy with Astral's ty across dependencies, config, CI, pre-commit hooks, and docs.

The authority hierarchy

Skills are not all equal. Authority flows top-down:

AGENTS.md  →  existing SKILL.md files  →  new skills

A new skill must not contradict what is above it. This keeps agent behaviour consistent as the skill set grows.

Why I built it

Every project I maintain has the same recurring needs: keep docs in sync, test code examples, migrate tooling. Writing the same instructions in each repo's AGENTS.md is copy-paste work that eventually gets out of date.

dot-agents puts those instructions in one place — versioned, reusable, and readable by both agents and humans.

The repository is at github.com/barseghyanartur/dot-agents. MIT licensed.