Optimizing Descriptions
Meta-skill for auditing and rewriting SKILL.md `description` fields per the agentskills.io optimizing-descriptions framework, layered with mizchi's two-track trigger policy (Meta = explicit-invoke-only, Project = pushy auto-trigger). Invoke ONLY when the user explicitly asks to "optimize a skill description," "audit descriptions," or "rewrite descriptions per agentskills." Do NOT auto-invoke after every SKILL.md edit; description tuning is a deliberate batch, not a per-edit reflex.
Install
npx skills add mizchi/skills --skill optimizing-descriptionsgit clone --depth 1 https://github.com/mizchi/skills.git /tmp/skills
mkdir -p ~/.claude/skills
cp -r /tmp/skills/optimizing-descriptions ~/.claude/skills/optimizing-descriptionsPersonal skills live in ~/.claude/skills. Use .claude/skills in a project folder to share a skill with your team.
From the SKILL.md
# Optimizing Skill Descriptions Operational guide for auditing and rewriting SKILL.md `description` fields so they trigger the way mizchi wants them to. The upstream reference is [agentskills.io/skill-creation/optimizing-descriptions](https://agentskills.io/skill-creation/optimizing-descriptions). This skill keeps the framework intact and adds the mizchi-specific two-track policy on top. ## Why this exists Agents see `name + description` at startup (progressive disclosure) and decide from that alone whether to load the full SKILL.md. The description is the entire triggering contract: - **Under-specified** → skill never fires when it should. - **Over-broad** → skill fires when it shouldn't, wasting context. Both failures are silent — the skill simply isn't doing its job. This audit makes them visible. ## When to invoke Meta-skill, explicit invocation only. Triggers: - "optimize / audit / rewrite this skill's description" - "audit descriptions per agentskills" - "tune trigger accuracy" - "go through mizchi/skills and fix descriptions" Do NOT use for: - Single-skill ad-hoc edits during normal skill authoring. - Newly written skills that haven't been used yet (write the description as part of `superpowers:writing-skills`; tune only after observed mistriggering). ## Two-track policy mizchi's skills split into two categories and need **different** description shapes. Picking the wrong one is the most common audit miss.
Details
- Skill name
optimizing-descriptions- Repository
- mizchi/skills
- Path
optimizing-descriptions/SKILL.md- Repo updated
- 18 November 2026
FAQ
What does the Optimizing Descriptions skill do?
Meta-skill for auditing and rewriting SKILL.md `description` fields per the agentskills.io optimizing-descriptions framework, layered with mizchi's two-track trigger policy (Meta = explicit-invoke-only, Project = pushy auto-trigger). Invoke ONLY when the user explicitly asks to "optimize a skill description," "audit descriptions," or "rewrite descriptions per agentskills." Do NOT auto-invoke after every SKILL.md edit; description tuning is a deliberate batch, not a per-edit reflex.
How do I install the Optimizing Descriptions skill?
skills CLI (Claude Code, Cursor, Codex and more): npx skills add mizchi/skills --skill optimizing-descriptions. Skills go in ~/.claude/skills (personal) or .claude/skills (project), and Claude loads them automatically when a task matches the description.
Is Optimizing Descriptions popular?
It lives in mizchi/skills, which has 423 GitHub stars and 6 forks.
Related skills
Actions CI Tuning
423mizchi/skills
Use when auditing or improving GitHub Actions workflows for a project. Covers cache setup (npm/pnpm/yarn), job parallelism, shard-based test splitting, artifact handling pitfalls, and Playwright-specific patterns. Trigger on: slow CI, cache miss, flaky shard jobs, merge-reports failures, or an explicit 'tune CI' request.
AI Index
423mizchi/skills
Method and tooling for measuring how AI-generated a piece of prose reads, in Japanese or English. Two layers — a deterministic lint for removable surface tells (scripts/slopscore.py, no API) and a judgment layer of typed probabilistic questions (Jev noul/score) for the tells that survive editing. Includes measured human/AI baselines, a gap-first calibration procedure, and labeled fixtures. Use when building or calibrating an AI-likeness score, or when a draft needs a defensible number rather than a vibe. For writing guidance use natural-writing-ja / natural-writing-en instead.
Apm Usage
423mizchi/skills
Reference for APM manifests, installation, targeted updates, deployment paths and lockfiles. Invoke when the user explicitly asks about APM or apm.yml, or an unfamiliar APM command/error needs exact CLI details. Do not automatically invoke for every project that happens to have installed skills.
Skill Selector
423mizchi/skills
Meta-skill for picking project skills via APM. Invoke ONLY when the user explicitly asks to set up apm.yml, choose which skills a project needs, or evaluate a catalog match — do NOT auto-invoke on routine project-init or apm-management tasks. Two-phase: pick from a curated catalog first; only escalate to broader search/evaluation when the catalog has no fit. Avoids the failure mode of impulse-installing skills you never use or hand-searching GitHub when a vetted answer already exists.
Chezmoi Management
423mizchi/skills
Meta-skill for mizchi's chezmoi dotfiles. Invoke ONLY when the user explicitly asks to manage / diff / apply chezmoi sources, add a skill to dotfiles, audit the APM vs chezmoi boundary, or initialize a new machine. Covers source location, diff/apply flow, skill addition, pre-push (pkfire + secretlint). Do NOT auto-invoke when the task only happens to touch a path under ~/.claude/, ~/.config/, or ~/.zshrc — consult only on explicit dotfile-management intent.
Skill Creator
206thomast1906/github-copilot-agent-skills
Create, update, review, and validate GitHub Copilot agent skills (SKILL.md files). Use this skill whenever someone wants to create a new skill, build a skill from scratch, package domain knowledge into a reusable agent skill, turn a workflow into a skill, or asks "how do I teach Copilot to do X consistently". Also use when updating or improving an existing SKILL.md, writing the description field for better triggering, or designing the folder structure and bundled resources for a skill. Do NOT use for general coding questions, runtime debugging, or MCP server configuration.
Browse the most popular Claude skills, all skill & plugin authoring skills, or write your own with the skills generator.