AI Skills and Agents Samples

A skill is a text file that teaches an AI coding assistant how to do a specific job — kind of like a recipe card, or step-by-step instructions you'd give a new team member. Instead of typing out the same detailed instructions every single time, you write them once, save them as a skill, and reuse them whenever you need them. This repository is a collection of skills like that, built to work the same way across three different AI tools: Codex, Claude Code, and GitHub Copilot CLI.

Quick start

git clone https://github.com/khadir-syed/ai-agent-skills.git && cd ai-agent-skills
mkdir -p .claude
./install.sh root-cause-investigator

(The mkdir step matters — a fresh clone has no .claude, .agents, or .github folder yet, and install.sh only copies into folders that already exist. Using Codex or Copilot CLI instead? Make .agents or .github instead of .claude.)

Then, in Codex, Claude Code, or Copilot CLI, try the first prompt from Try the samples in the Skills doc. On Claude Code specifically, this first try can be inconsistent — see Troubleshooting if it asks you for real system access instead of just running the investigation.

Contents

• About this collection
• Skills (Stage 1) — how a skill works, the full list of skills, example runs, and prompts you can try yourself
• Agents (Stage 2) — six agents, some that check in with you at every step and some that check in less, example runs, and tests where we tried to trick them
• Orchestrators (Stage 3) — a "router" that figures out which agent should handle your request
• Use a skill, agent, or orchestrator in an AI coding tool
• Troubleshooting
• What these samples do not provide
• Customise them
• Official documentation

About this collection

This collection is being built up in three stages, one at a time:

1. Skills
2. Agents
3. Orchestrators — one thing deciding which agent to use

Stage 1 (Skills) covers four topic areas (we call them "domains"), and each one has the same three kinds of skill: one that only looks and reports back, one that's allowed to write something (but always asks first), and one that runs through a checklist. Learn the pattern once, and every other skill just feels like a variation on it. See skills/README.md for the full list.

Stage 2 (Agents) takes one real job per domain and does it twice — once where a human approves every single step ("controlled"), and once where a human approves fewer steps ("autonomous") — so you can see exactly what changes when a human isn't checking in as often. See agents/README.md for all six agents, how we tested them, and what happened when we tried to trick one into skipping a step.

Stage 3 (Orchestrators) adds a "router" — something that reads your request and figures out which Stage 2 agent should handle it, then hands it off, in both a "checks in every step" and a "checks in less" version. See orchestrators/README.md for how each one works, example runs, and a real bug we found and fixed while testing.

More skills, agents, orchestrators, and topic areas are welcome — see CONTRIBUTING.md if you'd like to add one.

Use a skill in an AI coding tool

Copy the whole skill folder — not just the one file inside it — into a location your AI tool looks in. You can do this by hand, or use the install.sh script below to do it for you. This works the same way whether it's a Stage 1 skill, a Stage 2 agent, or a Stage 3 orchestrator — they're all just text files, installed the same way. If you install an orchestrator, also install the agent(s) it might hand off to (bug-fix-agent, feature-launch-readiness-agent-controlled or -autonomous, content-publish-readiness-agent-controlled or -autonomous), so it has something to hand off to.

If your tool doesn't notice a skill you just added, close it and reopen it. The exact way you invoke a skill can change as these tools update, so check your tool's own docs if something here looks out of date.

CLI apps vs. desktop apps

The table above is for the CLI tools you type commands into (Codex CLI, Claude Code CLI or its editor plugin, Copilot CLI) and the Codex desktop app. All of these read a skill straight from a project folder, so copying the folder in is all you need to do.

The Claude desktop app and Claude on the web are different. They don't look at your project folder at all. Instead, you upload skills as a ZIP file through the settings menu:

1. Settings → Capabilities → turn on "Code execution and file creation." A skill won't run without this turned on.
2. Customize → Skills → + → Create skill → Upload a skill.
3. Pick a ZIP file of the skill folder, with SKILL.md right at the top of the ZIP — not buried inside another folder. This is the most common reason an upload fails.
4. Turn the skill on after uploading. Uploading it doesn't automatically turn it on.

This upload method works for any skill, agent, or orchestrator in this repo that's just text — including both request-router-agent-controlled and request-router-agent-autonomous. If you upload a router, also upload and turn on the agent(s) it might route to, so it has something to hand off to, same as with the CLI.

It does not work for test-fix-loop-agent, because that one is an actual computer program (Python), not a text instruction file, and Claude Desktop and Claude web can't run programs. That one only works from a terminal — see its own README.

Using the install script

install.sh is just a helper — it's not a skill itself, it simply copies a skill folder for you so you don't have to do it by hand. It copies into whichever folders your tools already use on your computer. It doesn't do anything else: no internet access, no deleting files, nothing sneaky.

./install.sh root-cause-investigator

It looks for <skill-name> inside skills/<domain>/, agents/<domain>/, and orchestrators/ — so this exact same command also installs request-router-agent-controlled or request-router-agent-autonomous.

By default it only copies into your current project's folders (.agents/skills/, .claude/skills/, .github/skills/) — whichever of those already exist. Add --global to also copy into your personal home folder, so the skill is available in every project:

