DEV Community: Maxi Contieri

AI Coding Tip 013 - Use Progressive Disclosure

Maxi Contieri — Tue, 31 Mar 2026 11:00:00 +0000

Structure your skills so the AI loads only the files it needs. Split complexity across modular files and use keywords to trigger conditional loading.

TL;DR: You reduce token usage when you trigger conditional loading instead of loading all files at once.

Common Mistake ❌

You load a complex skill with 20 associated files into your context window all at once.

Your context window fills up immediately.

You waste tokens on irrelevant file content and cases that don't match what you're asking.

The AI gets lost in noise and disobeys your commands.

You can't ask follow-up questions because there's no space left and hallucinations happen.

Problems Addressed 😔

You waste tokens loading skill files you don't need
The AI reads case definitions that don't apply to your input
Context window fills up before you can iterate or ask follow-ups
Response time slows down because the AI is overwhelmed
You lose precision when the AI picks the wrong file or rule

How to Do It 🛠️

Split your skill into multiple files (one per concern)
Write a smart description with clear conditional triggers
Define keywords that trigger file loading
Create conditional rules: "If input contains X, load file Y"
Include response templates so the AI knows how to structure answers
Nest file references only when needed (e.g., array.md loads nested.md only for nested arrays)
Test your keywords to ensure the AI picks them up correctly

Benefits 🎯

The AI loads only the files it needs.

You save 90% of tokens on irrelevant skill content.

Response times stay fast even with complex skills.

Your context window stays clean for follow-up questions.

Each request is precise because the AI only sees rules that matter.

Context 🧠

Agentic skills can be massive.

A syntax validator might have files for declarations, arrays, nested arrays, function calls, and scripts.

If you load all of them, the AI wastes tokens reading rules that don't apply.

Progressive disclosure in skills works by defining keywords that trigger file loading.

When you write "DECLARE 123", the skill recognizes the DECLARE keyword and loads declaration.md.

The AI only reads what matters.

You write descriptions using "What," "When," or "How" patterns.

You create conditional rules in your main skill file.

You include response templates so answers stay consistent.

The AI requests what it needs using keywords, so you don't have to guess.

How Skills Work 🔄

Skills implement progressive disclosure at three stages:

Discovery: At startup, agents load only the name and description of each available skill.

Just enough information to know when a skill might be relevant.

No full instructions, no referenced files, no code—only the metadata.

Activation: When a task matches a skill's description, the agent reads the full SKILL.md instructions into context.

Now the agent has the complete instructions and knows what to do.

Still no unnecessary files or code loaded yet.

Execution: The agent follows the instructions, optionally loading referenced files or executing bundled code as needed.

Only when the AI detects it needs something does it load that file or run that script.

This approach keeps agents fast while giving them access to more context when they actually need it.

Each step is triggered by actual need, not preloaded upfront.

Prompt Reference 📝

Bad Prompt:

# SKILL.md (15,000 tokens - Monolithic)

Validates DECLARE, arrays, nested arrays,
function calls, loops, all in one file.

DECLARE Rules:
- First char uppercase
- Can't start with number

Array Rules:
- Use square brackets [item]
- Examples: [foo], [bar]

Function Call Rules:
- Parentheses required: func()
- Parameters separated by commas

Loop Rules:
- FOR, WHILE, DO keywords
- Body must be indented

When you ask "Is DECLARE 123 valid?" the AI loads all 15,000 tokens covering every rule.

Context window fills up fast.

Good Prompt:

# SKILL.md (800 tokens - Modular)

Validates foo syntax: DECLARE, arrays,
nested arrays, function calls, loops.

