AI coding agents are getting very good at writing code.
The harder problem is getting them to work consistently.
A capable agent can scaffold an application, write a feature, create a GitHub Actions workflow, configure deployment, and review code.
But without project-specific rules, the results can become inconsistent very quickly.
One agent creates one structure. Another uses a different one. One remembers to run tests. Another says "this should work." One adds unnecessary dependencies. Another duplicates existing utilities.
I wanted a different approach.
So I built a reusable collection of skills for AI coding agents.
The project is open source:
GitHub: https://github.com/bkoimett/agent-skills
The problem
When working with AI coding agents, I noticed that there are really two different kinds of instructions.
The first is:
"Build this feature."
The second is:
"Here is how this repository should be worked on."
Those second instructions are often scattered across:
- README files
- contribution guides
- agent instructions
- CI configuration
- deployment configuration
- undocumented conventions
- tribal knowledge
That makes every new agent session spend time rediscovering the same information.
I wanted to move those recurring workflows into reusable skills.
The idea
The system is organized around a simple lifecycle:
Idea
↓
Scaffold
↓
Build
↓
Review
↓
CI
↓
Deploy
↓
Verify
Instead of creating one enormous "software engineering" skill, each stage has a focused responsibility.
The current collection contains:
agent-skills/
│
├── project-scaffolder/
├── code-conventions/
├── cicd-consistency/
├── deployment-consistency/
└── app-review/
Each skill can be used independently.
1. Project scaffolder
This is the foundation.
The goal isn't:
"Generate a React app."
The goal is:
"Understand what needs to be built, make the important decisions explicit, then create the smallest appropriate project."
The workflow is:
Requirements
↓
Clarify ambiguity
↓
Architecture
↓
Stack selection
↓
Project structure
↓
Scaffold
↓
Documentation
↓
Install
↓
Verify
A particularly important rule is:
Don't add technology just because a template contains it.
If the application doesn't need a database, don't add one.
If authentication isn't required, don't generate an authentication system.
If a microservice isn't necessary, don't create one.
The scaffold should come from the requirements, not from the agent's imagination.
2. Code conventions
Once a project exists, another problem appears:
convention drift.
A project might start with:
TypeScript
strict typing
tests beside components
pnpm
ESLint
Prettier
Six months later, you might find:
different package managers
inconsistent test locations
`any` everywhere
unused abstractions
documentation that no longer matches the code
The code-conventions skill audits the repository against its established conventions.
It looks at:
- project instructions
- architecture documentation
- package configuration
- source code
- tests
- lint configuration
- TypeScript configuration
- Go conventions
- Git conventions
The important distinction is that it doesn't invent a new style just because the agent prefers one.
Existing project conventions come first.
3. CI/CD consistency
CI is often where local development and automation start drifting apart.
For example, the README says:
pnpm lint
pnpm typecheck
pnpm test
pnpm build
but GitHub Actions might still be running:
npm test
Or the project may have moved from Node 20 to Node 22 while CI still uses the old runtime.
The CI skill inspects the actual repository before generating or modifying workflows.
For Node/TypeScript projects, the typical lifecycle becomes:
Install
↓
Lint
↓
Typecheck
↓
Test
↓
Build
For Go:
gofmt
↓
go vet
↓
go test
↓
go build
For mixed repositories, the workflows can be composed around the actual package structure.
The important rule is:
Never invent a CI command that the project doesn't actually have.
4. Deployment consistency
Deployment has the same problem.
Different projects end up with completely different assumptions about:
- environment variables
- build commands
- health checks
- startup commands
- database migrations
- smoke tests
- rollback
So deployment consistency separates general deployment principles from provider-specific knowledge.
For example:
deployment-consistency/
│
├── SKILL.md
│
└── references/
├── deployment-principles.md
├── vercel.md
├── render.md
├── docker.md
├── environment-variables.md
├── database.md
├── rollback.md
└── verification.md
That means the main skill doesn't need to know every detail about every provider.
It can load the relevant reference when needed.
5. Application review
The final piece is a review skill.
I didn't want another generic:
"Review my code."
Instead, the review has specific areas.
Security
Things like:
- authentication boundaries
- authorization
- secret exposure
- injection risks
- XSS
- CSRF
- insecure redirects
- CORS
- sensitive logging
SEO
For public applications:
- metadata
- canonical URLs
- robots directives
- sitemap
- Open Graph
- structured data
- indexability
AI discoverability
Where relevant:
- machine-readable product information
- documentation
- structured information
- crawlability
- public API descriptions
Documentation drift
This one is particularly useful.
The skill compares what the project says with what it actually does.
For example:
README:
"Authentication is required."
Application:
Public route bypasses authentication.
Or:
README:
"Run pnpm dev."
package.json:
No dev script exists.
The goal is to find concrete inconsistencies rather than produce a giant subjective code review.
Why skills instead of one giant instruction file?
This was probably the biggest architectural decision.
It is tempting to create something like:
AI_ENGINEERING_RULES.md
with thousands of lines covering everything.
I don't think that's the right abstraction.
Instead:
AGENT
│
▼
┌──────────────┐
│ Skill │
└──────┬───────┘
│
┌──────────┴──────────┐
▼ ▼
SKILL.md references/
workflow detailed knowledge
The skill knows what to do.
The references explain how a particular technology/provider works.
That keeps the context smaller and makes the system easier to maintain.
The scaffolder also generates an operating system for the project
One thing I particularly wanted to solve was what happens after scaffolding.
Creating the initial source code isn't enough.
A new project also needs to tell future agents how to work.
So the scaffolder creates:
AGENTS.md
DESIGN.md
WORKFLOW.md
README.md
Each has a different responsibility.
AGENTS.md
How AI agents should work in the repository.
DESIGN.md
Architecture and design decisions.
WORKFLOW.md
Development, testing, Git, and release workflow.
README.md
Human-facing project documentation.
The important part is avoiding duplication.
The agent shouldn't need to read the same 500-line explanation in four different places.
Context efficiency matters
One of the biggest reasons I started thinking about this as a skill system was context.
An AI coding agent doesn't need the entire repository for every task.
If I'm fixing a Go session lifecycle bug, the agent shouldn't need to load:
PWA components
deployment configuration
SEO documentation
GitHub Actions
The ideal flow is:
Task
↓
Determine scope
↓
Load relevant skill
↓
Load relevant references
↓
Inspect relevant package
↓
Implement
↓
Verify
For a cross-package task, the system can use a shared contract:
docs/shared-contract.md
containing:
- event definitions
- API endpoints
- interface contracts
This allows separate agents to work on separate packages without forcing every agent to understand the entire repository.
What I learned
The biggest lesson so far is that AI agents don't just need better models.
They also need better environments.
A model can be very capable and still produce inconsistent results when:
- project conventions aren't documented
- verification isn't defined
- architecture is ambiguous
- CI differs from local development
- deployment assumptions are hidden
- documentation becomes stale
Skills turn those expectations into reusable workflows.
Instead of repeatedly telling an agent:
"Remember to run the tests."
the skill can define verification as part of the workflow.
Instead of:
"Please don't add unnecessary dependencies."
the scaffolder can make that an explicit decision rule.
Instead of:
"Check whether the README is still accurate."
the review skill can systematically inspect documentation drift.
What's next?
I want to keep the collection intentionally small.
The goal isn't to create 100 skills.
It's to create a small set of composable skills that cover recurring engineering workflows.
Some possible future additions include:
- database migration review
- API contract validation
- dependency auditing
- accessibility review
- performance review
- release management
- observability setup
But each new skill needs to justify its existence.
If it can be handled cleanly by an existing skill, it probably shouldn't become another skill.
Try it
The repository is open source:
GitHub: https://github.com/bkoimett/agent-skills
skills.sh: https://skills.sh/bkoimett/agent-skills
If you're building with OpenCode or another AI coding agent, I'd be interested in how you're structuring your own agent instructions and reusable workflows.
The interesting question for me isn't:
"Can AI write the code?"
It's increasingly:
"Can we build environments where AI consistently writes the kind of code we actually want?"
That's what this project is exploring.
Top comments (0)