Best Agent Skills for Claude Code and Codex: What to Install, How to Audit, Why Skills Don't Trigger

Name

Soren Atelier

Updated on 11/15/2026

The short version: install a few skills, not a whole repository. Three rules:

1. Pick by job. Start with one small, text-only pack such as obra/superpowers (15 skills) or a single skill such as Jane Street's socratic-tutor. Leave catalogs like google/skills (203 skills) and NVIDIA/skills (452) alone until you need one specific skill from them.
2. Read before you install. A skill is instructions plus optional scripts that run with your agent's permissions. The audit script below lists which skills ship code and which files to open first. It only reads files.
3. Check the listing after you install. Claude Code shows the model a list of skill names and descriptions, and caps that list. On a machine that already had 98 skills, a newly installed skill was listed by name only, so the model had no description to match a request against. Run /skill-doctor, then free the budget with skillOverrides or raise it with skillListingBudgetFraction.

What was tested: every number here comes from shallow clones made on November 15, 2026 and from Claude Code 2.1.325 on macOS. The audit script, claude plugin validate, /skill-doctor and the debug log were all run. Whether the model then picks a skill on its own was not tested, and neither were SkillSpector, the npx skills installer or Codex. The table near the end separates the two.

Ten skill repos compared

Agent skills are folders with a SKILL.md file that Claude Code, Codex and other agents load on demand. If you need the format itself, Codex vs Claude Code Skills covers paths, frontmatter and sharing one skill across both tools. This page is about choosing and installing other people's.

Interest in skill repos jumped in early November. Jane Street published a single-skill repository on November 3 and it reached 712 points on Hacker News. GoogleChrome/modern-web-guidance shipped 1.0.0 on November 10. anthropics/skills gained about 6,200 stars in a week.

The table counts every SKILL.md in each repository. "Description chars" is the total length of the description text, which is what an agent loads for every skill on every turn. The last column compares that with the 30,000-character listing budget Claude Code reported on the test machine.

Three things stand out.

• Size varies by two orders of magnitude. Installing all of google/skills or NVIDIA/skills overflows the listing several times over. Both READMEs let you install single skills: NVIDIA with --skill, Google through the installer's prompt.
• Most skills are plain Markdown. 552 of the 782 skills ship no code at all. The ones that do are concentrated in document, media and cloud skills, where a script does the deterministic part.
• Pre-approved tools are rare outside one catalog. 126 skills in NVIDIA/skills and 2 in google/skills declare allowed-tools. None of the other eight repositories do.

Which one for which job

• obra/superpowers is a complete working method: brainstorm, write a plan, execute it, debug systematically, verify before claiming done. It is the cheapest large pack in context terms.
• addyosmani/agent-skills is closer to a set of engineering checklists: code review, API design, CI, observability, security hardening. Its descriptions are longer, so 25 skills cost about four times what Superpowers does.
• mattpocock/skills leans on short commands you call yourself (/grill-me, /tdd, /to-spec). It includes eight in-progress skills.
• anthropics/skills is the reference set. Data people usually want its xlsx, pdf, docx and pptx skills, which ship the scripts that actually build the files. If your analysis lives in notebooks, an agent that works inside Jupyter such as RunCell (opens in a new tab) covers the part these file skills do not.
• GoogleChrome/modern-web-guidance is two skills backed by a CLI that searches a guide index, aimed at keeping agents off outdated front-end patterns.
• kajisho5/ffmpeg-skill is one large skill with 107 code files, mirrored in two places, plus 14 of the author's own project skills under .claude/skills. Install it with its installer, not by copying the repository.

Step 1: Audit a skill repo before you install it

A skill's instructions enter your agent's context, and its scripts run with whatever permissions your session has. Reading the repository first is the whole defence, so make the reading fast.

This script walks a folder, finds every SKILL.md, and prints which skills ship code and which contain patterns worth a look. It uses only the Python standard library and never runs anything from the folder it scans.

#!/usr/bin/env python3
"""Read-only audit of SKILL.md folders. Runs nothing from the repo it scans."""
import os, re, sys
 