Rules:
- DECLARE detected → load declaration.md
- [ detected → load array.md
- ( detected → load function-call.md

Template: [input] valid?
[YES/NO]. Reason: [rule].

declaration.md (1,200 tokens):

First character must be uppercase.
Cannot start with number.
Examples: DECLARE x, DECLARE foo

array.md (1,500 tokens):

Must use brackets: [item]
References nested-array.md for [x]
Examples: [foo], [bar], [123]

When you ask "Is DECLARE 123 valid?" the AI loads only SKILL.md (800) + declaration.md (1,200) = 2,000 tokens.

Context stays clean for follow-up questions.

Considerations ⚠️

Define your keywords upfront so the AI recognizes them consistently.

Each file should handle one concern (declarations, arrays, etc.).

Don't create too many nested references or the loading chain becomes confusing.

Test your keyword patterns to make sure the AI recognizes them.

If your skill includes scripts, review them carefully.

Scripts can create security risks if they run without review.

Type 📝

[X] Semi-Automatic

Limitations ⚠️

Progressive disclosure works best when keywords are distinctive.

Generic words like "function" might trigger too often and load the wrong file.

Deeply nested file structures (3+ levels) are confusing to maintain.

External scripts need security review before you share skills from online repositories.

Keywords must be clear or the AI loads files unpredictably.

Tags 🏷️

Standards

Level 🔋

Comments 1

4 min read

Conclusion 🏁

Progressive disclosure in skills means splitting files by concern and using keywords to trigger conditional loading.

You define what the AI needs to see, not dump everything.

Include templates so responses stay consistent.

When you get good at this pattern, even complex skills stay fast, efficient, and focused. 🎯

More Information ℹ️

Agent skills progressive disclosure

Claude Token Counting Guide

Context Windows and Token Limits

Prompt Engineering Patterns

UX Progressive Disclosure

Information Architecture Best Practices

Cognitive Load Theory

Efficient Prompt Design

API Cost Optimization

Code Context Patterns

Also Known As 🎭

Layered context disclosure
Just-in-time information architecture
Context-on-demand

Tools 🧰

Windsurf with progressive disclosure
GitHub Copilot with skills
Claude with custom skills
VS Code Copilot Chat
Agentic frameworks
Token counter tools

Disclaimer 📢

The views expressed here are my own.

I am a human who writes as best as possible for other humans.

I use AI proofreading tools to improve some texts.

I welcome constructive criticism and dialogue.

I shape these insights through 30 years in the software industry, 25 years of teaching, and writing over 500 articles and a book.

This article is part of the AI Coding Tip series.

Maxi Contieri

Jan 21

AI Coding Tips

#webdev #ai #programming #beginners

Comments

1 min read

AI Coding Tip 012 - Understand All Your Code

Maxi Contieri — Mon, 23 Mar 2026 15:25:54 +0000

You own the code. Own and understand what it does.

TL;DR: Never ship AI-generated code you don't understand — ask until you do.

Common Mistake ❌

You ask an AI agent to implement a feature.

It returns 200 lines of code.

You run the tests. They pass. You commit and push.

You think you are the best 'agentic-coder' in the world.

But you never read the code.

Three weeks later, a security issue appears in production.

The AI introduced subtle bugs you could have caught in two minutes.

You didn't catch it because you never looked.

You're accountable but don't understand what the code does, and you can't explain it to others.

There are many fancy video tutorials on using agents without reviewing the code.

Remember, there must always be a human in the loop.

Problems Addressed 😔

You lose control of your own codebase.
You can't debug code you don't understand.
You ship vulnerabilities without knowing they exist.
You can't explain your own code in a code review.
You build a dependency on AI that makes you a worse engineer over time.
You take legal and professional responsibility for code you never vetted.

Maxi Contieri

Nov 4 '25

Code Smell 313 - Workslop Code

#webdev #programming #ai #web3

Comments

7 min read

How to Do It 🛠️

Read every code line the AI generates or modifies before you accept it.
Ask the AI to explain any part you don't understand.
Ask follow-up questions until the explanation is clear to you.
Identify the assumptions the AI made and verify them.
Check edge cases the AI might have missed.
Refactor and polish any part that you would not have written that way yourself.
Make the code yours before you commit it.

Benefits 🎯

You stay as the author of your codebase, not just a curator of AI output.
You catch defects before they reach production.
You learn from what the AI generates.
You build trust with your team because you can explain your code.
You make better prompts over time because you understand what went wrong.

Context 🧠

AI agents are fast. That speed creates pressure.

You feel like slowing down to read breaks the momentum.

It doesn't. It saves you.

The AI doesn't know your system. It doesn't know your constraints.

It doesn't know what happened last quarter when you made a similar change.

You do. That context is irreplaceable.

When you skip reading, you hand off judgment to a tool that has no judgment. You outsource the one thing only you can do.

Asking questions is not a sign of weakness.

It is how you stay in control.

The AI won't judge you for asking.

It will give you a better answer.

Prompt Reference 📝

Bad Prompt:

Implement user authentication,

add it to the project,

commit and push to the main branch.

*This prompt gives the AI full authority over a critical system. *

*You get a blob of code with no checkpoint for understanding.*

Good Prompt:

Implement a login function using JWT.

Use RS256 signing.

After you write it, ask me questions about each step.

I'd like to understand what you did on every line of code

*This prompt sets expectations.*

*You get code AND an explanation.*

*You know what to verify.*

Considerations ⚠️

The AI can write completely wrong, confident-sounding code.
Passing tests doesn't mean you wrote correct logic.
The AI optimizes for plausible output, not correct output.
You are responsible for what you deploy, not the AI.
Some AI mistakes are subtle. You only catch them when you read carefully.

Type 📝

[X] Semi-Automatic

Limitations ⚠️

For very large generated files, break your review into sections.

Tags 🏷️

Readability

Level 🔋

[X] Beginner

Related Tips 🔗

Maxi Contieri

Feb 13

AI Coding Tip 006 - Review Every Line Before Commit

#ai #programming #development #softwaredevelopment

Comments 1

7 min read

AI Coding Tip - Ask the AI to Explain Its Own Code
AI Coding Tip - Use AI as a Pair Programmer, Not a Replacement

Conclusion 🏁

The AI writes fast. You think too slowly. That is not a flaw.

That is the division of labor that makes the combination work.

Speed without understanding is just faster mistakes.

Ask questions. Read the code. Own what you ship. 🏁

More Information ℹ️

The Pragmatic Programmer - Your Code, Your Responsibility

OWASP Top Ten - Common Security Risks in Code

Code Review Best Practices - Google Engineering

Martin Fowler - Code Smells

GitHub Copilot Security Research - Risks of AI Code

ACM Code of Ethics - Professional Responsibility

Stack Overflow Blog - How AI Changes Code Ownership

IEEE Software Engineering Standards

CWE - Common Weakness Enumeration

Also Known As 🎭

"Trust but verify."
"AI-generated code review."
"Responsible AI coding."
"Developer accountability"

Tools 🧰

Any AI coding assistant (GitHub Copilot, Claude, Cursor, Codeium)
Your language's linter and static analysis tool
Code review tools (GitHub PRs, GitLab MRs, Gerrit)

Disclaimer 📢

The views expressed here are my own.

I am a human who writes as best as possible for other humans.

I use AI proofreading tools to improve some texts.

I welcome constructive criticism and dialogue.

I shape these insights through 30 years in the software industry, 25 years of teaching, and writing over 500 articles and a book.

This article is part of the AI Coding Tip series.

Maxi Contieri

Jan 21

AI Coding Tips

#webdev #ai #programming #beginners

Comments

1 min read

AI Coding Tip 011 - Initialize Agents.md

Maxi Contieri — Wed, 18 Mar 2026 22:12:31 +0000

Summarize your architecture rules and give your AI a persistent memory

TL;DR: When you use the /init command, you create a context file that saves you from repeating instructions in every new session.

Common Mistake ❌

You waste time copying and pasting the same project rules into every new chat.

You forgot to tell the AI about your specific test commands.

When you start a fresh session, the AI loses all previous context about your coding style or architecture.

Create your own system prompts, persist them and keep an eye on them regularly.

Problems Addressed 😔

Repetitive and manual meta-prompting
Inconsistent code styles across sessions
High token usage from redundant instructions
AI hallucinations about build or test commands
Onboarding new projects

How to Do It 🛠️

Open your terminal in your project root directory.
Type /init if you use Claude Code or OpenCode.
Review the generated CLAUDE.md or AGENTS.md file.
Add specific "landmines" or things the AI can't see in the code.
Save the file, review the commit diffs, and start your next coding task.
You can do it again when you have new rules.

Benefits 🎯

When you initialize (/Init) your project, the AI reads all the repository immediately.

You get consistent results without extra effort.

You save tokens because you don't have to describe your stack every time.

Context 🧠

AI assistants start every session with a blank slate.

They don't remember what you told them yesterday.

Tools like Claude Code look for a specific file to understand your project.

When you provide this saved file, you close the gap between separate AI sessions.

Prompt Reference 📝

Bad Prompt:

Remember to use 2 spaces for indentation 
and always run 'npm run test:unit' 
before you finish the task.

Good Prompt:

git clone https://github.com/torvalds/linux.git

/Init

Considerations ⚠️

Keep the generated file short.

When you add too much text, the AI might get confused.

Don't include information that the AI can already find in your package.json or README.md.

Type 📝

[X] Semi-Automatic

Limitations ⚠️

You can only use this tip with AI tools that support persistent context files.

If you change your build tools, you can update the Markdown file manually, run /init again, or do both.

In Windsurf, there is no literal /init terminal command that automatically generates a configuration file, as Claude Code or OpenCode does.

Windsurf uses a more agentic approach where the AI (Cascade) either discovers your rules automatically or creates them when you ask.

Cascade, initialize a .windsurfrules file for this project. Include my tech stack, coding standards, and build commands.

Tags 🏷️

Standards

Level 🔋

[X] Beginner

Related Tips 🔗

AI Coding Tip 006 - Review Every Line Before Commit

Maxi Contieri ・ Feb 13

#ai #programming #development #softwaredevelopment

Use .cursorrules for local preferences
Create modular AGENTS.md files for monorepos
Keep your README.md updated for better AI indexing

Conclusion 🏁

When you use /init, you turn your AI from a temporary contributor into a permanent team member.

More Information ℹ️

OpenCode /Init

Claude Code: CLAUDE.md

.cursorrules in Cursor

Windsurf rules

Also Known As 🎭

Project-AI-Onboarding
Context-Bootstrapping

Tools 🧰

Claude Code
OpenCode
Cursor (via .cursorrules)

Disclaimer 📢

The views expressed here are my own.

I am a human who writes as best as possible for other humans.

I use AI proofreading tools to improve some texts.

I welcome constructive criticism and dialogue.

I shape these insights through 30 years in the software industry, 25 years of teaching, and writing over 500 articles and a book.

This article is part of the AI Coding Tip series.

AI Coding Tips

Maxi Contieri ・ Jan 21

#webdev #ai #programming #beginners

AI Coding Tip 010 - Access All Your Code

Maxi Contieri — Tue, 10 Mar 2026 18:52:48 +0000

Stop copying code chunks. Start letting AI agents work directly with your files.

TL;DR: Use terminal-based AI tools to give your assistant direct access to your local files and test suites.

Common Mistake ❌

You copy code snippets into a web browser chat like ChatGPT, Claude, or Grok.

You manually move code back and forth and give small chunks of code, filling up the context window.

You lose the context of your folder structure, relations among modules, and the whole architecture.

The AI often (wrongly) guesses your project layout and hallucinates.

When you do this, you get inconsistent code and outdated logic.

Problems Addressed 😔

Context Tax: Manual copying wastes your focus.
Hallucinations: The AI suggests libraries you don't actually have.
Isolated logic: The assistant doesn't know if your code even builds.
Manual effort: You have to run every test and fix every error yourself.

You're basically playing assistant to the AI, running around doing the busywork.

How to Do It 🛠️

Download a CLI or IDE tool like Claude Code, OpenCode, Windsurf, or similar, and let it access ALL your codebase.

(You'll need to check compliance, set up safeguards, and respect any NDAs).

Open your terminal and start an interactive session. Let the agent navigate through all your code.

Describe what you want to accomplish at a high level and delegate to the orchestrator agent.

Review the proposed plan in the terminal.

Approve the changes to update your local files.

Let the agent run your tests and fix failures automatically.

Benefits 🎯

Full project context through local AST and RAG indexing.

Self-healing code through automated shell feedback loops.

Multi-file edits in a single prompt.

Parallel development using multiple agent instances.

Iterative incremental learning and experimentation. Baby steps.

Context 🧠

We were all blown away when ChatGPT came out.

I wrote an article 2 days after its release, understanding it was a game-changer.

Even people like me who had been working with earlier GPT models.

Four years later, you still see many developers coding this way.

It works for small algorithms and functions, but falls apart for real software engineering.

Prompt Reference 📝

Bad Prompt

// Please fix the login bug in this snippet:

async function loginUser(email, password) {
  const url = 'https://api.penrosebrain.com/login';

  try {
    const response = await fetch(url, {
      method: 'PUT',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ email, password }),
    });

  } catch (error) {
    console.error('There was an error:', error.message);
    alert(error.message);
  }
}

Good Prompt

// opencode: "Create a failing text, fix the login bug, run tests, 
// Ensure it passes the new test and all the previous ones
// Create a Pull Request so I can review it

async function loginUser(email, password) {
  const url = 'https://api.penrosebrain.com/login';

  try {
    const response = await fetch(url, {
      method: 'PUT',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ email, password }),
    });

  } catch (error) {
    console.error('There was an error:', error.message);
    alert(error.message);
  }
}

