Claude Code Skills Guide¶
Overview¶
Claude Code Skills are reusable instructions that extend Claude Code's capabilities within the HMIS project. Skills provide project-specific knowledge and automated workflows that help developers work more efficiently. They are loaded automatically when relevant to your task or invoked manually as slash commands.
When to Use¶
- When starting a new development task with Claude Code
- When you need Claude to follow project-specific patterns and conventions
- When performing common workflows like deploying to QA or publishing documentation
- When reviewing code or preparing commits
How Skills Work¶
Skills are stored in the .claude/skills/ directory of the HMIS project. Each skill has a SKILL.md file that contains instructions Claude follows when the skill is active.
There are two types of skills:
Automatic Skills (Reference)¶
These skills are loaded automatically by Claude when your conversation matches their purpose. You don't need to do anything special - just work normally and Claude will apply the relevant guidelines.
Manual Skills (Slash Commands)¶
These skills are invoked by typing a slash command in Claude Code. Type / followed by the skill name and optional arguments.
Available Skills¶
Automatic Skills¶
These load automatically when you're working on related tasks:
| Skill | Activates When |
|---|---|
| UI Guidelines | Editing XHTML pages, working with PrimeFaces components, page layout |
| JSF AJAX | Working with AJAX updates, p:commandButton, partial page rendering |
| DTO Implementation | Creating or modifying DTOs, JPQL constructor queries |
| Database Guide | Writing database queries, MySQL operations |
| Security Privileges | Adding privileges, access control, role-based rendering |
| Pharmacy Dev | Working on pharmacy module features |
| Performance Optimization | Optimizing slow queries, autocomplete, report generation |
| App Configuration | Working with feature toggles and configuration options |
Slash Commands¶
Type these commands directly in Claude Code:
/verify-persistence¶
Checks persistence.xml for deployment readiness before git push.
Example:
What it does:
- Reads the persistence.xml file
- Checks that JNDI datasources use environment variables (not hardcoded names)
- Checks for hardcoded DDL generation paths
- Reports whether the file is deployment-ready
/publish-wiki¶
Publishes documentation from the wiki-docs/ folder to the GitHub Wiki.
Example:
What it does:
- Checks for documentation files in
wiki-docs/ - Clones or updates the sibling wiki repository
- Copies documentation files preserving directory structure
- Commits and pushes to the wiki
/write-wiki [Module/Feature-Name]¶
Creates end-user documentation following the project's wiki writing guidelines.
Example:
What it does:
- Creates a documentation file in
wiki-docs/ - Follows the standard template with required sections
- Writes for end users (not developers)
- Suggests publishing with
/publish-wikiwhen done
/deploy-qa [qa1|qa2]¶
Deploys code to QA testing environments.
Example:
What it does:
- Runs pre-deployment checks (persistence.xml verification)
- Merges development branch into the QA branch
- Pushes to trigger GitHub Actions deployment
/review-code¶
Reviews code changes against HMIS project standards.
Example:
What it does:
- Checks backward compatibility (no modified constructors, no renamed columns)
- Verifies AI suggestion patterns
- Validates persistence configuration
- Checks JSF/XHTML rules, DTO patterns, and security
/commit-code [issue-number]¶
Commits staged changes with proper HMIS conventions.
Example:
What it does:
- Reviews staged changes
- Creates a commit message with issue closing keyword (
Closes #18429) - Adds co-author attribution
- Checks for sensitive files before committing
Best Practices¶
- Let automatic skills work: Don't try to manually invoke reference skills - they load when needed
- Use slash commands for workflows: Use
/verify-persistencebefore every push - Combine commands: After
/write-wiki, use/publish-wikito publish immediately - Check before deploying: Always run
/verify-persistencebefore/deploy-qa
Troubleshooting¶
Skill Not Loading¶
If a skill doesn't seem to be active:
- Check that the
.claude/skills/directory exists in the project - Verify the skill's
SKILL.mdfile is present - Try explicitly mentioning the topic (e.g., "I'm working on AJAX updates")
Slash Command Not Found¶
If a slash command doesn't work:
- Type
/and check the autocomplete menu for available skills - Verify you're in the HMIS project directory
- Check that the skill file exists in
.claude/skills/<name>/SKILL.md
Too Many Skills Loading¶
If Claude seems to be applying too many rules:
- Be specific about what you're working on
- Skills with
disable-model-invocation: trueonly load when you invoke them
Related Features¶
- Code Conventions - Project coding standards
- Database Migration Development - Database migration workflow
- Deployment in a Development Environment - Setting up local development