Claude Code Custom Skills
Relevant source files
The following files were used as context for generating this wiki page:
Claude Code Custom Skills are specialized configuration files and behavioral guidelines located within the .claude/skills/ directory of the MoodTune repository. These skills serve to instruct the Claude Code agent on project-specific workflows, coding standards, and automated task execution, ensuring consistency across development activities such as commits, testing, and architecture implementation.
These skills complement the high-level project guidance found in CLAUDE.md and technical specifications like the Authentication System Implementation Plan and Routing System Implementation Plan.
Skill Architecture and Components
The custom skills system is designed to provide granular control over how the AI agent interacts with the codebase. The architecture relies on Markdown-based skill definitions that describe the "what," "why," and "how" of specific development tasks.
Skill Definition Structure
A custom skill typically includes a purpose statement, a set of triggers or conditions, and a step-by-step execution protocol. For example, the commit skill focuses on maintaining a high standard for version control history.
The diagram above illustrates how the Claude Code agent identifies and processes custom skills within the repository structure.
Sources: .claude/skills/commit/SKILL.md:1-5, CLAUDE.md:1-5
Core Development Skills
Automated Commit Management
The commit skill defines the protocol for generating high-quality Git commit messages. It emphasizes technical accuracy and adherence to the project's specific conventions, such as referencing relevant features like "Mood analysis" or "Spotify OAuth".
| Component | Responsibility |
|---|---|
| Message Generation | Summarizing changes based on diffs across Data, Domain, and Presentation layers. |
| Context Awareness | Identifying if changes affect specific systems like Supabase auth or FastAPI backend. |
| Formatting | Ensuring messages follow the standard header/body structure. |
Sources: .claude/skills/commit/SKILL.md:1-10, CLAUDE.md:37-45, README.md:43-52
Integration with Project Standards
Custom skills are intrinsically linked to the project's Clean Architecture and testing requirements. The agent uses these skills to ensure that code generated or modified adheres to the inward-pointing dependency rule (Presentation → Domain ← Data).
This diagram shows the dependency flow that Claude Code must respect when applying custom skills to modify the repository.
Sources: CLAUDE.md:65-75, authplan.md:30-45
Skill-Driven Workflows
Environment and Setup
Skills often reference specific environment variables and command-line interfaces used in the project, such as flutter run --flavor and very_good test.
| Command Category | Specific Tooling | Source Reference |
|---|---|---|
| Running the App | flutter run --flavor development --dart-define-from-file=dev.env | CLAUDE.md:13-17 |
| Testing | very_good test --coverage | CLAUDE.md:25-30 |
| Code Generation | flutter packages pub run build_runner build | CLAUDE.md:47-51 |
Navigation and Routing Logic
Custom skills assist in maintaining the AppRouter and RouteNames structure, ensuring that new routes are added in compliance with the go_router implementation plan. This includes reactive auth handling via refreshListenable.
Sources: routing_plan.md:35-50, routing_plan.md:158-175
The sequence shows the multi-file update process driven by custom skills to maintain routing integrity.
Sources: routing_plan.md:52-65, routing_plan.md:215-230
Summary
Claude Code Custom Skills provide the necessary guardrails for AI-assisted development in the MoodTune project. By codifying commit standards, architectural rules, and specific command sequences into the .claude/skills/ directory, the project ensures that the Claude Code agent operates as a technically accurate and context-aware extension of the development team. This system bridges the gap between general AI capabilities and the specific requirements of a Flutter/FastAPI/Supabase stack.