Considerations ⚠️

CLI agents have a learning curve.

Always review all changes before committing them.

Use a sandbox environment if you run untrusted code.

Type 📝

[X] Semi-Automatic

Limitations ⚠️

Don't use this for tiny, one-off scripts.

Web chats work better for creative brainstorming or generating images.

High token usage in long sessions can drive up your API costs.

Tags 🏷️

Complexity

Level 🔋

[X] Intermediate

Related Tips 🔗

Maxi Contieri

Jan 20

AI Coding Tip 003 - Force Read-Only Planning

#ai #programming #chatgpt #code

Comments

3 min read

Maxi Contieri

Feb 13

AI Coding Tip 006 - Review Every Line Before Commit

#ai #programming #development #softwaredevelopment

Comments 1

7 min read

Connect external data using the Model Context Protocol (MCP).

Run local models if you need 100% privacy.

Conclusion 🏁

Move your AI assistant to the terminal.

You'll work faster and make fewer mistakes.

When you delegate the boring parts, you can focus on architecture and high-level design.

More Information ℹ️

Why CLIs Are Better for AI Coding Agents Than IDEs

How Cursor Actually Indexes Your Codebase

Aider - AI Pair Programming in your Terminal

Claude Code Overview

OpenCode vs Claude Code: Comparing AI Coding Agents

AI Coding Assistants for Large Codebases

Boosting My Developer Productivity with AI in 2025

OpenCode Documentation

Introducing Advanced Tool Use on the Claude Developer Platform

What is OpenCode? - AI Quick Reference

Also Known As 🎭

Agentic Coding

Terminal Agents

Autonomous Coding Loops

Tools 🧰

Claude Code, OpenCode, Aider, Codex CLI.

Disclaimer 📢

The views expressed here are my own.

I am a human who writes as best as possible for other humans.

I use AI proofreading tools to improve some texts.

I welcome constructive criticism and dialogue.

I shape these insights through 30 years in the software industry, 25 years of teaching, and writing over 500 articles and a book.

This article is part of the AI Coding Tip series.

Maxi Contieri

Jan 21

AI Coding Tips

#webdev #ai #programming #beginners

Comments

1 min read

AI Coding Tip 009 - Compact Your Context

Maxi Contieri — Tue, 03 Mar 2026 02:02:44 +0000

Stop the memory rot

TL;DR: You can keep your AI sharp by forcing it to summarize and prune what it remembers (a.k.a. compacting).

Common Mistake ❌

You keep a single, long conversation open for hours.

You feed the AI with every error log and every iteration of your code.

Eventually, the AI starts to ignore your early instructions or hallucinate # AI Coding Tip 009 - Compact Your Context

Stop the memory rot

TL;DR: You can keep your AI sharp by forcing it to summarize and prune what it remembers (a.k.a. compacting).

Common Mistake ❌

You keep a single, long conversation open for hours.

You feed the AI with every error log and every iteration of your code.

Eventually, the AI starts to ignore your early instructions or hallucinate nonexistent functions.

Problems Addressed 😔

Context Decay: The AI loses track of your original goals in the middle of a long chat.
Hallucinations: The model fills memory gaps with hallucinations or outdated logic.
Token Waste: You pay for the AI to re-read useless error logs from three hours ago.
Reduced Reasoning: A bloated context makes the AI less smart and more prone to simple mistakes.

