Skip to content

Instantly share code, notes, and snippets.

@barseghyanartur

barseghyanartur/dot_agents.rst

Last active May 8, 2026 22:05
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save barseghyanartur/05fb8bd50969dde04c45794ede03ea05 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save barseghyanartur/05fb8bd50969dde04c45794ede03ea05 to your computer and use it in GitHub Desktop.
Download ZIP
blog: dot-agents: Skills for AI Agents
Raw
dot_agents.rst

dot-agents: Skills for AI Agents

Date: 2026-05-08 10:00
category:Tech
tags:python, ai, agents, tooling, open-source
summary:A collection of SKILL.md files that tell AI agents how to manage repos, validate docs, and handle Python projects.

AI agents do what you tell them. dot-agents is a public repository of SKILL.md files — plain-language procedures that agents like Claude Code or OpenCode can follow to do real work on a codebase.

Each skill has one job.

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment