Give each skill one task and name it for that task

How to do it

A skill that releases, rolls back and writes the changelog has a vague description, so the agent picks it for the wrong task. Split it into one skill per task. Use the lowercase, hyphenated folder name as the skill name. The Agent Skills format allows at most 64 characters and wants the name to match the folder. Let the person narrow the run with arguments, such as a playbook folder, a package name or --dry-run. In Claude Code, $ARGUMENTS in the skill body receives them, and argument-hint shows them in the menu. Then write a description that says when to use it.

Examples

Using these examples: they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

Markdown example

---
name: release-mobile-app
description: Build, sign and upload the iOS and Android apps for a release. Use when asked to release, ship or publish the mobile app.
argument-hint: "[ios|android|both] [--dry-run]"
---

Release the platforms in $ARGUMENTS. With `--dry-run`, build and sign but do not upload.

JavaScript example

// check-skill-names.mjs
import { readdirSync, readFileSync } from 'node:fs';
const VERB_OBJECT = /^[a-z0-9]+(-[a-z0-9]+)+$/;
for (const folder of readdirSync('.claude/skills')) {
  const name = /^name: (.+)$/m.exec(readFileSync(`.claude/skills/${folder}/SKILL.md`, 'utf8'))?.[1];
  if (name !== folder || !VERB_OBJECT.test(name) || name.length > 64) throw new Error(`Bad skill name: ${folder}`);
}

Python example

# check_skill_names.py
import pathlib, re
for skill in pathlib.Path(".claude/skills").glob("*/SKILL.md"):
    name = re.search(r"^name: (.+)$", skill.read_text(), re.M).group(1)
    if name != skill.parent.name or not re.fullmatch(r"[a-z0-9]+(-[a-z0-9]+)+", name) or len(name) > 64:
        raise SystemExit(f"Bad skill name: {skill.parent.name}")

How to check

A script fails when a name is not two or more lowercase words joined by hyphens, differs from its folder or is over 64 characters. No two skills share more than half the words of their descriptions.

Sources

• Agent Skills specification

Related rules

• Write a description that says when to use the skill in AI development