How to Do It 🛠️

Restart often: You can start a new chat once you finish a sub-task.
Request a State Summary: Before you close a conversation, ask the AI to summarize the current decisions and plan.
Add Human Checkpoints: After the summary, confirm you are still on track.
Use Markdown Docs: Keep a small context.md file with your current stack and rules.
Prune the Logs: You should only paste the relevant 5 lines of a stack trace instead of the whole irrelevant 200-line output.
Divide and conquer: Break large tasks into smaller ones, invoking their own skills with local tokens and a fresh context.
Divide the responsibility: A General doesn't need to know what every soldier is doing on the battlefield.
Create and persist as Skill: After you have taught the AI, you should refactor the knowledge and business rules.
Keep an Eye on the Context Size: Most tools have visual indicators of the window consumption.
Use Local Persistence: Some tools allow sharing memory among agents and their sub-agents.

Benefits 🎯

You get more accurate code suggestions.
You avoid divergences
You follow the AI's train of thought.
You spend less time correcting the AI's hallucinations.
The AI follows your project constraints more strictly and keeps focused on your tasks

Context 🧠

Large Language Models have limited attention.

Long context windows are a trap.

Many modern models offer a very large context window.

In practice, they ignore a lot of them to your frustration.

Even with huge context windows, they prioritize and focus ob the beginning and the end of the prompt.

Prompt Reference 📝

Bad Prompt

Here is the 500-line log of my failed build. 

Also, remember that we changed the database schema 

Three hours ago in this chat.

Add the unit tests as I described above.

Now, refactor the whole component.

Good Prompt

I am starting a new session. Here is the current state: 

We use *PostgreSQL* with the 'Users' table schema [ID, Email]. 

The AuthService`interface is [login(), logout()]. 

Refactor the LoginComponent` to use these.

Considerations ⚠️

You must ensure you don't purge essential context.

If you prune too much, the AI might suggest libraries that conflict with your current setup.

Review the compacted information.

Type 📝

[X] Semi-Automatic

Limitations ⚠️

You can use this tip manually in any chat interface.

If you use advanced agents like Claude Code or Cursor, they might handle some of this automatically, but manual pruning is still more reliable.

Tags 🏷️

Context

Level 🔋

[X] Intermediate

Related Tips 🔗

Maxi Contieri

Jan 27

AI Coding Tip 004 - Use Modular Skills

#ai #webdev #programming #beginners

Comments

4 min read

Maxi Contieri

Feb 4

AI Coding Tip 005 - Keep Context Fresh

#webdev #programming #ai #tutorial

Comments

4 min read

AI Coding Tip 010 - Create Skill from Conversation

Conclusion 🏁

You are the curator of the AI's memory.

If you let the context rot, the code will rot, too.

Keep it clean and compact. 🧹

More Information ℹ️

Lost in the Middle: How Language Models Use Long Context

LLMLingua: Prompt Compression for LLMs

How to Manage Context in AI Coding

Avoiding LLM Hallucinations

Prompt Engineering Guide: Context Management

Understanding Token Limits

Claude Context Window Best Practices

Also Known As 🎭

Context Pruning
Token Management
Prompt Compression

Tools 🧰

Claude Code
Cursor
Windsurf

Disclaimer 📢

The views expressed here are my own.

I am a human who writes as best as possible for other humans.

I use AI proofreading tools to improve some texts.

I welcome constructive criticism and dialogue.

I shape these insights through 30 years in the software industry, 25 years of teaching, and writing over 500 articles and a book.

This article is part of the AI Coding Tip series.

Maxi Contieri

Jan 21

AI Coding Tips

#webdev #ai #programming #beginners

Comments

1 min read

functions.

AI Coding Tip 008 - Use Spec-Driven Development with AI

Maxi Contieri — Tue, 24 Feb 2026 11:00:00 +0000

Learn guided by the domain

TL;DR: Use AI to understand requirements and build a shared mental model while you write the code.

Common Mistake ❌

You jump directly to code generation with a vague, wishful prompt.

The AI seems to understand your specific business logic, but is condescending with you.

The problem creates a spaghetti mess that is difficult to maintain later.

The AI is not a magic button for lazy people. It is a senior pair programmer and a learning companion.

You follow the Spec-Driven Development trend and work in a taylorist cascading way failing into analysis paralysis and unrealistic plans.

Problems Addressed 😔

Hallucinations: The AI guesses details when you don't provide specific context.

Technical Debt: You build complex systems that collapse under logical errors and don't simulate the real-world MAPPER.

Context Fragmentation: The AI loses track of your goals in long sessions.

Logic Drift: The code "works". Yet it doesn't solve the actual problem.

How to Do It 🛠️

Ask the AI to interview you.

You state the high-level idea and have the AI ask questions to uncover edge cases.

Work together in learning mode. Dave Farley tells us to be experts at learning.

Draft a spec.md file. You and the AI collaborate on a document that defines the architecture, data models, and goals.

Use the Plan Mode.

Keep the AI in a read-only environment to explore your codebase and verify the plan as you execute it.

Plan as you go with the goal in mind without making assumptions about a rigid roadmap.

Always validate the bijection against the real-world requirements.

Turn the live spec into a simple checklist of atomic implementation steps.

The backlog will grow and shrink as you learn the domain. It is a live artifact.

Set up a persistent context while you learn.

Create a .md file to store project rules that the AI cannot guess.

Benefits 🎯

You learn about the domain faster because the AI can serve as an encyclopedic mentor.

You stay proudly accountable for the architecture.

You eliminate boilerplate while maintaining system stability.

You close the Human 30% gap by focusing on system coordination.

Context 🧠

These tools are high-velocity coders, but they are very innocent.

They perform best when you instruct with a clear mission and modular instructions.

This "waterfall in 15 minutes" way favors you and the AI to be on the same page before you trigger the first code diff.

Prompt Reference 📝

Bad Prompt:

Build me a task management app with React and Node.

Create a behavior specification and a Gantt project

Good Prompt:

You are a Senior Software Engineer. I want to build a task app.

Ask me 10 clarifying questions about the architecture, security, 
and data model. 

After I answer, help me draft a spec.md.

Let's build it together with TDD and contract tests.

Considerations ⚠️

AI can write bugs with complete conviction.

You must review every change.

Type 📝

[X] Semi-Automatic

Tags 🏷️

Complexity

Level 🔋

[X] Intermediate

Related Tips 🔗

Use CLAUDE.md for project memory.

Set up MCP servers for live documentation.

Run parallel agents for large refactors.

Conclusion 🏁

You should invest 15 minutes in planning with the AI instead of rushing. It will save you hours of debugging.

Use the copilot to improve your design with your approval, and let it handle the hard accidental typing.

More Information ℹ️

Spec Driven Development

Kent Beck Critizing Spec-Driven Development

Kent Beck Earn and Learn

Addy Osmani Coding Workflow

