Instructions, Agents and Skills
Guide to Understand AI Tools and How to Use Them
Whatever you use AI tools like Github Copilot, Codex or Claude Code for, most of them work in a similar way, but it can get confusing when you are new to it, and you do not understand the basic concepts of how they work.
Every harness is different, so please refer to the documentation of the specific tool you are using, but most of them work in a similar way, so understanding the basic concepts will help you to use them better.
Instructions
All three of the tools I mentioned can be steered with instructions. It is one markdown file, which gives the model the most important context and instructions on how to behave, what to do, what to not do, and so on.
It is the most important file in your project, because it is automatically loaded during any interaction with the model.
In Codex it is called AGENTS.md, in Claude Code it is called CLAUDE.md and in GitHub Copilot it is called copilot-instructions.md.
Most of the tools have some sort of compatibility with each other, so you can use the same instructions for all of them, but Claude is a bit more strict about the naming and placing of the folder, so consult the documentation.
Do
- Follow existing code style & naming conventions
- Declare tech stack & preferred libraries upfront
- Use existing architectural patterns (modular, event-driven, component-based)
- Add security checks & error handling for external services
- Document: purpose, inputs, outputs, configuration
- Link to external docs rather than copying them
- Note only required environment variables
Don’t
- Include obvious bash commands
- Restate standard language conventions
- Copy detailed API docs (link instead)
- Add repo etiquette or PR conventions
- Write long tutorials or explanations
- Describe every file in the repo
- Mention self-evident practices like “write clean code”
Keep the file concise and to the point, because it is loaded during every interaction with the model. Try to keep it under 500 lines, because it can get too long and the model will start to forget important information.
Take into consideration that model looses sharpness with more context.
All these main instructions file, you can add to your project folder / file specific instructions.
In Codex you can add AGENTS.override.md file, which will override the main instructions (Source), in the Claude you can add to the folder another CLAUDE.md or add rule to the rule folder under .claude/rules/ (Source).
In GitHub Copilot you can add more *.instructions.md files, which will be loaded when you are working on the specific file, which is defined in YAML front matter of the instructions file. For example applyTo: ”**/*.py” will apply the instructions only when you are working on Python files. (Source)
Agents
With agents, you can give the model a persona and set of instructions how to behave and what to do.
Instructions are intended for giving context, but agents are intended for giving a persona and set of instructions on how to behave and what to do.
For example, you can create an agent called “Code Reviewer”, which will have instructions on how to review code, navigate code and give feedback. Then you can ask the model to review your code and it will behave like a code reviewer.
The agent should not contain rules for how the code should look like, it is up to the instructions file, but it should contain rules for how the model should behave when it is asked to review code. Avoid duplication of context.
Couple of ideas for agents:
- Code Reviewer
- Code Explainer
- Code Refactorer
- Code Tester
- Code Debugger
- Code Optimizer
- Code Documenter
- Code Summarizer
- Code Translator
- Code Architect
Github Copilot has a nice repository of agents for inspiration at Github and also how to create your own agents (Source).
Important is to define tools for the agent and also restrict them. For example, a reviewer does not need to have write access to the code, it just needs to read it and give feedback. Refactorer needs to have write access.
Once again, all platforms have some different way of implementing it.
Claude has subagents, which you can define under the agents folder in the .claude and more specifics and examples, you can find in the documentation (Source).
Codex’s implementation of the agents is still experimental and it is still subject to change, but you can find more information here (Source).
The implementation of Codex and Claude is more focused on orchestration of multiple agents, while Github Copilot is more focused on single agent, which guides you in the chat session and can handout tasks to other agents afterwards.
Skills
Skills are probably the most unified implementation across all platforms. They provide a way to extend the capabilities of the model and give it access to external tools, automate repeated actions, APIs and other resources.
For example, you want to show how to reach the API of your project, you can create a skill for it, which will have instructions on how to use the API, what are the endpoints, what are the parameters and so on. Then you can ask the model to use the skill and it will do it for you. You can even add scripts directly to use.
Under your model provider, create a skill folder and add folder, where you will define your skill in SKILL.md file. In the file, you will define the instructions for the skill, what it does, how to use it and so on. You can also add scripts to the skill folder, which will be loaded when the skill is used.
Give it descriptive name and description in YAML front matter, so the model can properly identify when it is needed. Ideally, when you know what you want to do, you can just ask the model to use the skill (or explicitly add it) and it will do it for you.
Do
- Give it a descriptive name and description in YAML front matter
- Define clear instructions on how to use the skill
- Add scripts to automate repeated actions under /scripts folder or if is template add it to /templates folder
- use /references to link to external documentation, instead of writing extensive SKILL.md file
- define error handling, if the model fails to navigate the instructions
- keep the length under the 5000 words
- do not overload the model with too many skills - ideally 20-50 skills
This is mostly based on the Anthropic guide to skills (Source). You can also use skill to create skill here
For skills, feel free to visit the Github repository of the awesome skills for inspiration: Github or dedicated side for skills (Source).
Conclusion
There are many different ways how to use AI tools, but understanding the basic concepts of instructions, agents and skills are becoming more and more important, because they are the building blocks of how to use AI tools effectively.
They can help you and your team to get better results and accelerate your development process, but it is important to understand how they work and how to use them properly.
Still, avoid overloading the model with too much context, because it can lead to worse results. Try to keep it concise and to the point. Models using large chunk of the context window, start to lose their sharpness and deliver worse results (Source).
For more tips and tricks on how to use AI tools effectively, check out my previous article AI Tips and Tricks.
Socials
Thanks for reading this article!
For more content like this, follow me here or on X or LinkedIn.
