The Agent Skill Model for Python Teams
An AI coding assistant already knows how to write a FastAPI route, add type hints, or wire up a Celery task in general - that knowledge came from its training, not from your team.
What it doesn't know by default is which Python version your services actually run, whether your team standardizes on Pydantic v2 patterns or still carries v1 code, which logging fields are mandatory, or which shortcut a past incident taught everyone never to take again. An Agent Skill is how a team encodes that gap - the specific, local, version-pinned decisions - into something an assistant can be handed at the exact moment it needs them, instead of hoping a prompt happens to mention all of it.
This page is the model underneath the individual skill pages in this section - FastAPI Expert Skill, pytest / Testing Skill, Type-Hinting Skill, Packaging & Publishing Skill, and the rest each look like separate skills, but they're all built from the same three parts described here.
Summary
- An Agent Skill is a structured, invocable contract - a
SKILL.mdfile - that scopes an AI assistant's default behavior to one team's specific conventions for one recurring Python task. - Insight: Raw prompting drifts toward an assistant's generic training defaults - outdated Pydantic v1 patterns, unpinned Python versions, sync code inside async routes - and a skill closes that gap at the point of use, not after the fact in review.
- Key Concepts: trigger, decision domain, input/output contract, guardrail, stack pin, verifiable output.
- When to Use: Any recurring Python task where you'd otherwise repeat the same conventions in every prompt - scaffolding a FastAPI service, writing pytest suites, packaging for PyPI, reviewing a PR for type-hint gaps - and where a wrong default has a real cost.
- Limitations/Trade-offs: A skill narrows risk, it doesn't eliminate it - guardrails reduce the chance of a bad default, but they don't replace CI, code review, or the human cookbook page a skill's guidance is drawn from.
- Related Topics: SKILL.md structure, decision domains, guardrails vs. review, human documentation as the source of truth.
Foundations
A decision domain is the scope a single skill owns - "scaffold a FastAPI service," "review a PR for type-hint coverage," "package a library for PyPI," "build a data pipeline" - and the first rule of the model is that one skill covers exactly one domain. A skill that tries to cover everything stops being a specific contract and becomes a vague, general-purpose prompt with extra formatting, which defeats the point.
A skill is invoked at a trigger - a moment in the work where its specific guidance applies, rather than sitting passively as background reading the way a wiki page does. "New microservice in the monorepo," "we're standardizing type hints before a mypy rollout," "this PR touches the training pipeline" are all triggers; the skill exists specifically to be reached for at that moment, not browsed ahead of time.
A useful analogy is a lab protocol handed to a new research assistant on their first day. It doesn't re-teach them how Python or statistics work, they already know that. It tells them exactly which conventions apply here: which random seed to fix, which validation split to use, which shortcut a past experiment proved was a mistake. That's the difference between a skill and a tutorial - a tutorial builds general knowledge; a skill applies specific, local knowledge at the exact moment it's needed.
Mechanics & Interactions
Every skill is built from three parts, and a SKILL.md file missing any one of them is closer to a doc than a skill:
- Triggers - the conditions under which an assistant (or a human) should reach for this skill instead of general knowledge. pytest / Testing Skill's triggers include "new module has no test coverage" and "CI flagged a flaky test" - specific, recognizable conditions, not "when tests seem off."
- Input/output contract - what the skill needs to be handed (service name, sync vs. async database, auth model) and what it produces (a
pyproject.toml, router modules, a test suite). This is what makes a skill's output checkable rather than just plausible-sounding. - Guardrails - explicit boundaries on what the assistant should never do inside this domain, regardless of how a prompt is phrased. Guardrails are where hard-won operational lessons get encoded directly, rather than trusted to be remembered.
trigger recognized ──▶ skill loaded ──▶ guardrails applied ──▶ output produced
│ │ │ │
"new FastAPI stack pin + "Pydantic v2 only, pyproject.toml,
service needed" decision tree never sync DB in routers, tests,
for this domain an async route" verification cmds
The stack pin - the exact Python, framework, and library versions a skill assumes - exists because an assistant's training data spans years of API history, and without an explicit pin it has no reliable way to know which era of guidance is current for your codebase right now. FastAPI Expert Skill states its pin (Python 3.14, FastAPI 0.115+, Pydantic 2) in its header for exactly this reason; a skill without one is implicitly trusting the model to guess correctly, which it often won't.
The output side of the contract matters as much as the input side: skill outputs in this section are required to end in verifiable commands - uv run pytest, ruff check, mypy or pyright, a curl against a health route - specifically so a human isn't left evaluating an assistant's prose confidence, but can run something objective and see whether it actually passes.
Advanced Considerations & Applications
A skill's guardrails narrow the space of likely mistakes, but they are not a substitute for review - the model producing output under a skill's guidance is still the same underlying model, applying the same reasoning process, just with better local context to reason from. Treating skill output as pre-approved because it followed a contract is a mistake; the contract exists to make output checkable, not to make checking optional.
Skills also age, the same way any version-pinned artifact does. A skill written against Pydantic v1 and Python 3.10 becomes actively misleading once a codebase moves to Pydantic v2 and Python 3.14, not neutral, actively wrong, because it will confidently apply outdated patterns (.dict() instead of model_dump(), no structural pattern matching) to a newer stack.
There's a real security dimension specific to skills that scaffold code: a guardrail like "never commit real secrets, .env.example placeholders only" is only valuable if it's explicit, because a generic assistant asked to "add config for a database connection" has no way to know your org's convention is a secret manager rather than a literal connection string in a file.
Python's split between application engineering and data/ML work adds a domain-specific wrinkle other ecosystems handle less often: a skill scoped to "build a data pipeline" or "train a PyTorch model" often needs guardrails around reproducibility (fixed seeds, pinned dataset versions, logged hyperparameters) that a web-service skill has no equivalent for, which is why this section keeps those as clearly separate decision domains rather than one generic "write Python" skill.
Skills are deliberately positioned as a layer on top of existing human documentation, not a replacement for it - each skill page in this section states directly that the corresponding human cookbook pages (fastapi/, pytest/, packaging-publishing/) remain authoritative, and a skill's job is to route an assistant to the right convention at the right moment, not to become the new source of truth itself.
| Approach | Strength | Weakness | Best Fit |
|---|---|---|---|
| Raw prompting, no skill | Fast to start, no maintenance overhead | Drifts to generic training defaults; conventions repeated (or forgotten) every time | One-off, low-stakes tasks with no house convention to violate |
| Agent Skill (this model) | Encodes specific, version-pinned conventions; reusable across the team | Needs authoring and upkeep as the stack evolves | Recurring, decision-domain-scoped tasks with a real cost to getting defaults wrong |
| Full agent autonomy, no human review | Fastest iteration loop, no human bottleneck | No objective check on output; guardrails alone don't catch everything | Rarely appropriate for production Python changes, even skill-guided output benefits from review |
Common Misconceptions
- "A skill is just documentation written for a bot instead of a person." A skill is an operational contract with defined inputs, outputs, and guardrails meant to be invoked at a specific trigger, a doc is meant to be read and understood, a skill is meant to be executed against.
- "Once a skill exists, the human cookbook pages it references are redundant." The opposite is true by design - skills explicitly defer to cookbook pages as the authoritative source, routing an assistant to the right convention rather than duplicating it.
- "Following a skill guarantees correct code." Guardrails narrow the likely mistakes within a decision domain; they don't remove the need for CI, tests, and human review of the actual output.
- "Any useful prompt can be turned into a skill by saving it." A prompt becomes a skill only once it has explicit triggers, an input/output contract, and guardrails, without those, it's a saved prompt, not an invocable contract.
- "One general 'write good Python' skill covers everything a team needs." A web-service skill and a data-pipeline skill need different guardrails entirely (async correctness versus reproducibility), which is exactly why this section keeps decision domains narrow instead of merging them.
FAQs
What is an Agent Skill, in one sentence?
A structured SKILL.md contract - triggers, inputs/outputs, guardrails, and a stack pin - that scopes an AI assistant's behavior to one team's specific conventions for one recurring Python task.
How is a skill different from a normal documentation page?
Documentation is written for a human to read and internalize over time; a skill is written to be invoked at a specific trigger and to produce a checkable output. A skill without triggers, an input/output contract, and guardrails is functionally just a doc with extra formatting.
Why can't I just describe my team's Python conventions in the prompt every time?
You can, but it doesn't scale - conventions get forgotten, phrased inconsistently, or omitted under time pressure, and the assistant quietly falls back to its generic training defaults whenever a specific instruction is missing. A skill exists precisely so that context doesn't depend on someone remembering to type it correctly every time.
What are the three parts every skill needs?
Triggers (when to invoke it), an input/output contract (what it needs and what it produces), and guardrails (explicit boundaries on what it should never do). A SKILL.md missing any of the three is closer to a passive doc than an invocable skill.
Why does every skill pin an exact stack version in its header?
Because an assistant's training data spans multiple years of Python and framework history, and without an explicit pin it has no reliable way to know which era of guidance currently applies to your codebase, the pin removes that ambiguity outright.
What's a "decision domain," and why should one skill only cover one?
It's the specific scope a skill owns, scaffolding, testing, packaging, data pipelines. Limiting a skill to one domain keeps its triggers and guardrails specific and checkable; a skill that tries to cover everything degrades into a vague general-purpose prompt.
Does a skill replace the need for code review or CI?
No, a skill's guardrails reduce the likelihood of a wrong default, but the output still needs to pass the same objective checks (pytest, ruff, mypy) and the same human review any other change would. Skill outputs are explicitly required to end in verifiable commands for this reason.
Do data-science or ML skills need different guardrails than web-service skills?
Yes, a pipeline or model-training skill typically guards reproducibility (fixed seeds, pinned dataset versions, logged hyperparameters), while a web-service skill guards things like async correctness and secret handling. Keeping these as separate decision domains is deliberate.
Who or what actually "reads" a SKILL.md file?
An AI coding assistant, at the moment its trigger condition is recognized, either because a human explicitly invokes it or because the assistant's tooling matches the current task to a known skill's trigger.
Do skills go stale the same way documentation does?
Yes, and arguably faster, because a stale skill doesn't just become outdated, it actively and confidently applies old guardrails and version pins to a newer stack, which is worse than no guidance at all.
Can a skill's guidance conflict with what's in the human cookbook pages?
It shouldn't by design, skills are meant to route to and reinforce the authoritative human documentation, not diverge from it. A skill that drifts out of sync with its referenced cookbook pages is a sign the skill itself needs updating.
Is a guardrail the same thing as a test?
No, a guardrail is an instruction shaping what the assistant should avoid doing while producing output; a test is an objective, automated check run against the output afterward. Guardrails reduce how often a test needs to catch something in the first place, but they don't replace running it.
What kind of task is a poor fit for a skill?
A one-off task with no repeated convention to encode and no real cost if the assistant's generic default is used, writing a skill for something that will only ever come up once is pure overhead with no return.
Related
- FastAPI Expert Skill - a skill built on this model for service scaffolding
- pytest / Testing Skill - a skill built around a verifiable-output contract
- Type-Hinting Skill - a skill scoped to one narrow decision domain
- Packaging & Publishing Skill - a skill whose guardrails guard a PyPI release process
- Python Best-Practices Skill - condensed operational rules that follow from this model
Stack versions: This page was written for Python 3.14.0 (stable 3.14, maintenance 3.13), FastAPI 0.115+, Pydantic 2, and ruff 0.9+.