Start with a clear path (specs before code)
Break work into small, iterative chunks
Provide extensive context and guidance
Choose the right model (and use multiple when needed)
Leverage AI coding across the lifecycle
Keep a human in the loop - verify, test, and review everything
Commit often and use version control as a safety net. Never commit code you can’t explain.
Customize the AI’s behavior with rules and examples
Embrace testing and automation as force multipliers
Continuously learn and adapt (AI amplifies your skills)

Also Known As 🎭

Spec-Driven Development

Waterfall in 15 Minutes

Vibe Coding with Discipline

Disclaimer 📢

The views expressed here are my own.

I am a human who writes as best as possible for other humans.

I use AI proofreading tools to improve some texts.

I welcome constructive criticism and dialogue.

I shape these insights through 30 years in the software industry, 25 years of teaching, and writing over 500 articles and a book.

This article is part of the AI Coding Tip series.

Maxi Contieri

Jan 21

AI Coding Tips

#webdev #ai #programming #beginners

Comments

1 min read

AI Coding Tip 007 - Avoid Malicious Skills

Maxi Contieri — Tue, 17 Feb 2026 04:14:54 +0000

Avoid the Agentic Trojan Horse

TL;DR: Treat AI agent skills like dangerous executable code and read the instructions carefully.

Common Mistake ❌

You install community skills for your AI assistant based on popularity or download counts.

You trust "proactive" agents when they ask you to run "setup" commands or install "AuthTool" prerequisites.

You grab exciting skills from public registries and install them right away.

You skip code reviews or scans because the docs look clean.

You are lazy and careless.

Even careful developers can miss these details when rushing.

Problems Addressed 😔

Information stealers search for your SSH keys, browser cookies, and .env files.

Supply chain attacks exploit naming confusion (ClawdBot vs. MoltBot vs. OpenClaw).

Typosquatting pushes you into installing malicious packages.

Your adversaries invoke Arbitrary Code Execution using unvalidated WebSocket connections.

How to Do It 🛠️

Run your AI agent inside a dedicated isolated Virtual Machine or Docker container.

This measure prevents the agent from accessing your primary filesystem.

Review the SKILL.md and source code of every new skill.

Making a code review You can find hidden curl commands, base64-encoded strings and obfuscated code that try to get to malicious IPs like 91.92.242.30.

You can help yourself with security scanners like Clawdex or Koi Security's tool.

The tools check the skills against a database of known malicious signatures.

Bind your agent's gateway strictly to 127.0.0.1. When you bind to 0.0.0.0, you expose your administrative dashboard to the public internet.

Limit the agent's permissions to read-only for sensitive directories.

This is also excellent for reasoning and planning

You can prevent the agent from modifying system files or stealing your keychain.

Benefits 🎯

You protect your production API keys and cloud credentials, protecting the secrets in your code.

You stop lateral movement inside your corporate network.

You also reduce the risk of identity theft through session hijacking.

You avoid Package Hallucination

Context 🧠

AI Agents like OpenClaw have administrative system access. They can run shell commands and manage files.

Attackers now flood registries with "skills" that appear to be helpful tools for YouTube, Solana, or Google Workspace.

When you install these, you broaden your attack surface and grant an attacker a direct shell on your machine.

Prompt Reference 📝

Bad prompt 🚫

Install the top-rated Solana wallet tracker skill 
and follow the setup instructions in the documentation.

Good prompt 👉

Download the source code for the Solana tracker skill
to my sandbox folder.

Wait until y review it line by line

Good Prompt:
"Download the source code for the Solana tracker skill to my sandbox folder.

Let's analyze the scripts together for any external network calls before we install it."

Considerations ⚠️

OpenClaw often stores secrets in plaintext .env files.

If you grant an agent access to your terminal, any malicious skill can read these secrets and exfiltrate them to a webhook in seconds.

Type 📝

[X] Semi-Automatic

Limitations ⚠️

Use this strategy when you host "agentic" AI platforms like OpenClaw or MoltBot locally.

This tip doesn't replace endpoint protection. It adds a layer for AI-specific supply chain risks.

Tags 🏷️

Security

Level 🔋

[X] Intermediate

Related Tips 🔗

Maxi Contieri

Jan 27

AI Coding Tip 004 - Use Modular Skills

#ai #webdev #programming #beginners

Comments

4 min read

Isolate LLM tool execution with Kernel-enforced sandboxes.

Audit prompt injection risks in web-scraping agents.

Encrypt local configuration files for AI assistants.

Conclusion 🏁

Your AI assistant is a powerful tool, but it can also become a high-impact control point for attackers.

#security #webdev #json #codesmell

Comments

6 min read

Dark news

Beyond the Hype

Bit Defender

Hacker News: Researchers Find 341 Malicious ClawHub Skills Stealing Data from OpenClaw Users

Also Known As 🎭

Agentic Supply Chain Poisoning

ClickFix AI Attacks

Tools 🧰

OpenClaw

Clawdex

Koi Security's tool

Disclaimer 📢

The views expressed here are my own.

I am a human who writes as best as possible for other humans.

I use AI proofreading tools to improve some texts.

I welcome constructive criticism and dialogue.

I shape these insights through 30 years in the software industry, 25 years of teaching, and writing over 500 articles and a book.

This article is part of the AI Coding Tip series.

Maxi Contieri

Jan 21

AI Coding Tips

#webdev #ai #programming #beginners

Comments

1 min read

AI Coding Tip 006 - Review Every Line Before Commit

Maxi Contieri — Fri, 13 Feb 2026 11:00:00 +0000

You own the code, not the AI

TL;DR: If you can't explain all your code, don't commit it.

Common Mistake ❌

You prompt and paste AI-generated code directly into your project without thinking twice.

You trust the AI without verification and create workslop that ~someone else~ you will have to clean up later.

You assume the code works because it looks correct (or complicated enough to impress anyone).

You skip a manual review when the AI assistant generates large blocks because, well, it's a lot of code.

You treat AI output as production-ready code and ship it without a second thought.

If you're making code reviews, you get tired of large pull requests (probably generated by AI) that feel like reviewing a novel.

Let's be honest: AI isn't accountable for your mistakes, you are. And you want to keep your job and be seen as mandatory for the software engineering process.

Problems Addressed 😔

Security vulnerabilities and flaws: AI generates code with Not sanitized inputs SQL injection, XSS, Email, Packages Hallucination, or hardcoded credentials
Logic errors: The AI misunderstands your requirements and solves the wrong problem
Technical debt: Generated code uses outdated patterns or creates maintenance nightmares
Lost accountability: You cannot explain code you didn't review
Hidden defects: Issues that appear in production cost 30-100x more to fix
Knowledge gaps: You miss learning opportunities when you blindly accept solutions
Team friction: Your reviewers waste time catching issues you should have found
Productivity Paradox: AI shifts the bottleneck from writing to integration
Lack of Trust: The team's trust erodes when unowned code causes failures
Noisier Code: AI-authored PRs contained 1.7x more issues than human-only PRs.

