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…
Creating a Validated Agent Skill with SKILL.md and Python Scripts
Artificial intelligence excels at understanding intentions, yet ambiguous instructions risk misinterpretation. The open-source how-to-create-a-skill-tutorial demonstrates a practical approach: rely on the agent to make judgments while employing small local scripts to enforce repeatable rules. This tutorial constructs the most basic version of that pattern: a commit-crafter skill comprising a SKILL.md file, a Python validator, and tests utilizing Python's standard library.
TL;DR An Agent Skill is a directory containing at least a SKILL.md file, where workflows and safety boundaries reside in the former, and exact validation occurs in the latter. The finished repository includes a skill that verifies Conventional Commit messages. This structure can be replicated for release notes, configuration generation, research reports, or any workflow with rules amenable to mechanical verification.
Prerequisites:
- Python 3.12 or newer for the repository's CI example
- Git for inspecting staged changes
- An agent compatible with the Agent Skills directory convention
- A shell, designed using POSIX syntax with files adaptable for Windows
- No stable release tag at the time of writing, with examples checked against the current main branch
Skill Directory Structure:
1. Create the skill directory with two scopes:
- A personal skill in the user skills directory
- A project skill within the repository for team review and installation
2. Required directory layout:
- commit-crafter/
- SKILL.md
- scripts/
- check_message.py
- references/
- conventional-commits.md
- examples.md
Only SKILL.md is mandatory, with scripts/, references/, and assets/ directories acting as templates for executable code, documentation, and reusable resources.
Writing the Agent-Facing Contract:
1. The frontmatter serves as the discovery contract, matching the directory name in lowercase letters, numbers, and hyphens.
2. The description should elucidate the capability and the user vocabulary triggering it.
3. The skill validates Conventional Commit messages, with two key boundaries:
- The skill may inspect staged work but cannot stage files
- Drafting a message and executing git commit are separate actions
Scripting Exact Rules:
1. The tutorial's design principle is: let the model decide, let the script verify, and let the script calculate.
2. The example validator exposes a validate(message) function and a CLI, using only the standard library for a package-free validation path.
3. Validation checks include subject line format, length, blank-line separator, and breaking-change footers.
4. The script returns deterministic violations, aiding the agent in providing useful next actions.
Testing Before Installation:
1. The repository includes unit tests for the validator, covering valid messages, malformed subjects, missing blank lines, breaking changes, warnings, and CLI exit codes.
2. Run the tests with `python examples/commit-crafter/tests/test_check_message.py -v`, ensuring all 16 tests pass on the current main checkout.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
