agent-skills

Agents are good at the work and inconsistent at the process. Each skill here is the written-down procedure for one job: numbered steps, each ending in a check the agent can actually verify.

📚 Skills Catalogue

Bucket	Job it covers	Skills
Agent lifecycle	Building AI agents, scope through production	7
Diagnosis	Something is wrong and you need to know why	6
Reliability (SRE)	Keep it running: incidents, SLOs, capacity, recovery	7
Security	Keep it safe: threats, auth, secrets, supply chain	5
Review	Judging code you or someone else wrote	4
Quality assurance	Proving it works before users find out	6
Building	Writing and changing code	7
Delivery (DevOps)	Ship it: CI, containers, infrastructure	4
Data	Query it, model it, migrate it, analyse it	4
Documentation	Explaining it to people	7
Reading and research	Getting information in and making sense of it	3

Agent lifecycle

Seven phases, each consuming the previous phase's artifact. Ordered but not one-way. Evaluation sends you back to design, and production traces send you back to scope.

Phase	Skill	Produces
1	agent-scoping	An agent spec: jobs, boundaries, success criteria
2	agent-design	Tool surface, context strategy, control flow, model choice
3	agent-implementation	The loop, tools, prompts, and readable traces
4	agent-evaluation	Eval set, graders, a baseline with variance
5	agent-hardening	Permissions and limits enforced in code, not in the prompt
6	agent-deployment	Staged rollout, tested rollback, designed fallback
7	agent-observability	Traces, quality metrics, failures fed back into evals

Diagnosis

Skill	Purpose
debugging	Locates the divergence point of a specific failure before any code changes
issue-investigation	Sharpens a murky systemic problem into an answerable question
issue-triage	Ranks a backlog on impact × frequency, and closes what will never be fixed
performance-profiling	Finds why something is slow by measuring, not by reading code for suspects
log-analysis	Gets an answer out of log volume by filtering and aggregating before reading
network-troubleshooting	Works up the stack (DNS, TCP, TLS) instead of guessing at a timeout

Reliability (SRE)

Skill	Purpose
incident-response	Runs a live outage: stabilise first, diagnose after
root-cause-analysis	Blameless postmortems that end every "why" at a changeable system
runbooks	Playbooks someone unfamiliar can follow at 3am
slo-definition	Targets derived from user tolerance, and error budgets that drive decisions
monitoring-setup	Four signals, bounded cardinality, alerts that justify waking someone
capacity-planning	Headroom set by failure cost and scaling lead time, with the cost stated
disaster-recovery	Backups you have actually restored, with a measured recovery time

Security

Skill	Purpose
threat-modeling	Design-time STRIDE walk, ranked by reachability, with accepted risks recorded
security-analysis	Source-to-sink tracing; no finding without a reachable attack path
auth-design	Object-level authorization, and revocation time as the deciding factor
secrets-management	Prefer no secret at all; revoke first when one leaks
dependency-audit	Vulnerabilities triaged for reachability, plus licences and abandonment

Review

Skill	Purpose
code-review	Findings ranked by severity, each with the concrete input that breaks it
code-analysis	Maps a codebase with depth concentrated on git-churn hotspots
code-linting	Linting for any stack, with 10 language references bundled
accessibility-review	Keyboard, screen reader, contrast, and focus: the barriers that block people

Quality assurance

Skill	Purpose
test-driven-development	Red-green-refactor in cycles small enough to stay honest
unit-testing	Tests for existing code that survive refactoring
integration-testing	Real database, real dependencies, where mocks turn out to have lied
browser-testing	E2E suites that stay fast and stop being flaky
load-testing	Finds the knee in the curve and which resource saturates first
test-data	Factories over fixtures, and realism that exposes encoding and date bugs

Building

Skill	Purpose
feature-implementation	Changes that match the codebase's existing idiom, in reviewable pieces
refactoring	Structure changes with behaviour held constant, never in the same commit
api-design	Interfaces designed from the caller's side, with errors and change planned in
error-handling	What to catch, what to retry, what to surface, and what to let crash
project-scaffolding	New projects with what they need and nothing they have not earned
code-templating	Templates from three real instances, with rot detection built in
dependency-upgrade	One dependency per commit, changelog read before the command is run

Delivery (DevOps)