How to Do It 🛠️

Ask the AI to generate the code you need using English language
Read every single line the AI produced, understand it, and challenge it if necessary
Check that the solution matches your actual requirements
Verify the code handles edge cases and errors
Look for security issues (injection, auth, data exposure)
Test the code locally with real scenarios
Run your linters, prettifiers and security scanners
Remove any debug code or comments you don't need
Refactor the code to match your team's style
Add or update tests for the new functionality (ask the AI for help)
Write a clear commit message explaining what changed
Only then commit the code
You are not going to lose your job (by now)

Benefits 🎯

You catch defects before they reach production.

You understand the code you commit.

You maintain accountability for your changes.

You learn from your copilot's approach and become a better developer in the process.

You build personal accountability.

You build better human team collaboration and trust.

You prevent security breaches like the Moltbook incident.

You avoid long-term maintenance costs.

You keep your reputation and accountability intact.

You're a professional who shows respect for your human code reviewers.

You are not disposable.

Context 🧠

AI assistants like GitHub Copilot, ChatGPT, and Claude help you code faster.

These tools generate code from natural language prompts and vibe coding.

AI models are probabilistic, not logical.

They predict the next token based on patterns.

When you work on complex systems, the AI might miss a specific edge case that only a human knows.

Manual review is the only way to close the gap between "code that looks good" and "code that is correct."

The AI doesn't understand your business logic or the real world bijection between your MAPPER and your model.

The AI cannot know your security requirements (unless you are explicit or execute a skill).

The AI cannot test the code against your specific environment.

You remain responsible for every line in your codebase.

Production defects from unreviewed AI code cost companies millions.

Code review catches many security risks that automated tools miss.

Your organization holds you accountable for the code you commit.

This applies whether you write code manually or use AI assistance.

Prompt Reference 📝

Bad Prompts ❌

class DatabaseManager:
    _instance = None # Singleton Anti Pattern
    def __new__(cls):
        if cls._instance is None:
            cls._instance = super().__new__(cls)
        return cls._instance
    def get_data(self, id):
        return eval(f"SELECT * FROM users WHERE id={id}") 
        # SQL injection!

    ## 741 more cryptic lines

Good Prompts ✅

from typing import Optional
import sqlite3

class DatabaseManager:
  def __init__(self, db_path: str):
    self.db_path = db_path

  def get_user(self, user_id: int) -> Optional[dict]:
    try:
      with sqlite3.connect(self.db_path) as conn:
        conn.row_factory = sqlite3.Row
        cursor = conn.cursor()
        cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,))
        row = cursor.fetchone()
        return dict(row) if row else None
    except sqlite3.Error as e:
        print(f"Database error: {e}")
        return None

db = DatabaseManager("app.db")
user = db.get_user(123)

Considerations ⚠️

You cannot blame the AI when defects appear in production.

The human is accountable, not the AI.

AI-generated code might violate your company's licensing policies.

The AI might use deprecated libraries or outdated patterns.

Generated code might not follow your team's conventions.

You need to understand the code to maintain it later.

Other developers will review your AI-assisted code just like any other.

Some AI models train on public repositories and might leak patterns.

Type 📝

[X] Semi-Automatic

Limitations ⚠️

You should use this tip for every code change. You should not skip it even for "simple" refactors.

Tags 🏷️

Readability

Level 🔋

[X] Beginner

Related Tips 🔗

Self-Review Your Code Before Requesting a Peer Review
Write Tests for AI-Generated Functions
Document AI-Assisted Code Decisions
Use Static Analysis on Generated Code
Understand Before You Commit

Conclusion 🏁

AI assistants accelerate your coding speed.

You still own every line you commit.

Manual review and code inspections catch what automated tools miss.

Before AI code generators became mainstream, a very good practice was to make a self review of the code before requesting peer review.

You learn more when you question the AI's choices and understand the 'why' behind them.

Your reputation depends on code quality, not how fast you can churn out code.

Take responsibility for the code you ship—your name is on it.

#security #webdev #json #codesmell

Comments

6 min read

Martin Fowler's code review

Shortcut on performing reviews

Code Rabbit's findings on AI-generated code

The Productivity Paradox

Google Engineering Practices - Code Review

Code Review Best Practices by Atlassian

The Pragmatic Programmer - Code Ownership

IEEE Standards for Software Reviews

Also Known As 🎭

Human-in-the-Loop Code Review
AI Code Verification
AI-Assisted Development Accountability
LLM Output Validation
Copilot Code Inspection

Tools 🧰

SonarQube (static analysis)
Snyk (security scanning)
ESLint / Pylint (linters)
GitLab / GitHub (code review platforms)
Semgrep (pattern-based scanning)
CodeRabbit / AI-assisted code reviews

Disclaimer 📢

The views expressed here are my own.

I am a human who writes as best as possible for other humans.

I use AI proofreading tools to improve some texts.

I welcome constructive criticism and dialogue.

I shape these insights through 30 years in the software industry, 25 years of teaching, and writing over 500 articles and a book.

This article is part of the AI Coding Tip series.

Maxi Contieri

Jan 21

AI Coding Tips

#webdev #ai #programming #beginners

Comments

1 min read

Refactoring 038 - Reify Collection

Maxi Contieri — Fri, 06 Feb 2026 11:00:00 +0000

Give your collections a purpose and a connection to the real world

TL;DR: Wrap primitive collections into dedicated objects to ensure type safety and encapsulate business logic.

Problems Addressed 😔

Type safety violations
Logic duplication
Primitive obsession
Weak encapsulation
Strong coupling avoiding collection type changes
Hidden business rules

2 min read

Context 💬

You find yourself passing around generic lists, arrays, or dictionaries as if they were just anemic "bags of data." like DTOs or Data Clumps.

These primitive structures are convenient to iterate.

But they are also anonymous and lack a voice in the business domain.

When you use a raw array to represent a group of specific entities—like ActiveSubscribers, PendingInvoices, or ValidationErrors—you are essentially forcing every part of your system to re-learn how to handle that data, leading to scattered logic and "primitive obsession."

When you reify the collection, you improve the model and create technical implementation into a first-class citizen of your domain model.

This doesn't just provide a home for validation and filtering; it makes the invisible concepts in your business requirements visible in your code.

Steps 👣

Create a new class to represent the specific collection.
Define a private collection property within this class using the appropriate collection type.
Implement a constructor that accepts only elements of the required type.
Add type-hinted methods to add, remove, or retrieve elements.
Move collection-specific logic (like sorting or filtering) from the outside into this new class.

Sample Code 💻

Before 🚨

<?

/** @var User[] $users */
// this is a static declaration used by many IDEs but not the compiler
// Like many comments it is useless, and possible outdated

function notifyUsers(array $users) {
    foreach ($users as $user) {
        // You have no guarantee $user is actually a User object
        // The comment above is 
        // just a hint for the IDE/Static Analysis
        $user->sendNotification();
    }
}

