Command Code

Best Practices for Skills

Follow these best practices to create effective and maintainable skills.

Writing effective descriptions

Good descriptions help Command Code know when to use a skill:

Specific and keyword-rich:

description: Extract text and tables from PDF files using pdfplumber. Use when user mentions PDFs, pdf files, document extraction, or needs to read PDF content.

Too vague:

description: PDF tools

Keep skills focused

Each skill should do one thing well:

Focused:

  • code-review - Code review checklist
  • commit-messages - Commit message format
  • testing-patterns - Testing conventions

Too broad:

  • development - All development tasks

Pick a name that does not collide

Skill names share the / menu with built-in commands like /clear, /help, /share, and /rewind, and with any custom commands you define in .commandcode/commands/. Those take precedence — typing /<name> routes to the owner and the skill renders with a shadowed by note next to its [skill] badge.

Prefer task-oriented names that are unlikely to overlap:

Safe: pr-desc, api-guidelines, release-notes, code-review

Risky: clear, help, share, rewind — these are built-in.

Use progressive disclosure

Keep SKILL.md concise. Move detailed content to references/, for example:

# API Guidelines Quick reference of our API patterns. For complete documentation, see: - [Authentication details](references/AUTH.md) - [Error handling guide](references/ERRORS.md) - [Versioning strategy](references/VERSIONING.md)

Version control

Track your skills in Git:

Git tracking

# Add skills to git git add .commandcode/skills/ # Commit git commit -m "Add API guidelines skill" # Share with team git push

Don't ignore .commandcode/skills/ - these should be shared with your team.

Next steps