RISKY = {
    "pipe-to-shell": r"(curl|wget)[^\n|]*\|\s*(sudo\s+)?(ba|z)?sh",
    "reads-secrets": r"\.ssh/|\.aws/credentials|\.env\b|id_rsa|\.netrc|keychain",
    "sudo": r"\bsudo\s",
    "rm-rf": r"\brm\s+-[a-zA-Z]*r[a-zA-Z]*f|\brm\s+-[a-zA-Z]*f[a-zA-Z]*r",
    "skip-permissions": r"dangerously-skip-permissions|bypassPermissions|--yolo",
    "hidden-unicode": r"[\u200b\u200c\u200d\u2060\u202a-\u202e\U000e0000-\U000e007f]",
}
CODE = (".py", ".sh", ".js", ".mjs", ".ts", ".rb", ".ps1")
 
def frontmatter(text):
    m = re.match(r"^---\n(.*?)\n---\n?", text, re.S)
    if not m:
        return None, text
    fields, key = {}, None
    for line in m.group(1).splitlines():
        k = re.match(r"^([A-Za-z_-]+):\s*(.*)$", line)
        if k:
            key = k.group(1)
            fields[key] = k.group(2).strip().strip("\"'")
        elif key and line.startswith((" ", "\t")):
            fields[key] += " " + line.strip()
    return fields, text[m.end():]
 
def audit(root):
    rows = []
    for folder, dirs, files in os.walk(root):
        dirs[:] = [d for d in dirs if d not in (".git", "node_modules")]
        if "SKILL.md" not in files:
            continue
        text = open(os.path.join(folder, "SKILL.md"), encoding="utf-8", errors="replace").read()
        fields, body = frontmatter(text)
        everything, code_files = text, 0
        for sub, _, names in os.walk(folder):
            for n in names:
                if n.endswith(CODE):
                    code_files += 1
                if n.endswith(CODE + (".md",)) and n != "SKILL.md":
                    try:
                        everything += open(os.path.join(sub, n), encoding="utf-8", errors="replace").read()
                    except OSError:
                        pass
        flags = [name for name, pat in RISKY.items() if re.search(pat, everything)]
        if fields is None:
            flags.append("no-frontmatter")
            fields = {}
        if fields.get("allowed-tools"):
            flags.append("allowed-tools")
        if "hooks" in fields:
            flags.append("hooks")
        if re.search(r"!`[^`]+`|```!", body):
            flags.append("shell-injection-block")
        desc = (fields.get("description", "") + " " + fields.get("when_to_use", "")).strip()
        rows.append((os.path.relpath(folder, root), len(desc), len(body), code_files, flags))
    return rows
 
if __name__ == "__main__":
    rows = audit(sys.argv[1])
    listing = sum(d for _, d, _, _, _ in rows)
    print(f"{len(rows)} skills, {listing:,} description chars (~{listing // 4:,} tokens if all are listed)")
    print(f"{sum(1 for r in rows if r[3])} skills ship code files, {sum(r[3] for r in rows)} code files in total")
    for path, desc, body, code, flags in sorted(rows, key=lambda r: (-len(r[4]), r[0])):
        if flags or "-v" in sys.argv:
            print(f"  {path}: desc={desc} body={body} code={code} flags={','.join(flags) or '-'}")

Clone the repository somewhere outside your project, then point the script at it.

git clone --depth 1 https://github.com/obra/superpowers /tmp/superpowers
python3 audit_skills.py /tmp/superpowers

The output for Superpowers on November 15:

15 skills, 2,317 description chars (~579 tokens if all are listed)
3 skills ship code files, 6 code files in total
  skills/brainstorming: desc=213 body=14933 code=3 flags=rm-rf
  skills/subagent-driven-development: desc=85 body=19484 code=0 flags=rm-rf
  skills/systematic-debugging: desc=91 body=9366 code=2 flags=reads-secrets

How to read the flags