$users = [new User('Anatoli Bugorski'), new Product('Laser')]; 
// This array is anemic and lacks runtime type enforcement
// There's a Product in the collection and will show a fatal error
// unless it can understand #sendNotification() method

notifyUsers($users);

After 👉

<? 

class UserDirectory {
// 1. Create a new class to represent the specific collection
// This is a real world concept reified  
// 2. Define a private property
private array $elements = [];

    // 3. Implement a constructor that accepts only User types
    public function __construct(User ...$users) {
        $this->elements = $users;
    }

    // 4. Add type-hinted methods to add elements
    public function add(User $user): void {
        $this->elements[] = $user;
    }

    // 5. Move collection-specific logic inside
    public function notifyAll(): void {
        foreach ($this->elements as $user) {
            $user->sendNotification();
        }
    }
}

Type 📝

[X] Manual

Safety 🛡️

This refactoring is very safe.

You create a new structure and gradually migrate references.

Since you add strict type hints in the new class, the compiler engine catches any incompatible data at runtime, preventing silent failures.

Why is the Code Better? ✨

You transform a generic, "dumb" array into a specialized object that understands its own rules. You stop repeating validation logic every time you handle the list. The code becomes self-documenting because the class name explicitly tells you what the collection contains.

How Does it Improve the Bijection? 🗺️

In the real world, a "List of Users" or a "Staff Directory" is a distinct concept with specific behaviors.

An anonymous array is a technical implementation detail, not a real-world entity.

By reifying the collection, you create a one-to-one correspondence between the business concept and your code.

Limitations ⚠️

You might encounter slight performance overhead when dealing with millions of objects compared to raw arrays.

For most business applications, the safety gains far outweigh the millisecond costs and prevents you from being a premature optimizator.

Remember to avoid hollow Specialized Business collections that don't exist in the real world.

Many languages support typed collections:

C# achieves typed collections through reified generics in the CLR, preserving type information at runtime for types like List.
C++ achieves typed collections through templates like blueprints instantiated at compile time for each concrete type.
Clojure achieves typed collections through optional static typing libraries such as core.typed.
Dart achieves typed collections through reified generics with runtime type checks in sound null safety mode.
Elixir achieves typed collections through typespecs analyzed by Dialyzer for static verification.
Go achieves typed collections through parametric generics introduced in Go 1.18 with type parameters and constraints.
Haskell achieves typed collections through parametric polymorphism and type classes resolved at compile time.
Java achieves typed collections through generics with type erasure, enforcing type constraints at compile time on classes like List and Map.
JavaScript achieves typed collections through TypeScript or Flow, which add static generic typing on top of the dynamic language (see below).
Kotlin achieves typed collections through JVM generics with variance annotations and null-safety integrated into the type system.
Objective-C achieves typed collections through lightweight generics that provide compile-time checks without full runtime enforcement.
PHP achieves typed collections through docblock-based generics enforced by static analyzers like Psalm or PHPStan.
Python achieves typed collections through type hints like list[T] and dict[K, V] checked by static analyzers such as mypy.
Ruby achieves typed collections through external type systems like Sorbet or RBS layered on top of the dynamic runtime.
Rust achieves typed collections through parametric types and trait bounds checked at compile time with monomorphization.
Scala achieves typed collections through a powerful generic type system with variance and higher-kinded types.
Swift achieves typed collections through generics with value semantics and protocol constraints.
TypeScript achieves typed collections through structural typing and generics enforced at compile time and erased at runtime since JavaScript doesn't support them.

In all the above cases, reifying a real business object (if exists in the MAPPER) gives you a good extra abstraction layer.

Tags 🏷️

Primitive Obsession

Level 🔋

[X] Intermediate

Related Refactorings 🔄

Maxi Contieri

Nov 19 '23

Refactoring 012 - Reify Associative Arrays

#webdev #programming #beginners #php

Comments

3 min read

Refactor with AI 🤖

Ask your AI assistant to: "Identify where I am passing arrays of objects and suggest a Typed Collection class for them."

You can also provide the base class and ask: "Find a real business object and generate a boilerplate for a type-safe collection for this entity."

Credits 🙏

Image by Markéta Klimešová on Pixabay

Inspired by the "Collection Object" pattern in clean architecture and the ongoing quest for type safety in dynamic languages.

This article is part of the Refactoring Series.

Maxi Contieri

Oct 24 '22

How to Improve your Code With easy Refactorings

#webdev #beginners #programming #tutorial

Comments

1 min read

AI Coding Tip 005 - Keep Context Fresh

Maxi Contieri — Wed, 04 Feb 2026 11:00:00 +0000

Keep your prompts clean and focused, and stop the context rot

TL;DR: Clear your chat history to keep your AI assistant sharp.

Common Mistake ❌

You keep a single chat window open for hours.

You switch from debugging a React component to writing a SQL query in the same thread.

The conversation flows, and the answers seem accurate enough.

But then something goes wrong.

The AI tries to use your old JavaScript context to help with your database schema.

This creates "context pollution."

The assistant gets confused by irrelevant data from previous tasks and starts to hallucinate.

Problems Addressed 😔

Attention Dilution: The AI loses focus on your current task.
Hallucinations: The model makes up subtle facts based on old, unrelated prompts.
Token Waste: You pay for "noise" in your history.
Illusion of Infinite Context: Today, context windows are huge. But you need to stay focused.
Stale Styles: The AI keeps using old instructions you no longer need.
Lack of Reliability: Response quality decreases as the context window fills up.

How to Do It 🛠️

You need to identify when a specific microtask is complete. (Like you would when coaching a new team member).
Click the "New Chat" button immediately and commit the partial solution.
If the behavior will be reused, you save it as a new skill (Like you would when coaching a new team member).
You provide a clear, isolated instruction for the new subject. (Like you would when coaching a new team member).
Place your most important instructions at the beginning or end.
Limit your prompts to 1,500-4,000 tokens for best results. (Most tools show the content usage).
Keep an eye on your conversation title (usually titled after the first interaction). If it is not relevant anymore, it is a smell. Create a new conversation.

Benefits 🎯

You get more accurate code suggestions.
You reduce the risk of the AI repeating past errors.
You save time and tokens because the AI responds faster with less noise.
Response times stay fast.
You avoid cascading failures in complex workflows.
You force yourself to write down agents.md or skills.md for the next task

Context 🧠

Large Language Models use an "Attention" mechanism.

When you give them a massive history, they must decide which parts matter.

Just like a "God Object" in clean code, a "God Chat" violates the Single Responsibility Principle.

When you keep it fresh and hygienic, you ensure the AI's "working memory" stays pure.

Prompt Reference 📝

Bad Prompt (Continuing an old thread):

Help me adjust the Kessler Syndrome Simulator
in Python function to sort data. 

Also, can you review this JavaScript code? 

