skills

Do I know anyone working on the Vercel skills CLI? @vercel I would love to chat about a programmatic install API. Frameworks like Nuxt, or people selling their skills, could build on top of it instead of spawning `npx skills add`. skills#178

skills#278 (by someone else) quite ridiculous—just skim its first two comments, absurd amounts of unnecessary detail and a preposterous solution, all very obviously slop. All that needed to be said was “cloning repositories can take arbitrarily long, so putting a 60 second timeout is obviously wrong”. The rest is worse than posturing. Rather like the issue, this article is written in a tedious style which sure looks sloppy, and I disagree with parts of its conclusions. > The thing is, timeouts need to exist. Infinite waits are bad. Hanging processes are bad. I’m not arguing against timeouts. Since the author won’t, I will. The skills case shouldn’t have a timeout at all: it’s the wrong place and the wrong thing. You rather want to check if it’s still working, and Git has that handled. The problematic case is if it can get stalled waiting for authentication, and I’m not convinced that can happen in a way that needs to be catered for. If it’s interactive, the user will observe the authentication prompt and so the timeout cutting them off is wrong, and if it’s not interactive then it should fail immediately. I’m inclined to presume it’s slop-style cargo-culting (in which area Chesterton’s fence is an increasingly unreliable rubric). As for the Docker Gordon case, well, for a human tool I’d just say there shouldn’t be any timeout, it’s obviously dumb, the human will observe if things aren’t working as expected and interrupt it. For AI nonsense, well, this sounds to me like the wrong way to apply a timeout. I would rather expect it to throw an LLM at it and its logs or something to apply judgement like the human would, to see if it seems like it’s not working or stuck and interrupt it. A hard timeout is obviously idiotic, but a timeout at all feels from the wrong era of computing for such a thing.

How to make link to SaaS Launch Video system A screenshot can show what you built. A screen recording can show how it works. But making a short, polished launch video usually means opening another set of tools—and spending time editing instead of sharing. /brag is an open-source agent skill designed to help with that last step. Point an agent at a project, and it can inspect the code, plan a short video, and prepare the output for sharing. Watch the examples and see the project What is /brag? /brag reads a project’s source code to understand what the product does, what it looks like, and which details are worth showing. It then creates a video plan and hands a focused composition brief to Hyperframes, which handles the composition and rendering workflow. The output includes the rendered video, a poster image, and a share caption—along with the plan and composition files. From project code to video The classic /brag workflow has four steps: 1. Inspect the project. Read relevant files to identify the product, audience, visual identity, and user flow. 2. Plan the story. Choose a creative angle, write a hook, and lay out the video scene by scene. 3. Build the composition. Give Hyperframes the brief, including the visual direction and storyboard. 4. Validate and deliver. Check the composition, render the video, select a poster frame, and write share copy. The story usually follows a simple shape: Hook → product reveal → highlights → close !Image description That shape is a guide, not a rigid template. The video is meant to show the actual product—not just string together generic marketing claims. A typical output folder looks like this: brag-output/ brag-plan.md composition-brief.md brag.mp4 brag.jpg share-copy.txt composition/ The plan and brief document the creative direction, while the video, poster, and caption are the pieces ready to share. What makes a good brag video? The project’s instructions set a few useful creative constraints: - Keep it short: usually 15–25 seconds. - Make the hook count: the opening seconds should give people a reason to keep watching. - Show the product: include real UI, copy, or other recognizable project details. - Keep text readable: use motion and cuts to create pace, not text that disappears before it can be read. - Stay specific: avoid claims and phrases that could describe any product. - Make it shareable: choose a strong poster frame and write a caption that works outside the video. The workflow also includes a validation step before rendering. In the classic path, Hyperframes’ check helps catch issues such as text overflow and contrast problems. Two workflows: /brag and /brag-slim The repository includes two approaches: - /brag uses Hyperframes to build and render the composition. - /brag-slim is a lean, single-file workflow. The agent builds the video with tools already available on the machine, without Hyperframes or bundled assets. On Claude Opus 5.5, /brag switches to /brag-slim by default. Use /brag --full to request the classic Hyperframes workflow instead. Try it Install the skill with the skills CLI: npx skills add latent-spaces/brag --skill brag MASHRAF AIMAN CTO and Co-founder Ennovat Studio

每个 agent 工具装技能都要各翻各的文档？ Vercel 开源的 skills CLI：一条 npx skills 命令，就能给 70+ 工具装技能。 适合多工具混用 agent 的人，先装一个常用的技能。 先给哪个工具装，Claude Code 还是 Codex？ #Agent #CLI @grok vercel-labs/skills