A flag means "open this file", not "this skill is malicious". Every flag checked by hand in these ten repositories was benign. The rm-rf hit in Superpowers is rm -rf "$SESSION_DIR" in a script that cleans up its own temp folder. The hidden-unicode hit in ffmpeg-skill is a zero-width joiner inside a note about Hindi ligatures. reads-secrets fires on any mention of .env, including advice not to commit one.

The last three matter most in Claude Code. allowed-tools grants tools without asking for the turn that invokes the skill. A hooks entry keeps running for the rest of the session. A !`command` block executes when the skill is loaded.

Two more checks

Claude Code can validate the frontmatter for you. This ran clean on a folder of 91 installed skills, and on a repository that is not packaged as a plugin it fails with No manifest found, which tells you the repository is copy-only.

claude plugin validate .claude/skills

For a deeper scan, NVIDIA's SkillSpector (opens in a new tab) is a dedicated scanner with 71 patterns and a 0-100 risk score. Its README gives this as the quick path; it was not run for this article.

uv tool install git+https://github.com/NVIDIA/skillspector.git
skillspector scan ./my-skill/ --no-llm

Step 2: Install only what you need

Copying one folder is the install method with the fewest moving parts, and it is the one tested here.

git clone --depth 1 https://github.com/janestreet/agent_skills /tmp/agent_skills
mkdir -p .claude/skills
cp -R /tmp/agent_skills/socratic-tutor .claude/skills/

The destination decides where the skill loads.

Prefer the project folder for anything you are trying out. It keeps the skill out of your other sessions, and deleting the folder removes it.

The other two routes come from each project's README and were not run here.

• Plugins install a whole pack and are updated from /plugin. For example, /plugin marketplace add anthropics/skills, then /plugin install document-skills@anthropic-agent-skills. Superpowers is /plugin install superpowers@claude-plugins-official.
• The skills CLI from Vercel Labs copies files into the project for many agents at once: npx skills add addyosmani/agent-skills --skill test-driven-development -a claude-code. Add --list to browse first.

One caveat from the Claude Code docs: skillOverrides does not apply to plugin skills. If a plugin pack is too large, you disable the plugin, not individual skills.

Step 3: Check that the new skill is actually listed

This step catches a cause of "installed but never triggers" that produces no error.

Claude Code gives the model a listing of every skill's name and description. The listing has a budget, 1% of the context window by default. When it overflows, Claude Code keeps every name but drops descriptions, starting with the skills you use least. A freshly installed skill has zero uses. The Claude Code docs describe the mechanism under Skill descriptions are cut short (opens in a new tab); the numbers below show what it looks like in practice.

Here is what that looked like on a machine that already had 84 personal skills and 14 plugin skills. After copying in one new skill, the debug log said:

[WARN] Skill listing over budget: 112 skills, 37491 chars > 30000 budget — descriptions will be truncated.

And /skill-doctor showed the new skill listed by name only:

A cost of < 20 is not proof on its own, because a skill with a one-line description also costs under 20. Compare it with the description length. The counts below only include skills whose descriptions are long enough to tell.

Adding more made it worse for everything else. With 91 project skills installed, 76 were listed and 70 of them had lost a description of 80 characters or more. With 289, the number of personal skills that had lost their descriptions rose from 6 to 39: the new arrivals pushed out descriptions of skills that had been working.

Run the check

/skill-doctor prints one row per skill with its listing cost. It needs Claude Code 2.1.252 or later and works in -p mode.

claude -p "/skill-doctor"

To see the budget warning itself, write a debug log and search it.

claude --debug-file /tmp/cc-debug.log -p "hello"
grep "Skill listing over budget" /tmp/cc-debug.log

Fix it

Turn off what you do not use first. This goes in .claude/settings.json for the project, or ~/.claude/settings.json for every project.

{
  "skillOverrides": {
    "legacy-context": "name-only",
    "deploy": "off"
  }
}

"name-only" keeps a skill callable as /name while removing its description from the listing. "off" hides it completely. In an interactive session, /skills writes the same setting: press Space on a row to cycle its state, then Esc to save.

If you really do use everything, raise the budget instead. It costs context on every turn.

{
  "skillListingBudgetFraction": 0.02
}