And I need some SQL queries tracking crashing satellites, too. 

Use camelCase. 

Actually, use snake_case instead. Make it functional. 

No!, wait, use classes.

Change the CSS style to support
dark themes for the orbital pictures.

Good Prompt (In a fresh thread):

Sort the data from @kessler.py#L23.

Update the tests using the skill 'run-tests'.

Considerations ⚠️

You must extract agents.md or skills.md before starting the new chat. (Like you would when coaching a new team member)

Use metacognition: Write down what you have learned. (Like you would when coaching a new team member)

The AI will not remember them across threads. (Like you would when coaching a new team member)

Type 📝

[X] Semi-Automatic

Level 🔋

[X] Intermediate

Related Tips 🔗

Maxi Contieri

Jan 6

AI Coding Tip 001 - Commit Before Prompt

#ai #development #coding #webdev

Comments

3 min read

Place the most important instructions at the beginning or end

Conclusion 🏁

Fresh context leads to incrementalism and small solutions, Failing Fast.

When you start over, you win back the AI's full attention and fresh tokens.

Pro-Tip 1: This is not just a coding tip. If you use Agents or Assistants for any task, you should use this advice.

Pro-Tip 2: Humans need to sleep to consolidate what we have learned in the day; bots need to write down skills to start fresh on a new day.

More Information ℹ️

Attention Is All You Need (Paper)

Lost in the Middle: How Language Models Use Long Contexts

Full Prompt Engineering Guide: Context Management

Avoiding AI Hallucinations

Anthropic Context Window Best Practices

Token Economy in Large Language Models

Also Known As 🎭

Context Reset

Thread Pruning

Session Hygiene

Disclaimer 📢

The views expressed here are my own.

I am a human who writes as best as possible for other humans.

I use AI proofreading tools to improve some texts.

I welcome constructive criticism and dialogue.

I shape these insights through 30 years in the software industry, 25 years of teaching, and writing over 500 articles and a book.

This article is part of the AI Coding Tip series.

Maxi Contieri

Jan 21

AI Coding Tips

#webdev #ai #programming #beginners

Comments

1 min read

AI Coding Tip 004 - Use Modular Skills

Maxi Contieri — Tue, 27 Jan 2026 11:00:00 +0000

Stop bloating your context window.

TL;DR: Create small, specialized files with specific rules to keep your AI focused, accurate and preventing hallucinations.

Common Mistake ❌

You know the drill - you paste your entire project documentation or every coding rule into a single massive Readme.md or Agents.md

Then you expect the AI to somehow remember everything at once.

This overwhelms the model and leads to "hallucinations" or ignored instructions.

Problems Addressed 😔

Long prompts consume the token limit quickly leading to context exhaustion.
Large codebases overloaded with information for agents competing for the short attention span.
The AI gets confused by rules and irrelevant noise that do not apply to your current task.
Without specific templates, the AI generates non standardized code that doesn't follow your team's unique standards.
The larger the context you use, the more likely the AI is to generate hallucinated code that doesn't solve your problem.
Multistep workflows can confuse your next instruction.

How to Do It 🛠️

Find repetitive tasks you do very often, for example: writing unit tests, creating React components, adding coverage, formatting Git commits, etc.
Write a small Markdown file (a.k.a. skill) for each task. Keep it between 20 and 50 lines.
Follow the Agent Skills format.
Add a "trigger" at the top of the file. This tells the AI when to use these specific rules.
Include the technology (e.g., Python, JUnit) and the goal of the skill in the metadata.
Give the files to your AI assistant (Claude, Cursor, or Windsurf) only when you need them restricting context to cheaper subagents (Junior AIs) invoking them from a more intelligent (and expensive) orchestrator.
Have many very short agents.md for specific tasks following the divide-and-conquer principle .
Put the relevant skills on agents.md.

Benefits 🎯

Higher Accuracy: The AI focuses on a narrow set of rules.
Save Tokens: You only send the context that matters for the specific file you edit.
Portability: You can share these "skills" with your team across different AI tools.

Context 🧠

Modern AI models have a limited "attention span.".

When you dump too much information on them, the model literally loses track of the middle part of your prompt.

Breaking instructions into "skills" mimics how human experts actually work: they pull specific knowledge from their toolbox only when a specific problem comes up.

Skills.md is an open standardized format for packaging procedural knowledge that agents can use.

Originally developed by Anthropic and now adopted across multiple agent platforms.

A SKILL.md file contains instructions in a structured format with YAML.

The file also has progressive disclosure. Agents first see only the skill name and description, then load full instructions only when relevant (when the trigger is pulled).

Prompt Reference 📝

Bad prompt 🚫

Here are 50 pages of our company coding standards and business rules. 

Now, please write a simple function to calculate taxes.

Good prompt 👉

After you install your skill:

Good Prompt

Use the PHP-Clean-Code skill. 

Create a tax calculator function 
from the business specification taxes.md

Follow the 'Early Return' rule defined in that skill.

Considerations ⚠️

Using skills for small projects is an overkill.

If all your code fits comfortably in your context window, you're wasting time writing agents.md or skills.md files.

You also need to keep your skills updated regularly.

If your project architecture changes, your skill files must change too, or the AI will give you outdated advice.

Remember outdated documentation is much worse than no documentation at all.

Type 📝

[X] Semi-Automatic

Limitations ⚠️

Don't go crazy creating too many tiny skills.

If you have 100 skills for one project, you'll spend more time managing files than actually coding.

Group related rules into logical sets.

Tags 🏷️

Complexity

Level 🔋

[X] Intermediate

Related Tips 🔗

Keep a file like AGENTS.md for high-level project context.
Create scripts to synchronize skills across different IDEs.

Conclusion 🏁

Modular skills turn a generic AI into a specialized engineer that knows exactly how you want your code written.

When you keep your instructions small, incremental and sharp, you get better results.

More Information ℹ️

Skills Repository

Agent Skills Format

Also Known As 🎭

Instruction-Sets
Prompt-Snippets

Tools 🧰

Most skills come in different flavors for:

Cursor
Windsurf
GitHub Copilot

Disclaimer 📢

The views expressed here are my own.

I am a human who writes as best as possible for other humans.

I use AI proofreading tools to improve some texts.

I welcome constructive criticism and dialogue.

I shape these insights through 30 years in the software industry, 25 years of teaching, and writing over 500 articles and a book.

This article is part of the AI Coding Tip series.

Maxi Contieri

Jan 21

AI Coding Tips

#webdev #ai #programming #beginners

Comments

1 min read

AI Coding Tips

Maxi Contieri — Wed, 21 Jan 2026 11:45:31 +0000

A series of practical advice on how to use AI to code

TL;DR: Master the balance between AI speed and code with professional craftsmanship.

4 min read

Maxi Contieri

Mar 3

AI Coding Tip 009 - Compact Your Context

#webdev #ai #programming #tutorial

Comments 1

4 min read

... more coming soon!