Best Practices for Naming Skills in knowledge-work-plugins

Use kebab-case (lowercase letters separated by hyphens), ensure the name: field matches the directory name exactly, and never change a skill's identifier after publication to avoid breaking downstream integrations.

The anthropics/knowledge-work-plugins repository organizes reusable AI workflows as "skills" defined in SKILL.md files. Consistent naming conventions are critical because these identifiers are referenced programmatically across connectors, runbooks, and user interfaces. Adhering to the established patterns ensures skills remain discoverable, parseable in YAML configurations, and stable throughout the plugin lifecycle.

Adopt Kebab-Case for All Skill Identifiers

Every skill name in the repository uses kebab-case: lowercase letters with words separated by single hyphens. This convention eliminates parsing ambiguities and ensures compatibility with URL paths and YAML keys.

• Use only lowercase letters (a-z) and hyphens (-).
• Avoid spaces, underscores, camelCase, or PascalCase.
• Keep names concise but descriptive of the domain action.

Examples from the codebase include ticket-deflector, tax-season-organizer, and lead-triage. Each follows the pattern of domain-action or purpose-descriptor.

Align the name Field with the Directory Structure

The name: field inside SKILL.md must match the containing folder name exactly. This one-to-one mapping prevents configuration drift and simplifies automated discovery.

In small-business/skills/ticket-deflector/SKILL.md, the declaration reads:

name: ticket-deflector

The directory structure mirrors this identifier:

small-business/
└── skills/
    └── ticket-deflector/
        ├── SKILL.md
        └── reference/

Similarly, [tax-season-organizer/SKILL.md](https://github.com/anthropics/knowledge-work-plugins/blob/main/small-business/skills/tax-season-organizer/SKILL.md) declares name: tax-season-organizer. Maintaining this parity ensures that file system paths and programmatic references resolve correctly.

Treat Skill Names as Immutable Identifiers

Once a skill is published, its name becomes a stable contract. The [cowork-plugin-customizer/SKILL.md](https://github.com/anthropics/knowledge-work-plugins/blob/main/cowork-plugin-management/skills/cowork-plugin-customizer/SKILL.md) explicitly warns: "Never change the name of the plugin or skill being customized."

Renaming a skill after creation forces updates to:

• Connector configurations that invoke the skill by name.
• Documentation and runbooks referencing the identifier.
• Downstream automation scripts relying on the path structure.

If the functionality evolves significantly, create a new skill with a distinct name rather than modifying the existing identifier.

Practical Implementation Examples

When authoring a new skill, structure the SKILL.md header as follows:

name: invoice-chaser
description: Automate polite follow-ups for overdue client invoices.

The corresponding file system layout should be:

small-business/
└── skills/
    └── invoice-chaser/
        ├── SKILL.md   # Contains `name: invoice-chaser`

        └── reference/

Avoid these common anti-patterns:

• ❌ name: InvoiceChaser (uses uppercase)
• ❌ name: invoice_chaser (uses underscore)
• ❌ name: invoice chaser (uses space)
• ❌ name: deflector (does not match folder ticket-deflector)

Summary

• Use kebab-case (lowercase with hyphens) for all skill names to ensure URL and YAML safety.
• Match the directory name exactly in the name: field of SKILL.md to maintain path consistency.
• Never rename skills after publication to prevent breaking existing integrations.
• Avoid spaces and special characters that complicate parsing and filesystem operations.
• Reference existing skills like ticket-deflector and tax-season-organizer as canonical examples.

Frequently Asked Questions

What case format should I use when naming skills in knowledge-work-plugins?

Use kebab-case, which means all lowercase letters with words separated by hyphens (e.g., lead-triage, tax-season-organizer). This format ensures compatibility with file systems, URLs, and YAML configuration files throughout the repository.

Should the skill name match the folder name exactly?

Yes. The value of the name: field in SKILL.md must be identical to the containing directory name. For example, the skill located at small-business/skills/ticket-deflector/ must declare name: ticket-deflector in its configuration file.

Can I rename a skill after it has been published?

No. According to the source code in [cowork-plugin-customizer/SKILL.md](https://github.com/anthropics/knowledge-work-plugins/blob/main/cowork-plugin-management/skills/cowork-plugin-customizer/SKILL.md), you should never change the name of a skill after creation. Renaming breaks existing references in connectors, runbooks, and automated workflows that rely on the stable identifier.

Are spaces allowed in skill names?

No. Spaces are prohibited because they cause parsing errors in YAML files and create invalid URL paths. Always use hyphens to separate words in skill identifiers.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}