{"slug": "senior-agent-skills-make-your-agent-act-as-a-senior", "title": "Senior-agent-skills, make your agent act as a senior", "summary": "Aditya Arakeri released senior-agent-skills, a set of eight portable playbooks that make coding agents behave like careful senior engineers, working identically across Claude Code, Codex CLI, Google Antigravity, OpenCode, GitHub Copilot, and Cursor. The skills cover the full development loop from repo reconnaissance to committing, with a single SKILL.md format and zero dependencies.", "body_md": "Agent skills · showcase and setup\n\n# Make a coding agent behave like a careful senior engineer.\n\nEight portable playbooks that cover the whole loop, from understanding a repo to committing the diff. One `SKILL.md`\n\nformat, working identically across Claude Code, Codex CLI, Google Antigravity, OpenCode, GitHub Copilot, and Cursor.\n\n**8** skills\n\n**6** harnesses\n\n**1** shared format\n\n**0** dependencies\n\n## Install once, inherit everywhere\n\nThe installer symlinks each skill into every harness's directory, so you edit one canonical copy and all six pick it up. Restart your agent afterward so it rescans.\n\n```\ngit clone git@github.com:adityaarakeri/senior-agent-skills.git; cd senior-agent-skills\n./install.sh\n```\n\n./install.sh\n\nUser-level symlinks into the Claude, Codex, Gemini, and agents paths. The recommended default.\n\n./install.sh **--copy**\n\nIndependent copies instead of symlinks, for when you want each harness to drift on its own.\n\n./install.sh **--project**\n\nInstalls into the current repo, writing `.github/skills`\n\nfor Copilot so the team gets them on clone.\n\n## The eight skills\n\nEach one names a failure mode agents fall into, then hands the model a playbook to avoid it. They read in the order work actually happens.\n\n**>** They form one loop: understand, plan, build, then review, prove, commit, and back around.\n\n**01**· Understand\n\n### repo-recon\n\n**The problem.** Dropped into unfamiliar code, an agent guesses the structure, edits the wrong file, and reinvents a helper that already existed.\n\nForces a mapping pass first: read the manifest, learn the build and test commands, trace one existing flow end to end, and match the house conventions before changing anything.\n\n>\"I'm new to this repo. Map it before we add the webhook handler.\"\n\n**02**· Plan\n\n### plan-first\n\n**The problem.** On a wide or risky change, an agent sprints confidently in the wrong direction for twenty minutes before you get a chance to redirect it.\n\nProduces a one-page plan (goal, non-goals, ordered steps, rollback story) you approve before any code is written. The non-goals section alone kills most scope creep.\n\n>\"Use plan-first for adding rate limiting, then wait for my go-ahead.\"\n\n**03**· Build\n\n### tdd-loop\n\n**The problem.** \"Looks correct\" quietly stands in for \"is correct,\" and the gap ships straight to production.\n\nStrict red, green, refactor, with anti-cheating rules: never weaken an assertion to reach green, never mock the unit under test, never skip a failing test to come back later.\n\n>\"Implement the discount rule test-first.\"\n\n**04**· Diagnose\n\n### debug-protocol\n\n**The problem.** Guess-and-check editing burns context, patches the symptom, and teaches the agent nothing about the real fault.\n\nReproduce first, form one falsifiable hypothesis at a time, print what the value actually is, bisect when lost, and fix the root cause rather than the crash site.\n\n>\"This is failing in prod: <stack trace>. Use debug-protocol.\"\n\n**05**· Restructure\n\n### safe-refactor\n\n**The problem.** A refactor that silently changes behavior is the worst kind of bug: invisible in review, because everyone trusts the \"no behavior change\" promise.\n\nCharacterization tests first, structure and behavior changes in separate commits, one small mechanical step at a time with the suite run between each.\n\n>\"Extract the auth logic with safe-refactor.\"\n\n**06**· Review\n\n### self-review\n\n**The problem.** The author's context is a blindfold. You see what the code was meant to do, which is exactly not what a reviewer needs to see.\n\nReads the full diff as a skeptical stranger, walks the unhappy paths, sweeps the changed lines for injection and secrets, and strips leftover debug code.\n\n>\"Run self-review on the whole diff before we commit.\"\n\n**07**· Prove\n\n### verify-done\n\n**The problem.** \"Should work\" converts your one review pass into a debugging session, and trust erodes fast after the second time it happens.\n\nAn evidence gate before anything is called done: it builds, tests pass with real numbers reported, and the actual thing was run once on real input. Evidence or it did not happen.\n\n>\"Use verify-done before you say it's finished.\"\n\n**08**· Commit\n\n### git-hygiene\n\n**The problem.** Messy history breaks bisect and blame, and a single unasked-for destructive command torches trust instantly.\n\nAtomic commits with meaningful messages, plus a hard rule that force-push, reset, and clean require an explicit instruction naming the command before they run.\n\n>\"Commit this with git-hygiene, root cause in the message.\"\n\n## Install and trigger, per harness\n\nThe format is identical everywhere. Only the directory and the explicit-invoke syntax differ. Pick your tool.\n\n> reads from ~/.claude/skills/<name>/SKILL.md\n\n### Install\n\nPersonal in `~/.claude/skills/`\n\n, or per-repo in `.claude/skills/`\n\n. A project skill shadows a personal one of the same name, so one repo can carry stricter rules.\n\n### Trigger\n\nDescribe the task and the matching skill loads on its own, or name it directly to be sure: \"use the plan-first skill, then implement it.\"\n\n### Verify\n\nAsk \"which skills do you currently have available?\" and confirm all eight are listed. Restart the session after any edit.\n\n### Install\n\nInstaller targets `~/.codex/skills/`\n\n. Codex also reads `.agents/skills/`\n\nin a repo and `~/.agents/skills/`\n\nfor a personal library.\n\n### Trigger\n\nType `$`\n\nplus the name for an explicit call, `$debug-protocol this test is flaky`\n\n, or let it match on the description. Browse everything with `/skills`\n\n.\n\n### Verify\n\nRun `/skills`\n\nin the CLI. Disable one without uninstalling via an `[[skills.config]]`\n\nblock in `~/.codex/config.toml`\n\n, then restart.\n\n### Install\n\nReplaced Gemini CLI, which stopped serving consumer tiers on June 18, 2026 (enterprise Code Assist keeps legacy access). Global skills: `~/.gemini/config/skills/`\n\n, still under `~/.gemini`\n\n. Project scope: `.agents/skills/`\n\n, which `--project`\n\nalready writes.\n\n### Trigger\n\nSame description matching; Antigravity kept Agent Skills through the transition, so the files carry over unchanged. A permission prompt appears when a skill activates. Approve it; that is expected, not an error.\n\n### Verify\n\nRun `/skills`\n\nin Antigravity CLI, or ask \"what skills are available?\" in the desktop app. Migration docs live at antigravity.google/docs/gcli-migration.\n\n### Install\n\nNo directory of its own needed. OpenCode natively searches the `.claude/skills`\n\nand `.agents/skills`\n\npaths (project and global), so the default install covers it twice.\n\n### Trigger\n\nLoads through the native skill tool: the agent sees names and descriptions and pulls the full body only on a match. Describe the task or name the skill.\n\n### Verify\n\nDiscovery is cached at startup, so restart OpenCode after editing a skill. Per-agent permissions support wildcards like `internal-*`\n\n.\n\n### Install\n\nRepo-scoped. Canonical path is `.github/skills/`\n\n, committed so the team gets it on clone. Run `./install.sh --project`\n\nfrom the repo root. Copilot also auto-reads a repo's `.claude/skills/`\n\n.\n\n### Trigger\n\nDescription matching at session startup, across the coding agent, Copilot CLI, and VS Code agent mode. The most specific description wins when several could apply.\n\n### Verify\n\nType `/skills`\n\nin the VS Code Chat panel. Copilot reads only `name`\n\nand `description`\n\nfrom frontmatter, which this pack respects.\n\n### Install\n\nProject skills live in `.cursor/skills/`\n\nor the shared `.agents/skills/`\n\npath. The installer also targets `~/.cursor/skills/`\n\nfor Cursor builds with personal-skill support.\n\n### Trigger\n\nCursor discovers skills from their descriptions and loads the full instructions when the task matches. Name a skill directly when you want to force an explicit workflow.\n\n### Verify\n\nStart a fresh agent session after installation, then ask which skills are available and confirm all eight appear.\n\n## Preferred model and effort\n\nA common question: do the skills pick the model? They do not, on purpose. Here is how the layers divide, and what to set for the best results.\n\n**The harness owns model and effort. The skill inherits it.** No SKILL.md names a model or sets a reasoning budget, so the same file runs identically on all six harnesses. A skill is instructions handed to whatever engine is already running, the way a recipe cannot choose your oven. Set model and effort once at the harness level and every skill picks it up.\n\nThat said, the skills split cleanly into two kinds of work, and matching effort to the kind is where quality comes from.\n\nHigher reasoning\n\n#### Thinking-heavy skills\n\n- plan-first\n- debug-protocol\n- safe-refactor\n\nDesign decisions, hypothesis chains, and blast-radius analysis reward a stronger model and a raised thinking budget. Give these the headroom.\n\nStandard reasoning\n\n#### Procedural skills\n\n- repo-recon\n- tdd-loop\n- self-review\n- verify-done · git-hygiene\n\nThese are follow-the-checklist work. A default model at normal effort executes them faithfully, so save the budget for where it moves the needle.\n\nWhere each harness sets it:\n\nModel via `/model`\n\nor config; thinking effort is exposed on Opus-class models.\n\nModel plus a reasoning-effort level from minimal to high, set by config or flags.\n\nModel selected at the session level; the skill runs on whatever is active.\n\nProvider-agnostic. Model set per session or pinned to a named agent, Claude, GPT, or local.\n\nSession model selection, with auto-routing in newer builds, entirely outside the skill.\n\nModel selected per agent session; skill instructions run on the active model without choosing one themselves.\n\nOne nuance: some harnesses let a named subagent pin a specific model, and a skill's text can point at such an agent. That is still the harness choosing the model, invoked by name, not the skill reaching down to swap engines. The pack keeps all eight free of that so they stay portable.\n\n## How they chain in practice\n\nOn a real task you rarely touch all eight. The skills reference each other where the phases connect, so a natural chain forms on its own.\n\nGreenfield feature\n\n#### New code, unfamiliar repo\n\n- repo-recon maps the codebase\n- plan-first outlines it, you approve\n- tdd-loop builds it red then green\n- self-review reads the diff\n- verify-done proves it is finished\n\nProduction bug\n\n#### Broken, cause unknown\n\n- debug-protocol reproduces and diagnoses\n- tdd-loop writes the regression test first\n- verify-done confirms with evidence\n- git-hygiene commits, root cause in the message\n\nRefactor, thin coverage\n\n#### Restructure without breaking\n\n- safe-refactor writes characterization tests\n- structure changes in small verified steps\n- self-review confirms zero behavior change\n- verify-done checks old names return no hits\n\nUnattended run\n\n#### CI or full-auto\n\n- name skills explicitly in the command\n- implicit matching is weaker on terse prompts\n- always include verify-done\n- the run reports evidence, not a guess\n\n## When something misfires\n\nThe fix is almost always in the `description`\n\nfrontmatter, not the skill's body. Descriptions are the entire matching mechanism.\n\n## Skill never appears in the available list\n\nDiscovery failed. Check, in order: the file sits at the exact path the harness scans, the folder name matches the `name`\n\nin frontmatter, the first line is exactly `---`\n\nwith valid YAML under it, and you restarted the session. OpenCode and Codex both need a restart after changes.\n\n## Skill appears but never activates on its own\n\nThe description is not matching your phrasing. Name the skill explicitly for an immediate fix, or edit the `description`\n\nto include the phrases you actually use, then restart. The body has no effect on triggering.\n\n## Skill activates for the wrong tasks\n\nThe description is too broad. Narrow it: drop generic trigger words, add the specific contexts where it should fire, and state plainly what it should not cover.\n\n## Edited a skill and nothing changed\n\nYou are mid-session and the harness cached the old version at startup. Restart. This bites hardest in OpenCode and Codex, which cache aggressively.\n\n## Antigravity keeps prompting, or Gemini CLI went dead\n\nThe prompt is not a bug: Antigravity asks permission when a skill activates, same as Gemini CLI did. Approve and continue. A dead `gemini`\n\ncommand after June 18, 2026 is the deprecation, not a skills problem: consumer tiers moved to Antigravity CLI, and your SKILL.md files carry over unchanged once placed in `~/.gemini/config/skills/`\n\n.\n\n## Copilot's /skills list is empty\n\nCopilot is repo-scoped. Run the installer with `--project`\n\nfrom inside the repo so skills land in `.github/skills`\n\n. If the extension predates the January 2026 stable rollout, update VS Code and the Copilot extension, then check again.\n\n## A destructive git command ran without asking\n\n`git-hygiene`\n\nis instructions, not enforcement, and an agent can ignore it under pressure. For a hard guarantee, pair it with your harness's own permission or hook system so the dangerous commands are blocked at the tool layer, not just discouraged in prose.", "url": "https://wpnews.pro/news/senior-agent-skills-make-your-agent-act-as-a-senior", "canonical_source": "https://adityaarakeri.github.io/senior-agent-skills/#harness", "published_at": "2026-07-22 07:48:54+00:00", "updated_at": "2026-07-22 08:22:41.885038+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "ai-tools"], "entities": ["Aditya Arakeri", "Claude Code", "Codex CLI", "Google Antigravity", "OpenCode", "GitHub Copilot", "Cursor"], "alternates": {"html": "https://wpnews.pro/news/senior-agent-skills-make-your-agent-act-as-a-senior", "markdown": "https://wpnews.pro/news/senior-agent-skills-make-your-agent-act-as-a-senior.md", "text": "https://wpnews.pro/news/senior-agent-skills-make-your-agent-act-as-a-senior.txt", "jsonld": "https://wpnews.pro/news/senior-agent-skills-make-your-agent-act-as-a-senior.jsonld"}}