Skill	Purpose
ci-pipelines	Fast, reproducible, and trustworthy enough that red means broken
containerization	Small, pinned, non-root images with layers ordered for caching
infrastructure-as-code	Read the plan, protect the state, guard what cannot be recreated
deployment-strategies	Blue-green, canary, flags, and the rollback that makes each safe

Data

Skill	Purpose
sql-queries	Joins that do not fan out, aggregates that do not double-count, indexed lookups
data-modeling	Schema that enforces correctness the application cannot violate
data-migration	Expand-then-contract, batched backfills, and a rollback you have run
data-analysis	Interrogates the data before trusting it, and reports caveats with the number

Documentation

Skill	Purpose
markdown-docs	Documentation organised around what the reader is trying to do
diagramming	Mermaid and C4 diagrams in version control that answer one question each
plain-language	Removes jargon without hollowing out precision
commit-messages	Why the change was made, in commits that revert independently
pr-descriptions	Points reviewers at the risk instead of restating the diff
api-documentation	Reference that answers the questions people actually arrive with
release-notes	Breaking changes first, written from the user's side

Reading and research

Skill	Purpose
feed-digest	Hacker News, RSS, blogs, podcasts, subreddits → five items or fewer
summarization	Condenses a document without softening its claims or dropping conditions
deep-research	Open questions answered with weighed sources and stated confidence

🚀 Quick start

git clone https://github.com/arjunprabhulal/agent-skills.git
cd agent-skills
./scripts/link-skills.sh

Skills load themselves when the work matches. You never name them.

You say	What loads	What changes
"the upload endpoint 500s sometimes and I can't reproduce it"	debugging	Works toward a reliable reproduction before touching code, instead of reading the stack trace and guessing
"does this look ok?"	code-review	Checks for files that should have changed but didn't, and ranks findings by severity rather than by file order
"we had a two-hour outage yesterday"	root-cause-analysis	Writes a blameless postmortem: impact in numbers, causes separated from contributing factors, actions with owners
"how much capacity do we need for the launch?"	capacity-planning	Starts from the measured ceiling and the scaling lead time, and names the resource that saturates first

To invoke one deliberately, name it: /debugging, or "use the debugging skill".

python3 scripts/check-skills.py
# ✓ 60 skills valid across 11 buckets

ls ~/.claude/skills | wc -l     # or ~/.agents/skills
# 60

Every entry is a symlink into your clone, so git pull updates all of them at once.

🧩 What a skill is

A directory containing a SKILL.md. YAML frontmatter declares when it applies, then the body gives the procedure to follow.

The description does the heavy lifting. It is the only part always in context, and it alone decides whether the skill loads. The body is the procedure, read only once the skill fires.

---
name: debugging
description: Finds the cause of a specific failing behaviour — a crash, a wrong value, a
  test that fails. Use this whenever something is broken and the cause is not yet known —
  the user says it "doesn't work", pastes a stack trace or error message, reports a failing
  test, or describes a bug, even if they just ask you to "fix" it without asking you to
  investigate. Jumping to a fix without this skill is the failure it prevents. For a failure
  whose cause is already known and needs a written post-mortem, use root-cause-analysis. For
  deciding which of many reported problems to work on first, use issue-triage.
license: MIT
---

# Debug

A bug is a gap between what you believe the system does and what it does. Debugging closes
the gap by finding the smallest place where belief and behaviour diverge. You are not
looking for a fix yet — you are looking for the **divergence point**.

The failure mode this skill exists to prevent: changing code before locating the divergence
point. A fix applied to a guessed cause either does nothing or hides the symptom, and both
outcomes cost more than the time you saved.

## 1. Make it happen on demand

Get a command that fails every time you run it. Write it down verbatim.

If it is intermittent, find what varies between runs — ordering, time, concurrency, a
leftover file, a network call, and pin it. An intermittent bug is a bug with a hidden input.

**Done when:** you can produce the failure at will, or you have written down exactly why you
cannot and what you are working from instead.

[... five more steps, then a section on what to try when stuck ...]

Notice how much of that file is the description. It names the phrasings a user would actually type, including "just fix it", and hands off to the sibling skill for the adjacent case.

Only the name and description of each installed skill sit in context permanently, at roughly 100 tokens apiece. The body loads when the skill matches; bundled references load only when the procedure reaches for them.

Because a skill is just a file, any harness that can read one can use these.

---

📥 Installation