Free, keyless Agent Skills for search, scraping, papers and YouTube: take them Wikimedia answers requests that carry an empty or generic User-Agent with HTTP 403. So when an agent's fetch tool sends one, "summarise this Wikipedia article" ends right there: $ curl -s -o /dev/null -w "%{http_code}\n" -A "" https://en.wikipedia.org/api/rest_v1/page/summary/Ada_Lovelace 403 Claude Code's tracker has bug reports about its fetch tool getting 403 on Wikipedia and npm, both closed as "not planned". Paid search and scraping APIs with keys exist for exactly this kind of gap. For Telegram, the libraries need an account and API credentials. The cheapest workaround is the agent writing its own curl with a header, or a line about it in AGENTS.md. That fixes the header. It doesn't give the agent tested parsing, rate limits that hold across runs, or a reliable way to say "this site blocked me, stop", and the next session re-derives the rest of the API from memory. I wanted that part written once and tested, so I started zedxter/utility-belt: an open-source, MIT-licensed collection of Agent Skills that needs no API keys. A skill is a folder with instructions and scripts; the agent reads its one-line description at startup and loads the rest only when a task matches. TL;DR: 20 skills, each a SKILL.md plus a Python script that uv run starts with no setup. Any agent that reads the SKILL.md format and can run shell commands with network access can use them, and they're yours to take and change. Install with the skills CLI: npx skills add zedxter/utility-belt. {% embed zedxter/utility-belt %} What's in it The web, without paid scraping APIs - web-search: DuckDuckGo, Bing, Brave and others through the unofficial ddgs library (best effort; your own SearXNG is the stable option). --read 3 also fetches the top results. - web-extract: a page or PDF as clean Markdown, with a Wayback Machine fallback when the page is gone or blocked. - web-crawl, web-scrape, web-browse: a whole docs site into one file, repeated records into CSV, and a real Chromium you drive step by step. - wayback: what a URL said on a given date, every capture in a period, and Save Page Now. Video and audio - youtube-search, youtube-transcript and youtube-audio cover search, captions and saving the audio. - transcribe-audio: local faster-whisper for videos without captions, voice memos and podcast episodes. - podcast-search: Apple's public search API plus the show's own RSS feed. Reading sources properly - scholar-search: arXiv, Crossref, Europe PMC, PubMed and bioRxiv, merged into one record per paper. - cite-check: checks a reference list or a .bib against doi.org, Crossref, arXiv and PubMed. - wiki-lookup: Wikipedia in any language plus Wikidata, with revision ids for citing. - hackernews, telegram-channel: HN search and comment trees; public Telegram channels without an account. Making things - human-writing: drafts and reviews prose; every claim has to trace to a source, and a linter flags machine-sounding patterns before you publish. - pdf-typeset: Markdown or JSON to a checked PDF through Typst. - anki-deck: Anki decks you can rebuild without duplicating cards. There's also weather: forecast, past weather back to 1940, and air quality, from Open-Meteo. Three rules every skill follows A plain script with its dependencies inline. Each script declares what it needs in a PEP 723 header, so uv run installs it on first use. Six of the skills use only the standard library. There's no server to run and nothing to configure for Docker or MCP. The trade-off: dependencies are version ranges, not a lock file, so the agent installs current releases without anyone reviewing them. For the yt-dlp skills that's deliberate: YouTube changes often, and old yt-dlp releases stop working (uv run --refresh picks up a new one). If you'd rather pin, uv lock --script locks a script. transcribe-audio is the one skill that downloads a large file on its own (Whisper models, 78 MB and up), and it asks first. An exit code the agent can act on. Every script prints one error: line with a hint, and in the search and lookup skills the common codes mean the same thing: 1 is "nothing found", 2 is bad input, 4 is "blocked or rate-limited, stop", 6 is a network error worth one retry later, 7 is an unexpected failure. An unhandled error exits 7, not 1, so an agent can't mistake a bug for an empty result; a CI check makes sure every script catches it. Other codes are skill-specific (in pdf-typeset, 1 means the PDF was written but its checks found problems); each SKILL.md has its table. Nothing agent-specific in a skill's instructions. No agent product names, no agent tool names like WebFetch, no install paths in SKILL.md. (The one exception is in code: a few web scripts look for the web-extract skill in each agent's skills folder.) Claude Code, Codex, Cursor, Gemini CLI and OpenCode read the same format; the installer copies the folders into each agent's skills directory. A CI check greps every skill for violations. Rate limits and licences Every script that calls a public API directly sends User-Agent: utility-belt-<skill>/1.0 (+https://github.com/zedxter/utility-belt) and keeps to the source's published limits. arXiv gets at most one request every three seconds, NCBI three a second, and HN Search stays under its 10,000 requests an hour. Only scholar-search's arXiv spacing holds across parallel runs on the same machine; the other limits are kept within one run. For Wikipedia, wiki-lookup sends that User-Agent and makes one request at a time, which is the fix for the 403: $ uv run scripts/wiki.py summary "Ada Lovelace" # Ada Lovelace English mathematician (1815–1852) Augusta Ada King, Countess of Lovelace, also known as Ada Lovelace, was an English mathematician and writer chiefly known for work on Charles Babbage's proposed mechanical general-purpose computer, the analytical engine. ... (Text from Wikipedia, CC BY-SA 4.0. Commands like this one run from the skill's folder, for example ~/.claude/skills/wiki-lookup/ after installing for Claude Code.) The web skills are a different case. Ordinary sites don't publish an API, and some turn away non-browser clients by their TLS handshake, so web-extract impersonates a browser's handshake to get past that filter. It sends its own User-Agent, stops at CAPTCHAs and bot challenges with exit 4, and is meant for pages you could open in your own browser. web-crawl honours robots.txt. Some access is unofficial, and that's your call to make: youtube-audio and youtube-transcript go through yt-dlp and an unofficial captions library, and web-search reads search engines' result pages. Your own SearXNG and the official APIs are the options that stay within the platforms' terms. Everything these skills fetch also lands in the agent's context, so the web, wayback, Telegram, HN and Wikipedia skills tell the agent to treat that content as data and never follow instructions in it. For web-browse, a profile without your real logins is the safer default. Licences are part of the rules too. Open-Meteo's free tier is non-commercial, so weather says so and credits the data. Dependencies can't be GPL or AGPL, a policy that keeps the default install clean for anyone who vendors or redistributes the skills. That cost real work once, because yt-dlp[default] pulls in mutagen, which is GPL, only to embed cover art. youtube-audio now embeds covers with ffmpeg instead. Review and tests The ten skills added most recently each went through at least two independent reviews before merging, usually one on the code and one on the spec and the docs. Every pull request's reviews found real bugs. A few: - The first version of cite-check marked fabricated references as verified: a real DOI with an invented title, invented co-authors, Nature Communications cited as Nature. It now compares title words, the first author and the venue strictly (abbreviated journal names still match), and every one of those cases is a regression test. When in doubt it says MISMATCH rather than VERIFIED, at the cost of some false alarms on preprints and renamed venues. - In anki-deck, an image reference like  packed that file into the deck. Media now has to be an image, audio or video file inside the input's own folder (or a folder given with --media). - weather -33.87,151.21 failed: the argument parser read the minus sign as an option, which broke the whole southern hemisphere. - hackernews decoded HTML entities twice, so &amp;region=us in a link came out as ®ion=us. Here is cite-check given a real DOI pasted under the wrong paper: $ uv run scripts/cite_check.py --doi 10.1038/nature14539 \ --title "Attention is all you need" --author "Vaswani, Ashish" --year 2017 MISMATCH ref1 cited: Attention is all you need found: Deep learning Lecun et al. · Nature · 2015 https://doi.org/10.1038/nature14539 differs: doi: cited 10.1038/nature14539 · found 10.1038/nature14539 (resolves to a different work) differs: title: cited Attention is all you need · found Deep learning ... The DOI exists, but it belongs to LeCun's "Deep learning", so the reference is flagged instead of passing. Then the tests: 569 test functions across 20 suites, run in CI on every pull request. The offline tests for youtube-search and youtube-transcript cover only input parsing and error handling, and the live check can't tell their breakage from a block, so a real regression in fetching would show up as "blocked". They are offline on purpose, against local HTTP servers and canned API answers. The real sources get a separate check: a weekly workflow runs a live command for 15 of the skills and keeps a single GitHub issue open while something is broken. Exits 4 and 6 go in their own section, "blocked or unreachable from the runner", because YouTube often bot-checks GitHub's runners for transcripts and downloads. That points at a real limit. The video and scraping skills assume a home or office connection. From cloud agents and other datacenter IPs, YouTube and some sites block them much of the time, and the scripts say so with exit 4. The description is a routing rule An agent decides whether to open a skill from its description alone, so that line gets tested like code. Each of the ten newest skills has trigger evals: about a dozen prompts that must load it or are near misses that must not, run once each on Claude Code and on Codex. scholar-search is the clearest example. The first description listed what the skill searches. With it, Claude answered "What are the most cited papers on graph neural networks?" from memory, with citation counts it hadn't checked, and called Unpaywall directly when asked for a free full-text PDF of a DOI. After the description was changed to lead with "Use whenever an answer should name real scholarly papers instead of recalling them from memory", both prompts loaded the skill and the near misses still didn't: 12 of 12, from 10. One run per prompt on the same twelve prompts that showed the problem is a small, non-held-out sample: it shows those two failures fixed, not routing improved in general. Codex scored 11 of 12 both times. Its miss was a near miss: asked to check the references in a refs.bib, it opened scholar-search, read that the task belongs to cite-check, and went looking for that skill. Try it npx skills add zedxter/utility-belt # pick skills and agents interactively npx skills add zedxter/utility-belt --all -a claude-code # everything, for one agent Each installed skill adds its description to every session, so picking the ones you need beats installing all twenty. Most scripts need nothing but uv. youtube-audio also needs ffmpeg, web-browse needs Playwright's Chromium, and web-crawl and web-scrape need web-extract installed next to them. Each skill's compatibility field lists what it needs. Then ask your agent for something it used to fail at: the transcript of a YouTube talk, the HN thread about a library you're evaluating, whether the references in a draft exist, last July's weather in a city you're moving to. Contribute The twenty skills cover the failures written up in the repo's issues. Yours are probably different. CONTRIBUTING.md has the checklist: a description written as a routing rule, the shared exit codes, no GPL imports, a User-Agent and the source's limits. From a clone of the repo, one command checks most of it: git clone https://github.com/zedxter/utility-belt && cd utility-belt python3 test/ops.py validate # spec, frontmatter, size, agent neutrality, licences python3 test/ops.py test <skill> # your skill's offline tests with exactly CI's dependencies python3 test/ops.py probe <skill> # your skill against its real source Take it All of it is open source under MIT: take the skills, use them in your own setup, fork them, change them. The repository is zedxter/utility-belt. Suggestions of any kind are welcome. If there's a free API your agent keeps fumbling, open an issue with the endpoint and what goes wrong; that's how many of these started. And if the collection saves you a few failed fetches, a star on the repo makes my day.

How to Create Claude Code Skills That Actually Trigger (SKILL.md Guide) To create a Claude Code skill, make a folder named after the skill inside .claude/skills/ (for one repository) or ~/.claude/skills/ (for every project on your machine), put a SKILL.md file in it with YAML frontmatter and Markdown instructions, and write a description that says what the skill does and when to use it. Claude reads only that description when deciding whether to load the skill, so most "my skill never triggers" problems are description problems. This guide covers deciding whether something should be a skill, the file layout, the frontmatter rules, a description formula that triggers on real requests, keeping the body small, and testing triggering the way you would test code. Everything here also applies to other coding agents that read the Agent Skills format, such as Codex, Cursor, Gemini CLI, and OpenCode. !How a Claude Code skill loads in three tiers: metadata, instructions, resources How Claude Code loads a skill A skill is a directory with a SKILL.md file (YAML frontmatter plus a Markdown body) and optional scripts/, references/, and assets/ folders. Coding agents load it in three tiers: | Tier | What loads | When | Budget | |---|---|---|---| | 1. Metadata | name and description of every installed skill | Session start, always | About 100 tokens per skill | | 2. Instructions | The full SKILL.md body | When the description matches the task | Under 5,000 tokens and 500 lines | | 3. Resources | Files in references/, scripts/, assets/ | Only when the body tells the agent to open them | As needed | Three rules follow from this table, and the rest of the guide builds on them: 1. The description alone decides whether the skill triggers. The body is invisible until then. 2. Every installed skill costs tier-1 tokens in every session. Ten unused skills cost roughly 1,000 tokens of metadata per session and compete with the skills you do want. 3. Everything in the body is paid for on every activation, so detail that only some tasks need belongs in references/. Step 1: Decide whether it should be a skill A skill earns its place when the agent would get a task wrong, slow, or inconsistent without it. Good candidates: - Project conventions the model cannot infer: this repo's migration tool, its test layout, its release steps. - Internal APIs, schemas, runbooks, and incident procedures. - Fragile sequences that must run exactly, such as a deploy or a data backfill. - Corrections you keep typing into chats. Every correction you have made to an agent is a candidate gotcha. Poor candidates are general knowledge ("how to write good Python"), one-off tasks, and anything a linter or formatter already enforces. Those belong in a linter config, a repo CLAUDE.md or AGENTS.md, or nowhere. Scope a skill like a function: one coherent unit of work. Too narrow and several skills load for one task with conflicting instructions. Too broad and the description cannot trigger precisely. Build skills from real material, not from a prompt that says "write a skill about X." The steps that worked on a real task, review comments, runbooks, and postmortem fixes produce instructions the model does not already know. A generated skill about a general topic mostly restates what the model knows already. Step 2: Create the folder in the right place Claude Code reads skills from these locations, according to the Claude Code skills documentation: | Location | Path | Loads in | |---|---|---| | Personal | ~/.claude/skills/<skill-name>/SKILL.md | All your projects on this machine | | Project | .claude/skills/<skill-name>/SKILL.md | Sessions in this repository; commit it so your team gets it | | Nested | <subdir>/.claude/skills/<skill-name>/SKILL.md | Sessions started in or below that subdirectory | | Plugin | <plugin>/skills/<skill-name>/SKILL.md | Wherever the plugin is enabled, as /plugin-name:skill-name | | Enterprise | Managed settings directory | All users on machines where your organization deploys it | When names collide, enterprise wins over personal, and personal wins over project. Do not keep a team skill and a personal skill with the same name: you will forget which one is running. Other coding agents use different directories. The skills CLI agent table lists them: | Agent | Project path | Global path | |---|---|---| | Claude Code | .claude/skills/ | ~/.claude/skills/ | | Codex | .agents/skills/ | ~/.agents/skills/ | | Cursor | .agents/skills/ | ~/.cursor/skills/ | | Gemini CLI | .agents/skills/ | ~/.gemini/skills/ | | GitHub Copilot | .agents/skills/ | ~/.copilot/skills/ | | OpenCode | .agents/skills/ | ~/.config/opencode/skills/ | A minimal layout looks like this: .claude/skills/db-migrations/ ├── SKILL.md ├── references/ │ └── online-index.md └── scripts/ └── migrate.py Step 3: Write valid frontmatter The Agent Skills specification defines the portable fields: - name: 1 to 64 characters, lowercase a-z, 0-9, and single hyphens. It must equal the folder name. - description: 1 to 1,024 characters. Required by the spec. - Optional: license, compatibility (500 characters or fewer, only for real environment requirements), metadata (a string-to-string map; put version here, quoted), and allowed-tools (experimental, support varies by agent). --- name: db-migrations description: Write, review and safely apply Postgres schema migrations with this repo's migrate tool, including backfills, lock-safe index creation and rollback scripts. Use when the user adds or changes a column, table, index or constraint, asks why a deploy is blocked on a migration, or mentions "migration", "ALTER TABLE", "backfill" or "schema change", even if they only describe the data change they want. license: MIT metadata: version: "1.2.0" --- Claude Code accepts extra fields on top of the spec, including when_to_use, disable-model-invocation, user-invocable, allowed-tools, context: fork, and hooks. Two details from the Claude Code docs catch people: - Claude Code ignores a field it does not recognize without reporting an error, and it only reads frontmatter when the opening --- is the first line of the file. A typo like disable_model_invocation silently does nothing. - The combined description and when_to_use text is truncated at 1,536 characters in the skill listing, so put the key use case first. If your team uses several coding agents, keep shared skills to the spec fields. Harness-specific behavior (Claude Code's context: fork or hooks) is not portable, so put it in a separate, clearly named skill. Step 4: Write a description that triggers The description is the only thing the agent sees before deciding. Use this formula: <What it does, with concrete verbs and nouns>. Use when <situations, including ones where the user never names the domain>. Trigger on <phrases users actually type>. <Optional: what it is NOT for, if a sibling skill overlaps>. Compare a description that never fires with one that does: # Weak: names a tool, says nothing about when description: Internal release helper. # Strong: what, when, real phrases, and a boundary description: Cut, tag and publish a release of this monorepo's packages with the release script, including changelog generation, version bumps and npm publish with provenance. Use when the user wants to release, ship, publish or bump a package version, asks why a release CI job failed, or says "cut a release" or "tag v1.x". Not for deploying the web app; use deploy-web. Rules that hold up in testing: 1. What, then when. One sentence of concrete capability, then the situations. 2. Intent, not implementation. "Use when the user wants to..." beats "This skill uses a Python script to...". 3. Cover indirect phrasings. List symptoms and goals as well as domain keywords: "deploy is stuck", "column is missing in prod", "even if they don't say migration". 4. Name the near-misses when a sibling skill overlaps: "Not for Excel formula edits; use spreadsheet-editing." 5. No marketing adjectives. "Powerful" and "comprehensive" trigger nothing. Agents also tend to skip skills for tasks they believe are simple. A perfect description will not trigger on "read this file." Triggering matters most where the skill carries knowledge the model lacks. Step 5: Keep the body small with progressive disclosure A structure that works for most skills: # <Title> One line: what the agent achieves. ## When to use (short; the description already did the heavy lifting) ## Steps (numbered; exact commands for fragile parts) ## Defaults (the one tool or approach to use, with an escape hatch) ## Gotchas (environment facts that defy reasonable assumptions) ## Verify (how the agent checks its own work) ## References (each file, and when to read it) Guidelines: - Target 150 to 400 lines in SKILL.md. Above 500, split. - Move detail into references/<topic>.md and say when to read each file: "Read references/api-errors.md if the API returns a non-200 status." A bare "see references/" means the agent opens none of them or all of them. - Keep references one level deep. No reference-to-reference chains. - Move logic the agent re-derives every run into a tested script in scripts/, with dependencies stated, --help output, non-zero exit codes, and no interactive prompts. - Prefer one default with an escape hatch over a menu of equal options. Menus make agents try several approaches. - Cut every line where the answer to "would the agent get this wrong without it?" is no. The Claude Code cost guide makes the same point from the billing side: CLAUDE.md loads at session start, while skills load on demand, so moving specialized workflow instructions out of CLAUDE.md and into skills keeps every session's base context smaller. Step 6: Test triggering like code Guessing whether a description works is how skills end up never loading. Build an eval set instead. !Trigger eval loop for a skill description: write queries, split, run, score, edit, ship Write about 20 realistic queries in a JSON file. Half should trigger, including indirect phrasings that never name the domain. Half should be near-misses that share keywords but need something else. "What's the weather" tests nothing. [ {"query": "prod deploy is stuck on 'waiting for migration lock' again, can you look", "should_trigger": true}, {"query": "add a nullable archived_at column to invoices and backfill it from status", "should_trigger": true}, {"query": "write a SQL query for last month's revenue by region", "should_trigger": false}, {"query": "our ORM model for invoices is missing a type hint, fix it", "should_trigger": false} ] Split it roughly 60/40 into train.json and validation.json, run each query three times, and count a pass when should-trigger queries load the skill at least half the time and near-misses load it less than half the time. This runner is adapted from the agentskills.io guide to optimizing descriptions; check the JSON shape your Claude Code version emits before relying on it: #!/usr/bin/env bash set -euo pipefail QUERIES="${1:?usage: $0 queries.json}"; SKILL="${2:?skill name}"; RUNS="${RUNS:-3}" check_triggered() { claude -p "$1" --output-format json 2>/dev/null | jq -e --arg s "$SKILL" 'any(.messages[].content[]?; .type=="tool_use" and .name=="Skill" and .input.skill==$s)' >/dev/null } n=$(jq length "$QUERIES") for i in $(seq 0 $((n-1))); do q=$(jq -r ".[$i].query" "$QUERIES"); want=$(jq -r ".[$i].should_trigger" "$QUERIES"); hits=0 for _ in $(seq 1 "$RUNS"); do check_triggered "$q" && hits=$((hits+1)) || true; done jq -n --arg q "$q" --argjson want "$want" --argjson h "$hits" --argjson r "$RUNS" \ '{query:$q, should_trigger:$want, rate:($h/$r), pass:(if $want then ($h/$r)>=0.5 else ($h/$r)<0.5 end)}' done | jq -s '{pass_rate: ((map(select(.pass))|length)/length), results: .}' Iterate on the train set only, usually for five rounds or fewer: - Positives failing: the description is too narrow. Add the category of situation, not the literal failing words. - Negatives triggering: it is too broad. Add a "Not for..." boundary. - Stuck: rewrite the description's structure instead of appending more phrases. - Recheck the 1,024-character limit every round. Then run an output eval. For three to five real tasks, run the agent with and without the skill and compare correctness and wasted steps. If the agent does equally well without it, the skill adds nothing; delete it. Why your Claude skill is not triggering Work through this list in order. Most cases stop at the first two items. 1. The description describes a tool, not a situation. "Database helper" will not fire. Rewrite with the formula above. 2. The frontmatter is not being read. The opening --- must be the first line, field names must match exactly (hyphens included), and name must equal the folder name and use only lowercase letters, digits, and single hyphens. 3. The skill is in the wrong directory for the agent you are running. Claude Code reads .claude/skills/, Codex reads .agents/skills/. 4. A same-named skill shadows it. A personal skill in ~/.claude/skills/ beats the project copy. 5. disable-model-invocation: true is set. That makes the skill manual-only (/skill-name). 6. The task looks too simple to the model. Agents skip skills for tasks they think they can do alone. Name the indirect symptoms in the description. 7. The session started before you edited the skill. Running sessions keep the already-loaded version. Start a fresh session. To check discovery, ask the agent in a fresh session to list its available skills, or run claude --debug and look for the skill's name in the debug log. How to add skills to Claude Code from GitHub You do not need to hand-copy folders into each agent's directory. The open-source skills CLI installs a skill from a GitHub repository and symlinks one canonical copy into every agent you select: npx skills add your-org/team-skills --list # see what the repo offers npx skills add your-org/team-skills --skill db-migrations -a claude-code codex cursor -y npx skills add your-org/team-skills --skill db-migrations -g -a claude-code -y # user-wide npx skills list # what is installed, and from where npx skills update db-migrations # upgrade deliberately skills.sh is the public directory of skills you can install this way. Private repositories work with your existing git, gh, or SSH authentication. Share, version, and review skills across a team Once more than one person depends on a skill, it behaves like an API whose consumer is the agent. A one-line edit changes what every engineer's agent does in the next session, with no build and no visible diff in the code they are working on. Four habits keep that under control: - One source of truth. Every skill has exactly one canonical home. Repo-specific skills live in the repo; cross-cutting skills live in a shared skills repo installed with npx skills add. Delete copies once the shared source exists: a skill copied into five repos is five skills. - SemVer in metadata.version plus a CHANGELOG.md. Wording fixes are a patch. A new reference file or broader triggering is a minor. A renamed skill, a changed default command, or narrower triggering is a major. A description change is never "just docs," because it changes triggering. - A review gate. Put CODEOWNERS on the skills directory and check scripts for curl | sh, sudo, broad rm -rf, reads of ~/.ssh or ~/.aws, and undocumented network calls. Read third-party skills in full before installing them. - A rehearsed rollback. Release from tags, pin consumers to a tag, and practice rolling back once before you need to. To find drift between copies today, run this from the root of each repo and from ~: find . \( -name node_modules -o -name .git \) -prune -o -name SKILL.md -print0 | while IFS= read -r -d '' f; do printf '%s\t%s\t%s\n' "$(sed -n 's/^name:[[:space:]]*//p' "$f" | head -1)" \ "$(shasum -a 256 "$f" | cut -c1-12)" "$f" done | sort The same name with different hashes is drift. Install the agent-skills-for-teams skill !agent-skills-for-teams: write, version, review and ship Agent Skills across a team Everything in this guide is packaged as an open-source agent skill, so your coding agent can do the audit and the fixes for you. - GitHub: build-with-ai-hq/agent-skills-for-teams - skills.sh: skills.sh npx skills add build-with-ai-hq/agent-skills-for-teams To install it into specific agents, or user-wide for Claude Code: npx skills add build-with-ai-hq/agent-skills-for-teams -a claude-code codex cursor -y npx skills add build-with-ai-hq/agent-skills-for-teams -g -a claude-code -y Then ask your agent something like "my deploy skill never triggers, fix the description" or "audit the skills in this repo." When the skill loads, the agent: 1. Audits the repo for every SKILL.md, copy-paste drift, oversized skills, missing versions, and unreviewed scripts, using a bundled linter (scripts/lint_skills.py, standard library only). 2. Rewrites descriptions so they trigger on real user phrasing and sets up a trigger-rate eval with train and validation splits. 3. Restructures bloated skills with progressive disclosure. 4. Adds SemVer, changelogs, a CI lint, and a version-bump check, plus a review and security checklist. 5. Picks a distribution model (in-repo, shared git repo with npx skills add, a plugin marketplace, or a central registry) and installs consistently across coding agents. The linter also works on its own: python3 scripts/lint_skills.py . # exits 1 on errors; wire it into CI python3 scripts/lint_skills.py ~/.claude/skills ./skills For teams that need a central registry with immutable versions and one-click rollback, the skill also covers the Skills Repository built into Bifrost, the open-source AI gateway, which serves skills to Claude Code and Codex as a plugin marketplace (docs). Related reading - Skills vs MCP: When to Use a Claude Skill, an MCP Server, or Both - How to Track Claude Code Usage Across Your Team (Per Developer, Per Project) FAQ What is the difference between a Claude Code skill and a slash command? Claude Code merged custom commands into skills. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy. Skills add a folder for supporting files, frontmatter that controls who can invoke them, and automatic loading when the description matches the task. How long should a SKILL.md be? Aim for 150 to 400 lines in the body and keep it under 500 lines (about 5,000 tokens). Move anything only some tasks need into references/ with an explicit "read this when..." instruction. How do I stop Claude from loading a skill automatically? Set disable-model-invocation: true in the frontmatter. The skill then runs only when you type /skill-name, and its description is not kept in context. Can one skill work in Claude Code, Codex, and Cursor? Yes, if it sticks to the spec fields (name, description, license, compatibility, metadata, allowed-tools). Install it with npx skills add ... -a claude-code codex cursor so each agent gets a link to the same canonical copy. How do I know which version of a skill my teammates are running? Put metadata.version in every skill and ask people (or a startup script) to report npx skills list. With a central registry, the served version is the answer for everyone who installs from it.

به Claude و ChatGPT مهارت یاد بده! ابزار رایگان Vercel با یه خط Skill رو روی Agentت نصب می‌کنه. دستور: npx skills add vercel-labs/agent-skills لینک: vercel-labs/skills t.co

Mais 15 projetos open source do GitHub que valem o seu tempo | Vol. 14 Mais 15 projetos open source do GitHub que valem o seu tempo, em contagem regressiva e com 10 segundos para cada um: a distro Linux do DHH, AirDrop do iPhone para o Linux, jogos de Windows no Mac, ditado por voz offline, várias máquinas como uma só mesa e muito mais. 📺 Décimo quarto volume da série Open source do GitHub. Escolhidos pela análise da lista inteira (estrelas, frequência de commits, último commit, README, documentação, capturas e site), conferida em 23/10/2026. Qual desses você vai testar primeiro? Conta nos comentários! ⏱️ CAPÍTULOS E LINKS 0:00 Abertura 0:10 #15 NodeWarden: servidor de senhas compatível com o Bitwarden, rodando na sua própria conta da Cloudflare (4,0 mil estrelas) shuaiplus/nodewarden 0:20 #14 Skill Scanner: scanner da Cisco que procura instruções escondidas, vazamento de dados e código malicioso nas skills dos agentes (2,6 mil estrelas) cisco-ai-defense/skill-scanner 0:30 #13 Pocket TTS: voz sintética leve que roda na CPU, sem placa de vídeo, e clona vozes (10,0 mil estrelas) kyutai-labs/pocket-tts 0:40 #12 Omarchy: a distribuição Linux do DHH: bonita, cheia de atalhos e pronta para agentes (45,5 mil estrelas) omacom/omarchy 0:50 #11 Owly: AirDrop entre o iPhone e um notebook com Linux, usando o mesmo protocolo da Apple (3,0 mil estrelas) t4t5/owly 1:00 #10 Highball: roda jogos de Windows no Mac com Apple Silicon e diz com sinceridade o que funciona (1,8 mil estrelas) gauthierpiarrette/highball 1:10 #9 Hopp: compartilhamento de tela para programar em dupla, com menos de 100 ms de atraso gethopp/hopp 1:20 #8 SCM: busca nas fotos, capturas e vídeos do Mac descrevendo a cena, com IA local allenv0/SCM 1:30 #7 Sockudo: servidor de tempo real em Rust, compatível com o Pusher, para chats, notificações e painéis ao vivo sockudo/sockudo 1:40 #6 Antfly: banco de busca com IA embutida: indexa, entende e responde sobre os seus dados num processo só antflydb/antfly 1:50 #5 skills, da Vercel: instala skills em mais de 70 agentes de código com um comando (36,3 mil estrelas) vercel-labs/skills 2:00 #4 BetterWispr: segure uma tecla, fale e o texto aparece em qualquer app do Mac, sem a voz sair do computador opennookorg/betterwispr 2:10 #3 OrcaReplay: grava a execução do agente de código e repete tudo igual, offline, para achar onde ele errou Continuum-AI-Corp/OrcaReplay 2:20 #2 ACRYL: ambiente de desenvolvimento em que qualquer agente de código entra como plugin acryldev/acryl 2:30 Oferecimento Hallen Tech 2:44 #1 TwinDesk: Mac, Windows, Linux e Android como uma só mesa: telas, mouse, arquivos e até as ligações do celular InukaAsith/TwinDesk 2:54 Encerramento 🧡 Oferecimento: Hallen Tech, liderança de tecnologia sob demanda, software, cloud e segurança para a sua empresa. Site: hallentech.com E-mail: contato@hallentech.com Instagram: instagram.com LinkedIn da Hallen Tech: linkedin.com LinkedIn do Eddwan: linkedin.com Se curtiu, deixa o like, segue o canal e ativa as notificações para a próxima lista. #opensource #github #programacao #ferramentas

5 skills para Claude Code que sí vale la pena instalar Hay más de un millón de skills para Claude, pero estas cinco sí vale la pena instalarlas: 1. Superpowers: obra/superpowers 2. Claude-Mem: thedotmack/claude-mem 3. Impeccable: pbakaus/impeccable 4. Ponytail: DietrichGebert/ponytail 5. Find Skills: vercel-labs/skills Las cinco son gratis y de código abierto. Las estrellas de GitHub son del 24 de octubre de 2026. [ar] 5 مهارات لـ Claude Code تستحق التثبيت فعلاً يوجد أكثر من مليون مهارة لكلود، لكن هذه الخمس تستحق التثبيت بالتأكيد: ١. قوى خارقة: obra/superpowers ٢. ذاكرة كلود: thedotmack/claude-mem ٣. لا تشوبه شائبة: pbakaus/impeccable ٤. ذيل حصان: DietrichGebert/ponytail ٥. البحث عن المهارات: vercel-labs/skills جميعها مجانية ومفتوحة المصدر. بدأ تقييمها على GitHub في ٢٤ أكتوبر ٢٠٢٦. [en-US] 5 Claude Code skills actually worth installing There are over a million skills for Claude, but these five are definitely worth installing: 1. Superpowers: obra/superpowers 2. Claude-Mem: thedotmack/claude-mem 3. Impeccable: pbakaus/impeccable 4. Ponytail: DietrichGebert/ponytail 5. Find Skills: vercel-labs/skills All five are free and open source. Their GitHub stars are from October 24, 2026. [pt-BR] 5 skills para Claude Code que realmente vale a pena instalar Existem mais de um milhão de skills para Claude, mas estas cinco definitivamente valem a pena instalar: 1. Superpowers: obra/superpowers 2. Claude-Mem: thedotmack/claude-mem 3. Impeccable: pbakaus/impeccable 4. Ponytail: DietrichGebert/ponytail 5. Find Skills: vercel-labs/skills Todas as cinco são gratuitas e de código aberto. Suas estrelas no GitHub são de 24 de outubro de 2026.

Agent Skills Explained: How to Write a SKILL.md for Claude Code, Cursor, Codex and Copilot Agent Skills are now the standard way to teach an AI coding agent a repeatable job. Write one SKILL.md file and Claude Code, Cursor, OpenAI Codex, GitHub Copilot and VS Code can all load it. Next.js 16.4 even ships its own skills that you install with npx skills add. In this guide I build a real skill, next-security-check, that checks a Next.js app against the October 2026 security advisories. I validate it with the official skills-ref validator and install it with the skills CLI. Along the way it covers the SKILL.md format, the folder each agent actually reads, and the mistakes that stop a skill from triggering. Every rule below is cited to the Agent Skills specification or to each agent's own docs. What are Agent Skills? Agent Skills are folders of instructions, scripts and reference files that an AI agent loads on demand to do a specific task. Each skill is a directory with a required SKILL.md file: YAML frontmatter with a name and description, then Markdown instructions. The agent reads only the name and description at startup and loads the rest when a task matches. According to the Agent Skills overview, the format "was originally developed by Anthropic, released as an open standard, and has been adopted by a growing number of agent products." The client showcase lists the tools that support it, including Claude Code, Cursor, OpenAI Codex, GitHub Copilot, VS Code, Gemini CLI, OpenCode, Goose and JetBrains Junie. | Term | Meaning | | --- | --- | | Skill | A directory containing SKILL.md plus optional scripts/, references/, assets/ | | SKILL.md | Frontmatter (name, description, optional fields) followed by Markdown instructions | | Activation | The agent decides a skill is relevant, or you invoke it with /skill-name or $skill-name | | Progressive disclosure | Loading metadata first, the body on activation, and resources only when needed | | skills-ref | The reference validator from the Agent Skills project | | skills CLI | Vercel Labs' installer (npx skills add) that copies or links skills into each agent's folder | Why do Agent Skills matter right now? Skills matter because they are the first agent customization format that works across vendors. The same folder runs in Claude Code, Cursor, Codex and Copilot. Framework teams now ship them: the Next.js 16.4 release tells you to run npx skills add vercel/next.js --skill next-bundle-optimizer, then /next-bundle-optimizer "in your AI agent of choice." Running npx skills add vercel/next.js --list on October 17, 2026 showed the official Next.js skills, including: - next-bundle-optimizer: audits and cuts browser initial-load work - next-cache-components-adoption: turns on Cache Components and fixes the blocking routes it surfaces - next-cache-components-optimizer: grows the static shell, guarded by instant() tests - next-partial-prefetching-adoption and next-partial-prefetching-optimizer - next-dev-loop: verifies runtime behavior against a running next dev If you already followed my Next.js use cache guide, next-cache-components-adoption is the skill that automates that migration. How is a skill different from AGENTS.md, rules and MCP? A skill is an on-demand procedure. AGENTS.md and rules files are always-on context. An MCP server is a live tool connection. Use AGENTS.md for facts every task needs, a skill for a multi-step job that only some tasks need, and MCP when the agent must call an external system such as a database or an API. | | AGENTS.md / CLAUDE.md / rules | Agent Skill (SKILL.md) | MCP server | | --- | --- | --- | --- | | Loaded | Every session | Name and description at startup; body on activation | Tool list at startup; calls at runtime | | Best for | Conventions, commands, project facts | Repeatable procedures, checklists, scripts | Live data and actions in other systems | | Contains | Markdown | Markdown + scripts + references + assets | Running code (stdio or HTTP) | | Context cost | Always paid | About 100 tokens until used | Tool schemas, paid per server | | Portable | Mostly, file names differ | Yes, one open spec | Yes, one open protocol | Claude Code's docs put it well: create a skill "when you keep pasting the same instructions, checklist, or multi-step procedure into chat, or when a section of CLAUDE.md has grown into a procedure" (Claude Code skills). For the always-on side, see AGENTS.md vs CLAUDE.md vs Cursor rules. For live tools, see how to build an MCP server in Next.js. What does the SKILL.md format look like? A SKILL.md file starts with YAML frontmatter between --- lines, then free-form Markdown. The specification requires only two fields, name and description. license, compatibility, metadata and the experimental allowed-tools are optional. The body has no required structure; write the steps the agent should follow. The folder layout for the skill in this guide: .agents/skills/next-security-check/ ├── SKILL.md # required: frontmatter + instructions ├── scripts/ │ └── check-next-security.mjs # code the agent runs └── references/ └── advisories.md # loaded only when SKILL.md points to it Which frontmatter fields does the spec define? | Field | Required | Rule from the spec | | --- | --- | --- | | name | Yes | 1-64 chars; lowercase letters, numbers and hyphens; no leading, trailing or consecutive hyphens; must match the folder name | | description | Yes | 1-1024 chars; what the skill does and when to use it | | license | No | License name or bundled license file | | compatibility | No | Up to 500 chars; required tools, network access, target product | | metadata | No | String-to-string map, e.g. author, version | | allowed-tools | No | Space-separated pre-approved tools, e.g. Bash(git:*) Read; experimental, support varies | Agents add their own optional fields on top. Claude Code, Cursor and VS Code all support disable-model-invocation: true to make a skill run only when you type /skill-name. Claude Code and VS Code also support user-invocable: false to hide a background skill from the / menu (VS Code agent skills, Cursor skills). Other agents ignore fields they don't know. Claude Code says it "ignores a field it doesn't recognize without reporting an error." How do I create an Agent Skill step by step? To create an Agent Skill, make a folder named after the skill inside .agents/skills/, add a SKILL.md with a name that matches the folder and a description that says when to use it, then write numbered steps in the body. Put long material in references/, code in scripts/, and validate with skills-ref validate. Step 1: Create the folder mkdir -p .agents/skills/next-security-check/{scripts,references} Step 2: Write SKILL.md This is the exact file I validated and installed: --- name: next-security-check description: Checks a Next.js app against known Next.js security advisories and patches it. Use when the user asks whether their Next.js app is vulnerable, mentions a Next.js CVE or GHSA, asks to upgrade Next.js for security, or before deploying a Next.js app. license: MIT compatibility: Requires Node.js 18+ and npm, pnpm or yarn in a Next.js project metadata: author: fabwaseem version: "1.0" --- # Next.js security check ## Steps 1. Run the checker from the project root: `node .agents/skills/next-security-check/scripts/check-next-security.mjs .` Exit code 0 means patched, 1 means at least one advisory is open. 2. If it reports VULNERABLE, read [references/advisories.md](references/advisories.md) for the fixed versions, then upgrade: - Next.js 16.x: `npm install next@latest eslint-config-next@latest` - Next.js 15.x: `npm install next@15.5.28`, then `npm update sharp` 3. Run the checker again. Do not report success until it exits 0. 4. Run the project's own checks (`npm run lint`, `npm run build`) and report any failures instead of hiding them. 5. Tell the user to commit the lockfile, rebuild the Docker image without cache and redeploy. A patched laptop does not patch production. ## Gotchas - `npm audit` can miss these advisories. Trust the checker's version comparison. - On Next.js 15.5.28 the lockfile can keep `sharp` 0.34.x. Always re-check `sharp`. - Upgrading `react` does not fix Next.js: Next.js bundles its own React Server Components runtime. Upgrade `next`. - Never run `npm audit fix --force`; it can jump major versions. ## Output format Report a short table: advisory, status before, status after, action taken. The Gotchas section holds what I found the hard way while writing the Next.js security update guide. The best-practices guide says "the highest-value content in many skills is a list of gotchas," because they are facts the agent can't guess (Agent Skills best practices). Step 3: Bundle the script and the reference Copy the dependency-free checker from the security post into scripts/check-next-security.mjs, and keep the advisory table in references/advisories.md: # Next.js advisories checked by this skill | Advisory | Severity | Affected next | Fixed in | Workaround | | --- | --- | --- | --- | --- | | GHSA-673q-mjm6-r5xr: RCE in `use cache` returning typed arrays | Critical 9.5 | 16.0.0 to 16.4.0 | 16.4.1 | None | | CVE-2026-96889 / GHSA-2464-fhr4-w9xw: RCE via SVG in image optimization (sharp, glibc) | Critical 9.5 | 10.0.0 to 15.5.27, 16.0.0 to 16.4.0 | 15.5.28, 16.4.1 (sharp 0.35.5+) | sharp 0.35.5+ | | GHSA-p3m5-59mp-jv5r: DoS via Server Actions | High 8.2 | 13.0.0 to 15.5.27, 16.0.0 to 16.4.0 | 15.5.28, 16.4.1 | None | Source: https://nextjs.org/blog/nextjs-security-update-october-14-2026 The agent only reads this file when step 2 sends it there. That is progressive disclosure working as designed. Step 4: Test the script on its own A skill is only as good as its script, so run it outside the agent first. On a project with next@16.4.0 it exits 1: VULNERABLE GHSA-p3m5-59mp-jv5r (high): DoS via Server Actions fix: upgrade next to 16.4.1+ 2 issue(s) found. Patch, rebuild and redeploy. On the same project after upgrading to next@16.4.2 it exits 0 with All three October 14, 2026 advisories are patched. How do I validate a SKILL.md file? Validate a skill with skills-ref validate <folder>, the reference validator from the Agent Skills project. It checks the frontmatter against the spec: required fields, name format, name matching the directory, and field lengths. It exits 0 when the skill is valid and 1 with a list of errors otherwise, so it works in CI. Install it from the official repository (the project calls it a reference library "for demonstration purposes only", so treat it as a linter, not a runtime): python3 -m venv .venv && . .venv/bin/activate pip install "git+https://github.com/agentskills/agentskills.git#subdirectory=skills-ref" skills-ref validate .agents/skills/next-security-check Real output from my run: Valid skill: .agents/skills/next-security-check And the three mistakes I tested on purpose: $ skills-ref validate bad/Next_Security Validation failed for bad/Next_Security: - Skill name 'Next_Security' must be lowercase - Skill name 'Next_Security' contains invalid characters. Only letters, digits, and hyphens are allowed. $ skills-ref validate bad/next-check Validation failed for bad/next-check: - Directory name 'next-check' must match skill name 'next-security-check' $ skills-ref validate bad/nodesc Validation failed for bad/nodesc: - Missing required field in frontmatter: description skills-ref to-prompt <folder> prints the <available_skills> XML block an agent would inject: name, description and location. Read it to see your skill the way the model sees it before activation. Where does each agent look for skills? Each agent scans its own folders, but they overlap. .agents/skills/ is read by Codex, Cursor, VS Code and GitHub Copilot. .claude/skills/ is read by Claude Code, Cursor, VS Code and Copilot. Claude Code does not list .agents/skills/, so keep the real folder in .agents/skills/ and symlink it into .claude/skills/. !Map of agent skill folders: .agents/skills is read by Codex, Cursor, VS Code and Copilot; .claude/skills by Claude Code, Cursor, VS Code and Copilot; .github/skills by VS Code and Copilot; .cursor/skills by Cursor | Agent | Project folders | Personal folders | Manual invoke | Source | | --- | --- | --- | --- | --- | | Claude Code | .claude/skills/ (also nested <subdir>/.claude/skills/) | ~/.claude/skills/ | /skill-name | docs | | Cursor | .agents/skills/, .cursor/skills/, plus .claude/skills/ and .codex/skills/ for compatibility | ~/.agents/skills/, ~/.cursor/skills/, ~/.claude/skills/, ~/.codex/skills/ | / then the skill name | docs | | OpenAI Codex | .agents/skills/ in every directory from the working directory up to the repo root | $HOME/.agents/skills | /skills or $skill-name | docs | | VS Code (Copilot Chat) | .github/skills/, .claude/skills/, .agents/skills/ | ~/.copilot/skills/, ~/.claude/skills/, ~/.agents/skills/ | /skill-name | docs | | GitHub Copilot | .github/skills, .claude/skills, .agents/skills | ~/.copilot/skills, ~/.agents/skills | per client | docs | You don't have to set up the symlink yourself. When I installed the skill with the skills CLI for Claude Code, Codex and Cursor, it did exactly that, as the next section shows. How do I install skills with npx skills add? npx skills add <source> installs skills from a GitHub repo, a URL or a local folder. It writes one canonical copy to .agents/skills/<name>/ and symlinks it into agent folders that need a different path, such as .claude/skills/. It also records the source and a content hash in skills-lock.json so installs are reproducible. The CLI is vercel-labs/skills (version 1.7.2 on npm when I tested it). One thing tripped me up: it needs Node.js 22.20 or later. On Node 20 it crashes with SyntaxError: The requested module 'fs/promises' does not provide an export named 'glob'. On Node 24 it worked: # see what a repo offers npx skills add vercel/next.js --list # install one official Next.js skill npx skills add vercel/next.js --skill next-cache-components-adoption # install your own local skill for three agents, no prompts npx skills add ./.agents/skills/next-security-check -a claude-code -a codex -a cursor -y The result in a fresh project: ◇ Installed 1 skill │ ✓ ./.agents/skills/next-security-check │ universal: Codex, Cursor │ symlinked: Claude Code .agents/skills/next-security-check/SKILL.md .claude/skills/next-security-check -> ../../.agents/skills/next-security-check skills-lock.json On GitHub, the gh skill command in GitHub CLI can also discover and install skills from repositories (GitHub Docs). Other useful skills CLI commands: npx skills ls lists installed skills, npx skills update updates them, npx skills remove removes them, and npx skills init my-skill scaffolds a new SKILL.md. Commit .agents/, .claude/skills and skills-lock.json so the whole team gets the same skills. The CLI ends every install with a warning worth repeating: "Review skills before use; they run with full agent permissions." Read a third-party skill's SKILL.md and scripts before you install it, exactly as you would read a postinstall script. How does progressive disclosure keep context small? Progressive disclosure means the agent loads a skill in three stages. The name and description (about 100 tokens) load at startup for every skill. The full SKILL.md body (under 5,000 tokens recommended) loads when the skill activates. Files in scripts/, references/ and assets/ load only when the instructions point to them. !Progressive disclosure in three levels: metadata of about 100 tokens loaded at startup, the SKILL.md body under 5,000 tokens loaded on activation, and scripts, references and assets loaded only when needed The specification gives two size rules that follow from this: 1. Keep the main SKILL.md under 500 lines and move detailed material to separate files. 2. Keep file references one level deep from SKILL.md, and avoid chains like SKILL.md → a.md → b.md. Because only metadata is always loaded, you can install dozens of skills for little context. Claude Code caps the listing too. It truncates the combined description and when_to_use text at 1,536 characters per skill, so it tells you to put the key use case first. How do I write a description that actually triggers? Write the description as two sentences: what the skill does, then "Use when..." followed by the words a user would actually type. Agents choose skills by matching the task against the description, so vague text like "Helps with Next.js" never fires. Name concrete triggers: error messages, file names, tool names and intents. Compare: | Weak description | Strong description | | --- | --- | | Helps with Next.js security. | Checks a Next.js app against known Next.js security advisories and patches it. Use when the user asks whether their Next.js app is vulnerable, mentions a Next.js CVE or GHSA, asks to upgrade Next.js for security, or before deploying a Next.js app. | | Database stuff. | Writes and reviews Prisma migrations for PostgreSQL. Use when the user edits schema.prisma, asks for a migration, or sees a P3005 or drift error. | OpenAI's Codex docs say the same: "write concise descriptions with clear scope and boundaries. Front-load the key use case and trigger words" (Codex skills). If a skill should never fire on its own, such as a deploy or a release, set disable-model-invocation: true in clients that support it and invoke it by name. What makes a skill good? Best practices checklist A good skill encodes knowledge the agent doesn't already have, gives an order of steps, and checks its own work. The best-practices guide recommends starting from a real task you have done, adding gotchas, providing templates and checklists, and building validation loops where the agent runs a check, fixes the problem and runs it again. Use this checklist before you commit a skill: 1. One job per skill. "Check and patch Next.js security" is one job; "all things Next.js" is not. 2. Name matches the folder, lowercase with hyphens, 64 characters or fewer. 3. Description says what and when, with the trigger words a user would type. 4. Numbered steps with exact commands, not advice. 5. A Gotchas section with the non-obvious facts you learned the hard way. 6. A validation loop: run a check, fix, run it again, and only then report success (step 3 in the example). 7. Scripts for anything deterministic. A script that exits 0 or 1 beats a paragraph the model has to interpret. 8. References for long material, linked from SKILL.md, one level deep. 9. An output format so results look the same every run. 10. skills-ref validate passes in CI. 11. No secrets in the folder. Skills are committed and shared; read tokens from the environment. 12. Tested by hand in at least one agent with a prompt that should trigger the skill and one that shouldn't. Common Agent Skill mistakes The most common reasons a skill doesn't trigger or doesn't work are a folder name that doesn't match name, a vague description, a file in a folder the agent doesn't scan, and frontmatter that doesn't start on line 1. Claude Code says that if the opening --- isn't the first line it treats the whole file, markers included, as skill content. | Symptom | Likely cause | Fix | | --- | --- | --- | | Skill never appears | Wrong folder for that agent | Use .agents/skills/ plus a .claude/skills/ symlink | | Validator fails on name | Uppercase, underscores, or folder mismatch | Rename both to the same lowercase-hyphen name | | Skill appears but never auto-triggers | Description lacks trigger words | Rewrite as "Does X. Use when ..." | | Fields ignored | YAML doesn't parse or --- not on line 1 | Fix the YAML; Claude Code still loads the skill with no fields set when it doesn't parse | | Agent says "done" too early | No validation loop | Add "run the check again; do not report success until it passes" | | npx skills crashes | Node.js older than 22.20 | Upgrade Node (24 LTS works) | | Skill fires for deploys you didn't ask for | Auto-invocation on | disable-model-invocation: true | Related: Next.js links a vercel-react-view-transitions skill for adding page animations. My React View Transitions guide covers the same patterns with tested code. Related: skills, MCP servers and plain APIs overlap. See MCP vs API for a benchmarked comparison and a decision guide for when an agent needs MCP at all. Related: the AI SDK ships a migration skill for coding agents; my AI SDK 7 migration guide covers when to use it versus the official codemod, tested on a real v6 app. Key takeaways - Agent Skills are folders with a SKILL.md (YAML name + description, then Markdown steps) plus optional scripts/, references/ and assets/. - One skill works across Claude Code, Cursor, Codex, GitHub Copilot, VS Code and the other clients listed on agentskills.io. - Put skills in .agents/skills/ and symlink them into .claude/skills/ for Claude Code; npx skills add does this for you. - Only about 100 tokens of metadata load per skill until it activates, so keep SKILL.md under 500 lines and move detail into references. - The description decides whether a skill triggers: say what it does and "Use when..." with real trigger words. - Validate with skills-ref validate, put gotchas and a validation loop in every skill, and review third-party skills before installing. - Next.js 16.4 ships official skills such as next-bundle-optimizer and next-cache-components-adoption. --- Originally published on fabwaseem.com.