Mastering Skills: How Custom AI Instructions Elevate Code Consistency

What Are AI Skills?

Every AI agent starts with zero context about your project. Without guidance, it'll use npm when you use yarn, write CSS-in-JS when your team uses SCSS modules, and name files however it feels right in the moment. A Skill (or AGENTS.md / CLAUDE.md file) is the mechanism that fixes this — a persistent, project-specific set of instructions that travels with the codebase.

It's the difference between an agent that works in your project and one that works for your project.

What a Real Skill Looks Like

Here's a simplified version of the agent instructions used on this portfolio:

# AGENTS.md — mirzaa.dev

## Stack
- Next.js 16 App Router, TypeScript, SCSS Modules
- Use `yarn` — never npm
- All components in `src/components/`, co-located with their `.module.scss`

## Mandates
- Always run `yarn build` before marking a task complete
- Use `Space Grotesk` for headings, `Inter` for body text
- CSS tokens live in `src/tokens/brand.json` — never hardcode hex values
- All new blog posts must include a `published: false` flag until reviewed

## Code Patterns
- Prefer React Server Components — only add `'use client'` when state or browser APIs are needed
- New API routes go in `src/app/api/` as Route Handlers, not the `pages/api/` directory
- Error boundaries required on all dynamic page segments

This file sits in the project root. Every agent session that reads it behaves consistently — the same naming conventions, the same build tooling, the same architectural constraints — regardless of who or what is doing the work.

The Three Layers of an Effective Skill

A well-structured skill has three distinct layers:

• Mandates — non-negotiable rules with zero tolerance for deviation. Package manager, file naming, build commands.
• Context — project knowledge that the agent can't infer from code alone. Design token locations, font choices, what branch to target.
• Procedures — step-by-step workflows for recurring tasks. "When adding a new blog post, do X then Y then Z."

The mandates stop the mistakes. The context stops the guesswork. The procedures stop the inconsistency.

Conclusion

Start with the mistakes you've already caught. Every time an agent does something you have to undo — wrong package manager, wrong naming convention, wrong file structure — add a mandate to your Skill file. After a week of active use, your AGENTS.md will reflect the real constraints of your project better than any documentation you'd have written upfront.

Sources & References

• OpenAI: System Prompt Best Practices
• Gemini CLI on GitHub: AGENTS.md and Custom Instructions
• Anthropic: Prompt Engineering Guide