Build a Tested Agent Skill with SKILL.md and Python Scripts

AI agents are good at interpreting goals, but prose instructions are a weak place to enforce exact rules. If a skill says "keep the commit subject short" or "never commit without approval," an agent can still misunderstand the boundary. The open-source how-to-create-a-skill-tutorial shows a practical split: let the agent make judgments, and let small local scripts validate repeatable rules. This tutorial builds the smallest useful version of that pattern: a commit-crafter skill with a SKILL.md file, a Python validator, and tests that run with the Python standard library. TL;DR An Agent Skill is a directory containing at least SKILL.md . Put the workflow and safety boundaries in that file. Put exact validation in a script. Keep the script deterministic, return meaningful exit codes, and run it before presenting the result to a user. The finished repository's example skill validates Conventional Commit messages. You can copy the same structure for release notes, config generation, research reports, or any other workflow with rules that can be checked mechanically. Prerequisites You need: Python 3.12 or newer for the repository's CI example. Git if you want the skill to inspect staged changes. An agent that supports the Agent Skills directory convention. A shell. The commands below use POSIX syntax; the files themselves are also designed for Windows. The project has no stable release tag at the time of writing. The examples and commands below are checked against the current main branch. Read the Agent Skills specification if your client uses a different discovery directory. 1. Create the skill directory The repository documents two useful scopes. A personal skill belongs in your user skills directory. A project skill belongs in the repository so a team can review and install it with the project. mkdir -p .agents/skills/commit-crafter/scripts mkdir -p .agents/skills/commit-crafter/references The required layout is simple: commit-crafter/ |-- SKILL.md |-- scripts/ | `--