Skills Best Practices Advanced

Design principles, naming conventions, and organizational patterns for building a reliable, maintainable library of Claude Code skills.

Skill Design Principles

🎯

Single Responsibility

Each skill should do one thing well. A /deploy skill should deploy, not also run tests and update changelogs. Compose multiple skills for complex workflows.

🔒

Safe by Default

Skills should not perform destructive actions without confirmation. Always include "ask before pushing," "do not delete without confirming," etc.

📋

Clear Output Format

Specify the expected output format in the skill. Structured output (sections, headers, lists) is easier to read and act on than free-form text.

🔧

Graceful Failure

Include instructions for what to do when something goes wrong. "If tests fail, stop and report the failures" is better than leaving it ambiguous.

Naming Conventions

Pattern Example Use Case
verb /deploy, /test, /lint Action commands
verb-noun /review-pr, /add-tests, /fix-lint Specific action on a target
noun /changelog, /migration Generate/manage a specific artifact
Guidelines:
  • Use lowercase with hyphens (kebab-case): code-review not codeReview
  • Keep names short but descriptive: /deploy over /deploy-to-staging-environment
  • Avoid conflicts with built-in commands: do not create a /commit custom skill
  • Prefix team-specific skills: /acme-deploy for company Acme

Testing Skills

  1. Test with typical input

    Run the skill with the most common use case to verify it works as expected.

  2. Test with no arguments

    If the skill uses $ARGUMENTS, verify it handles the case where no arguments are provided gracefully.

  3. Test with edge cases

    Try unusual inputs: very long file paths, files with special characters, empty repositories.

  4. Test in headless mode

    Run with claude -p "/your-skill args" to verify it works non-interactively.

Team Skill Libraries

Organize your team's skills for discoverability and maintainability:

Directory Structure 
.claude/
  commands/
    deploy.md          # /deploy - Deploy to staging
    deploy-prod.md     # /deploy-prod - Deploy to production
    code-review.md     # /code-review - Review code changes
    add-tests.md       # /add-tests - Generate unit tests
    migration.md       # /migration - Create DB migration
    changelog.md       # /changelog - Update changelog
    onboard.md         # /onboard - Explain codebase to new devs

Version Control for Skills

Best Practices:
  • Commit skills alongside the code they operate on
  • Review skill changes in PRs just like code changes
  • Include a comment at the top of each skill file describing its purpose
  • Use meaningful commit messages when updating skills: "Update /deploy skill to add health check step"

Common Mistakes

⚠

Too Vague

"Review the code and make it better" gives Claude too much freedom. Be specific about what to check and how to report findings.

⚠

Too Rigid

Overly prescriptive skills break when encountering unexpected project structures. Include fallback instructions: "If X does not exist, try Y instead."

⚠

No Error Handling

Skills that do not tell Claude what to do on failure can leave the project in a broken state. Always include "if this step fails, stop and report."

⚠

Destructive Defaults

Skills that push, delete, or overwrite without confirmation are dangerous. Always require explicit approval for destructive actions.

Frequently Asked Questions

Can I override built-in skills?

No. Built-in skills like /commit and /pr cannot be overridden by custom commands. If you name a custom command the same as a built-in, the built-in takes precedence. Use a different name for your custom version.

Can skills call other skills?

Not directly. A skill prompt cannot invoke another slash command. However, you can write a skill that includes the instructions from multiple workflows in sequence.

How long can a skill prompt be?

There is no hard limit on skill file size, but keep in mind that the entire prompt becomes part of the input tokens. Very long skill prompts (over 2,000 words) may reduce the available context for the actual task.

Can I use environment variables in skills?

The $ARGUMENTS variable is the only built-in substitution. However, you can instruct Claude to read environment variables using the Bash tool: "Read the value of $DEPLOY_TARGET from the environment."

Do skills work with all Claude models?

Yes. Skills are model-agnostic since they are just prompt templates. However, more complex skills work better with more capable models (Sonnet or Opus) than with Haiku.

← Creating Skills Course Overview →