./install.sh --global changelog-entry-drafter

Troubleshooting

Real problems we actually ran into while building and testing this repo — not guesses about what might go wrong.

A skill doesn't show up when I try to use it. Your tool only checks for new skills when it starts up, not while it's running. Close it and reopen it after copying a new skill in. Also double check you copied the whole folder (SKILL.md plus its examples/ and references/ folders), not just the one SKILL.md file by itself.

A skill doesn't trigger unless I type its name exactly. That means the tool couldn't tell your plain-language request matched the skill — it's not a broken skill. Try typing the skill's name directly first (like /skill-name) to check it's installed at all, then make the skill's short description mention the situations it should catch.

On Claude Code, the very first sample prompt can be genuinely inconsistent — even the /skill-name form. We tested this for real on a fresh install: the root-cause-investigator sample prompt (both as plain language and as /root-cause-investigator ...) sometimes ran the actual investigation as documented, and sometimes asked for real system access instead — across several tries, on identical wording, with no pattern tied to which phrasing was used. Codex was consistent in our testing. If this happens to you: try again in a fresh session (it may simply work the next time), and check whether a personal ~/.claude/CLAUDE.md is competing with the skill — see "A skill on Claude Code ignores its own rules..." further down this list. This repo now ships a project-level CLAUDE.md and AGENTS.md that fixes this for both tools — see that entry for what it does and why it's still not a 100% guarantee.

install.sh printed "Nothing copied." It only copies into folders that already exist in your current project (.agents/, .claude/, .github/) — it won't create them for you. Make one yourself first (like mkdir .claude), or use --global to install into your personal home folder instead.

Claude Desktop can't see a skill that works fine in Claude Code. That's expected — they work differently. Claude Code reads straight from your project's .claude/skills/ folder. Claude Desktop needs the skill uploaded as a ZIP file through Settings, with code execution turned on (see CLI apps vs. desktop apps above).

A skill that's supposed to ask before writing a file didn't ask the second time. Check whether an earlier message accidentally gave it standing permission (something like "yes, and don't ask again"). If you never said that, this is a bug in that skill's wording — it should ask every single time, not remember one "yes" as permission forever.

A skill ignores its own rules, or a Codex answer comes wrapped in unrelated headers. This can happen if you have your own personal instructions file — ~/.claude/CLAUDE.md for Claude Code, or ~/.codex/AGENTS.md for Codex (a global file you wrote yourself, separate from this repo). If those personal instructions give the AI a different job — for example, telling it to always give advice and ask discussion questions before doing anything — they can win out over a skill's own instructions, especially on a request that sounds like it needs a judgment call. We saw this happen for real: on Claude Code, a router skill was asked a genuinely tricky question, and instead of following its own "state the mix-up, ask which one" rule, it answered as a general advisor instead, because that's what a personal CLAUDE.md file told it to prioritize. Codex has the same kind of competing file at ~/.codex/AGENTS.md; in our testing it never changed Codex's actual answer or skipped an approval step, but it did sometimes wrap a correct answer in unrequested "Critique / Alternatives / Pros & Cons" headers from that personal file.

This repo ships a project-level CLAUDE.md and AGENTS.md at the repo root specifically to fix this: when you explicitly invoke one of this repo's skills, agents, or orchestrators, these files tell the tool to follow that skill's own instructions as written instead of layering your personal file's persona or format on top. In our testing this fixed the formatting bleed-through on Codex completely, and made the Claude Code behavior noticeably more consistent (it's still not a 100% guarantee — if a skill still seems to "forget" its own rules, check your personal instructions file for something that could be pulling it in a different direction, before assuming the skill itself is broken).

GitHub shows a different name than what I typed for my commit. If your commit's email matches a verified email on a GitHub account (including the private @users.noreply.github.com kind), GitHub shows that account's name and picture instead of the plain text name you typed. This is just how GitHub displays things — it's not a bug, and it's not a sign your push failed.

What these samples do not provide

• They don't guarantee an AI tool will pick the right skill on its own.
• They don't give access to files, terminals, logs, databases, or outside services by themselves.
• They don't override your tool's own permission settings or your own instructions.
• Following the right format doesn't automatically make a diagnosis, draft, or check correct — you still need to read the output.
• These are learning examples, not a real production system for handling incidents, releases, or security.

Customise them

Copy a sample and change one thing at a time:

1. Rewrite the short description so it matches the kinds of problems you actually want it to catch.
2. Add places specific to your own project that it should look at — for example, "check the browser, then the API, then the database."
3. Add whatever sources of evidence you actually have available.
4. Change the report format without removing the parts that separate facts from guesses.
5. Test it with a real, known problem — and also test it with something it should not react to.

Remember: saying a skill is "read-only" describes what it's supposed to do. It's your AI tool's own permission settings that actually stop it from doing more than that.

Official documentation

• OpenAI: Build skills for ChatGPT and Codex
• Anthropic: Extend Claude with skills
• GitHub: Add agent skills for GitHub Copilot CLI