The installer symlinks each skill into every agent skill directory it finds, so git pull updates everything you have installed without reinstalling.

./scripts/link-skills.sh

Detects and installs into ~/.claude/skills, ~/.agents/skills, and ~/.config/agents/skills, whichever already exist. Add --all to create them all first.

./scripts/link-skills.sh ~/.config/my-harness/skills
./scripts/link-skills.sh /path/to/project/.agents/skills

Anything that reads a directory of SKILL.md folders will work.

npx skills add arjunprabhulal/agent-skills

Resolves the repo straight from GitHub, lists all 60 skills, and links the ones you pick into whichever agent directories it finds. --skill '*' --agent '*' -y takes the whole set without prompting.

The repo ships .claude-plugin/plugin.json and marketplace.json, so it can be added as a plugin marketplace and installed and updated through that instead of symlinks.

claude plugin validate .    # verify the manifests

Skills are self-contained markdown. Open any SKILL.md, paste it into a system prompt, custom instructions, or a project rules file. You lose progressive disclosure, since bundled references stay on disk unread, but the procedure itself works standalone.

Preview before writing anything:

./scripts/link-skills.sh --dry-run

Existing non-symlink entries are never overwritten, and links pointing at renamed or deleted skills are reported as stale.

---

📁 Repository structure

agent-skills/
├── skills/<bucket>/<skill-name>/
│   ├── SKILL.md              instructions, loaded when the skill triggers
│   └── references/           loaded only when the procedure calls for them
├── evals/<skill-name>.json   test cases, three per skill
├── scripts/
│   ├── check-skills.py       validates naming, length, references, evals
│   └── link-skills.sh        symlink installer
├── .claude-plugin/           plugin and marketplace manifests
└── AGENTS.md                 conventions for agents maintaining this repo

Buckets group by what the user is trying to do, not by technology. Skill names are globally unique because installed skills share one flat directory.

✍️ Authoring standards

Every skill conforms to the published authoring guidance:

Standard	Rationale
Noun-phrase names, domain first	Matches the reference collection; keeps naming predictable
Third-person descriptions naming trigger situations	Under-triggering is the dominant failure mode
SKILL.md under 500 lines	It occupies the context window whenever the skill fires
References exactly one level deep	Nested references get partially read
Every step ends in a checkable completion criterion	Prevents premature completion
Explain why a rule exists	A rule that is understood survives paraphrase

Validate any change:

python3 scripts/check-skills.py

It checks frontmatter validity, naming rules, body length, whether every referenced file exists, whether any two skills share a name, and whether eval cases are present. CI runs the same command on every pull request.

🧪 Testing

Every skill ships with test cases in evals/, three per skill: the obvious trigger, a casual phrasing that makes the description earn the match, and a case where the skill's discipline is inconvenient to follow.

python3 scripts/check-skills.py

The same command runs in CI on every pull request.

🗺️ Roadmap

• 60 skills across eleven buckets
• Validation tooling and continuous integration
• Plugin packaging
• Test cases for every skill
• Execute the eval suite against a no-skill baseline
• npx installer for one-command setup
• Chaos engineering, vulnerability response, and estimation skills

📖 Documentation

Guide	Covers
Architecture	Why buckets group by job, the three loading levels, where new material goes
Authoring skills	Writing a description that triggers, checkable completion criteria
Installation	Per-harness setup, what the installer does, troubleshooting
Evals	Case format, and the difference between trigger and behaviour evaluation
FAQ	Context cost, harness support, why sixty skills rather than one

🤝 Contributing

Contributions are welcome. See the contributing guidelines to get started, and the code of conduct for how discussions run here.

The most valuable contribution is a skill you have used on real work, or a report of one that behaved badly. A transcript of what you asked and what the agent did is worth more than a bug description.

💬 Support

Security issues go through SECURITY.md, privately. Everything else — questions, proposals, and bug reports — belongs in GitHub issues. Templates are provided for proposing a new skill and for reporting one that misbehaved.

🙏 Acknowledgements

The SKILL.md format follows the Agent Skills specification published by Anthropic. The authoring standards here (trigger-oriented descriptions, progressive disclosure through reference files, and completion criteria on every step) draw on their published guidance and on the reference skill collection at anthropics/skills, whose skill-creator validator is used to check every skill in this repository.

⚖️ License

This repository is licensed under the MIT License.