Every project has its own way of doing things — migration patterns, transaction handling, deployment quirks, that one PDF template workflow nobody wants to touch. I've been writing this stuff down as markdown files with helper scripts so my AI agent can follow along. I've taken to calling this skill-driven development (building on agent skills, the open standard that originated at Anthropic and is now supported across most AI coding agents).
This post walks through some skills I've put together and shows the feedback loop that makes them worth maintaining.
What skills add over a README
A project README or an AGENTS.md can capture conventions. The skills I've been writing try to go a bit further:
- Progressive disclosure — a slim main file loads first, with detailed references pulled in only when needed. This keeps the agent's context window focused.
- Composability — skills declare dependencies and load together. A Django skill + a project overlay skill + a TDD skill compose into a complete workflow.
- Scripts — skills can ship executable scripts alongside the instructions. A script the agent calls is more reliable than a 15-step procedure the agent interprets.
- Self-improvement — when something goes wrong, the fix goes into the skill. Next session, the agent follows the updated instructions.
That last point is what makes it worth maintaining: every correction you make goes into the skill, and the agent doesn't make the same mistake twice.
The SDD loop
There's a useful parallel with Test-Driven Development:
| TDD | SDD | |
|---|---|---|
| Write | Write the test first | Write the skill first |
| Run | Run the code | Let the agent produce the code |
| Evaluate | Test fails → fix the code | Output is wrong → fix the skill |
| Loop | Until green | Until the agent gets it right |
In TDD, you iterate on code until the tests pass. Here, you iterate on skills until the agent's output is what you wanted. The skill isn't a one-shot handoff — you keep tweaking it as you find gaps.
The two work well together: write the tests, write the skill, let the agent produce the code. When tests fail, it's worth asking whether the code is wrong or the skill is incomplete. Fix the skill, re-run. Over time it adds up — each fix prevents one class of mistake, and after enough sessions you've built up a decent set of guardrails just from things that went wrong.
If you use teatree (a set of lifecycle skills I put together for multi-repo development), this loop can be automated: t3-retro runs a retrospective after each session and writes fixes into the skill files. But it works just as well manually — whenever you correct the agent, you can put that correction in a skill so it sticks.
What a skill looks like
A skill is a markdown file (SKILL.md) with YAML frontmatter, often accompanied by scripts for the mechanical parts. Here's a simplified example of the markdown side:
---
name: ac-django
description: Django coding conventions and best practices.
requires: []
metadata:
version: 0.2.0
---
# Django Conventions
## Models
### Fat Models Doctrine
- Business logic belongs in models, not views or serializers.
- Use model managers for complex queries.
### Migrations
- Always use `apps.get_model()` in data migrations — never import directly.
- Set `elidable=True` on data-only migrations.
- Include both `forwards` and `backwards` functions.
## Settings
### Storage Configuration (Non-Negotiable)
- Use `STORAGES` dict (Django 4.2+), not `DEFAULT_FILE_STORAGE`.
- The deprecated setting causes silent failures on deployment.
Rules marked (Non-Negotiable) are things I've learned the hard way. "Always verify services respond via HTTP before declaring running" sounds obvious, but without it, the agent will say "servers started" without checking whether anything actually came up.
These work with any agent that can read files — Claude Code, Codex, Cursor, whatever. The agent reads the skill and follows the instructions.
What's in the repo
I've put the generic ones in a public repository in case any of them are useful to others. Some are about coding conventions, some automate tedious manual work, and some help maintain the skills themselves.
Coding conventions
| Skill | What it covers |
|---|---|
ac-django |
Django 6.x / 5.2 LTS + DRF. Fat Models, migrations, transactions, security, testing |
ac-python |
Generic Python: style, typing, OOP design, testing, tooling |
ac-django is the one I use most. It covers the Django mistakes I kept correcting — outdated migration patterns, unsafe transaction handling, admin misconfigurations. It's not a tutorial, more of a reference for an agent that already knows Django but doesn't know how we use it.
Specialized operations
| Skill | What it covers |
|---|---|
ac-editing-acroforms |
AcroForm PDF templates: widget geometry, content streams, font subsetting |
ac-adopting-ruff |
Structured migration from black/isort/flake8 to ruff, one rule category per MR |
ac-auditing-repos |
Cross-repo infrastructure audit: harmonize pre-commit, linter, and editor configs |
ac-editing-acroforms came out of a nightmare I had editing PDF form templates by hand. The internals — annotation dictionaries, appearance stream generation, widget flags — are barely documented and full of gotchas. The agent can't figure this out from training data alone, so the skill ships with Python scripts that handle the tricky bits. The agent calls a function instead of trying to puzzle out PDF byte offsets.
ac-adopting-ruff is a step-by-step playbook for replacing black + isort + flake8 with ruff. It handles the things I got stuck on — conflicting formatter settings, rule equivalences between linters, the unfixable vs ignore distinction.
Content and meta-skills
| Skill | What it covers |
|---|---|
ac-writing-blog-posts |
Article writing + platform-specific social media promotion |
ac-generating-slides |
Markdown to presentation slides via Marp |
ac-reviewing-skills |
Deep review of other skills: architecture, content, scripts, quality |
ac-scaffolding-skill-repos |
Scaffold new skill repos with correct config and structure |
The last two are about keeping the skills themselves in shape. ac-reviewing-skills checks for duplication, stale cross-references, and issues in scripts — I run it once in a while to clean things up. ac-scaffolding-skill-repos sets up new skill repos with the right config so they stay consistent.
This blog post was written with ac-writing-blog-posts, for what it's worth.
How to use them
Install with npx skills:
npx skills add https://github.com/souliane/skills --skill '*' -g -y
This installs all skills globally for your default agent. To install for multiple agents at once:
npx skills add https://github.com/souliane/skills --skill '*' -g -y \
--agent claude-code codex cursor github-copilot
If you want the SDD feedback loop — where retrospective fixes land in files you can commit — this will NOT work because skills.sh would copy the local repo somewhere before symlinking:
git clone git@github.com:souliane/skills.git ~/workspace/souliane/skills
npx skills add ~/workspace/souliane/skills --skill '*' -g -y
Instead, you have to creates direct symlinks from your agent's skills directory to the clone, so the agent reads the live git checkout directly. When the agent (or you) updates a skill file, the change is immediately available in the next session and can be committed.
If you use teatree, its setup wizard can suggest these as companion skills for your project overlay — they're loaded automatically when you work in matching repos.
When it helps
Skills work best when:
- You correct the agent for the same kind of mistake more than once
- Your project has conventions that diverge from common patterns
- You work across sessions and the agent keeps losing context
- You use deterministic tools (PDF editors, linters, deployment scripts) where the agent needs exact steps
They're less useful for one-off tasks or when the model's defaults already match your preferences.
These skills reflect my own workflow — Django, Python, PDF templates, multi-repo infrastructure. They might not match yours at all. The most useful skills are probably ones you'd write yourself for your own project's conventions. These are just examples of what worked for me.
Top comments (0)