Codex has the same mechanism with different numbers. Its docs say the initial skills list uses at most 2% of the context window, or 8,000 characters when the window is unknown, shortens descriptions first, and may omit skills from the list with a warning. skills.max_context_tokens changes the budget, and a [[skills.config]] entry with enabled = false in ~/.codex/config.toml disables one skill.

Step 4: Let a skill run unattended

Claude Code 2.1.325, released on November 13, changed one behavior that affects scheduled work. Scheduled tasks and /loop now ask before running a skill that declares allowed-tools or hooks. To run such a skill without a prompt, allow it by name.

{
  "permissions": {
    "allow": ["Skill(release-notes)"]
  }
}

The reverse also works. A deny rule such as Skill(deploy *) stops the model from invoking a skill, and denying Skill with no argument turns all of them off. Both come from the Claude Code docs. Claude Code Permissions Hardening covers the rest of the permission settings worth committing to a repository.

Step 5: Remove a skill

• Copied skill: delete its folder under .claude/skills/ or .agents/skills/.
• Plugin skill: /plugin uninstall <plugin>@<marketplace>, or disable it in /plugin.
• Keep it but stop auto-use: set it to "name-only" or "off" in skillOverrides, or add disable-model-invocation: true to its frontmatter if you own the file.

Tested vs documented

The 30,000-character budget is what one machine reported. Yours depends on the model's context window, so read your own debug log before relying on the percentage column.

FAQ

Which agent skills should I install first in Claude Code?

Start small. obra/superpowers gives a full plan, test, debug and review workflow in 15 skills. addyosmani/agent-skills adds 25 engineering checklists. For spreadsheets, PDFs and slides, install the document-skills plugin from anthropics/skills. Install single skills from large catalogs instead of the whole thing.

Why does my new Claude Code skill not trigger?

On a machine with many skills, the listing is probably over budget and the new skill is listed by name only. Run /skill-doctor. A context cost under 20 on a skill with a long description means the description was dropped. Turn unused skills off with skillOverrides, or raise skillListingBudgetFraction.

How do I check whether a skill is safe before installing it?

Clone it outside your project and read it. Look for bundled scripts, allowed-tools, hooks, and !`command` blocks. The audit script above lists them for every SKILL.md without running anything.

How many skills are too many for Claude Code?

It depends on description length, not the count. Twenty skills from anthropics/skills use about 9,500 characters of a 30,000-character budget. google/skills in full needs about 107,600.

What does /skill-doctor do?

It prints every loaded skill with its source, listing cost, 7-day token use and invocation count, and flags the ones never used. It needs Claude Code 2.1.252 or later.

Where do I put a skill so both Claude Code and Codex can use it?

.claude/skills/ for Claude Code and .agents/skills/ for Codex, in the project or in your home directory. Keep one copy and symlink the other.

Can I disable a skill without deleting it?

Yes: skillOverrides in Claude Code settings, or [[skills.config]] with enabled = false in Codex. Plugin skills are managed through /plugin.

Why does a scheduled task ask before running my skill in Claude Code 2.1.325?

Scheduled tasks and /loop now ask before running a skill that declares allowed-tools or hooks. Add Skill(name) to permissions.allow.

Sources

• Extend Claude with skills (opens in a new tab) and the settings reference (opens in a new tab), Claude Code docs
• Claude Code changelog (opens in a new tab), version 2.1.325
• Build skills (opens in a new tab), Codex docs
• Agent Skills specification (opens in a new tab)
• vercel-labs/skills (opens in a new tab) and NVIDIA/SkillSpector (opens in a new tab) READMEs
• Socratic Tutor on Hacker News (opens in a new tab)

Related Guides

• Codex vs Claude Code Skills: Setup, Settings, and How to Share Skills Across Both
• Claude Code Permissions Hardening: Block Writes Outside Your Repo, Deny Instead of Prompt, and Audit settings.local.json
• Claude Code Mods Tutorial: Build and Test Your First Mod
• Claude Code Reads AGENTS.md Now: Setup and Loading Modes
• Oh My OpenCode and OpenCode: Install, Setup, and Fixes