name: createProjectSkills description: Atlas skill for designing and creating Claude Skills for project-specific codebases. USE WHEN you need to capture repeatable workflows, complex multi-step processes, or domain-specific patterns that Claude should handle consistently. context: fork user-invocable: false

Creating Claude Skills

This skill helps you design and create effective Claude Skills for the Kompass Rails application.

Quick Reference

Skill locations:

Personal: ~/.claude/skills/<skill-name>/SKILL.md (private to you)
Project: .claude/skills/<skill-name>/SKILL.md (shared with team)

When to use each:

Use Personal for your own workflow, cross-project utilities
Use Project for team-shared skills, project-specific patterns

Frontmatter format:

---
name: skill-name-in-kebab-case
description: What it does and when to use it (max 1024 chars)
---

Requirements:

Name: Gerund form (verb + -ing), lowercase, letters/numbers/hyphens only, max 64 chars
Description: Third person, specific about WHAT and WHEN, no XML tags
SKILL.md: Keep under 500 lines (use reference files for additional content)

When to Create a Skill vs. Improving CLAUDE.md

Create a skill when:

✅ Pattern requires 3+ coordinated steps that must happen in specific order
✅ Complex workflow with multiple decision points
✅ Task has validation loops (do → check → fix → repeat)
✅ Domain-specific conventions that aren't obvious from code alone
✅ You find yourself repeatedly explaining the same multi-step process
✅ Risk of missing critical steps in a workflow

Update CLAUDE.md when:

❌ Simple convention or preference (Ruby keyword shorthand, bin/rails usage)
❌ General architectural knowledge (event sourcing overview)
❌ Single-step operation
❌ Claude already knows this (Rails conventions, Ruby syntax)
❌ No specific execution order required

Rule of thumb: If it's knowledge, put it in CLAUDE.md. If it's a workflow, make it a skill.

Discovery Workflow

1. Identify Skill Candidates

Review recent work for patterns you explain repeatedly:

# Look for repeated patterns in conversation
cat TEMPLATES.md  # See common patterns worth capturing

Strong candidates in this codebase:

Event-sourced feature generation (Command → Decider → Event → Reactor → ReadModel)
Temporal query implementation (valid_at, created_at, as_of patterns)
Read model reactor creation
Multi-step forms with Turbo
Background job workflows with Commands::Async

2. Validate the Need

Ask:

Does this require multiple steps in specific order? (If no, probably not a skill)
Would missing a step cause problems? (If no, probably not a skill)
Does Claude get this wrong when you just explain it? (If no, probably not a skill)
Is this specific to our domain/codebase? (If no, probably not a skill)

If you answered "yes" to most questions, proceed to create the skill.

Writing Workflow

Step 1: Create the Skill Structure

Use the creation script with location flags:

For personal skills:

~/.claude/skills/creating-claude-skills/scripts/create_skill.sh \
  skill-name \
  "Description with 'Use when' clause" \
  --personal

For project skills:

./.claude/skills/creating-claude-skills/scripts/create_skill.sh \
  skill-name \
  "Description with 'Use when' clause" \
  --project

Auto-detection: If you omit the flag, the script auto-detects:

In git repository → creates project skill
Outside git repository → creates personal skill

Choose based on:

Use --personal for your own workflow, cross-project utilities
Use --project for team-shared skills, project-specific patterns

Plan freedom level:

High freedom (text guidance): Flexible tasks where approaches vary (designing features)
Medium freedom (pseudocode): Preferred patterns but some flexibility (creating controllers)
Low freedom (scripts): Fragile operations requiring consistency (database operations)

Plan content distribution:

SKILL.md: Core workflow, essential examples (< 500 lines)
Reference files: Deep dives, extensive examples, optional details
Scripts: Deterministic operations, validation tools

Step 2: Customize the Frontmatter

---
name: action-oriented-gerund-name
description: Verb phrase stating what it does. Second sentence explaining when to use it.
---

Good examples:

generating-event-sourced-features: Create complete event-sourced features with Commands, Deciders, Events, Reactors, and ReadModels. Use when building new domain functionality.
writing-focused-specs: Write behavior-focused RSpec tests that validate business logic without testing implementation details. Use when creating tests for Deciders, Reactors, or integration flows.

Bad examples:

helper: Helps with things (too vague)
eventing: For events (not descriptive)
rails-patterns: Rails conventions (too broad, belongs in CLAUDE.md)

Step 3: Structure the Instructions

Recommended structure:

# Skill Name

Brief overview (1-2 sentences).

## Core Workflow

1. **Step Name:** What to do
   - Sub-steps if needed
   - Key decision points

2. **Step Name:** Next action
   - Validation checks
   - Error handling

## Codebase-Specific Conventions

- Ruby keyword shorthand: `method(date:, people:)` not `method(date: date, people: people)`
- Commands: Always use `bin/rails` not `rails`
- [Any patterns specific to this skill's domain]

## Examples

[Concrete input/output examples from this codebase]

## Validation Checklist

- [ ] Item to check
- [ ] Another item
- [ ] Final verification

## References

For detailed information, see:

- `cat REFERENCE_FILE.md` - Description of what's in it

Step 4: Add Examples from This Codebase

Use real code patterns:

# Good example - shows actual conventions
class Events::Duty::Created < Events::Base
  attribute :duty_id, Types::String
  attribute :client_id, Types::String
  attribute :name, Types::String

  validates :duty_id, :client_id, :name, presence: true
end

Show input/output pairs to demonstrate expected detail level and style.

Step 5: Implement Progressive Disclosure

Keep SKILL.md focused. Move to reference files:

SKILL.md (< 500 lines):

Core workflow steps
Essential examples
Quick reference

Reference files (load on demand):

For detailed architecture patterns:

```bash
cat ARCHITECTURE.md
```

For complete examples:

cat EXAMPLES.md


### Step 6: Create Utility Scripts

**validation scripts:**
```bash
#!/bin/bash
# scripts/validate_skill.sh
# Check SKILL.md format, length, frontmatter

Helper scripts:

#!/bin/bash
# scripts/create_structure.sh
# Generate boilerplate for new features

Key principles:

Scripts solve problems, don't punt to Claude
Document why constants have specific values
Handle error conditions explicitly
Use forward slashes for paths (cross-platform)

Step 7: Validate

Run validation (path depends on where skill is located):

For personal skills:

~/.claude/skills/creating-claude-skills/scripts/validate_skill.sh <skill-dir>

For project skills:

./.claude/skills/creating-claude-skills/scripts/validate_skill.sh <skill-dir>

Check:

Frontmatter valid (name, description present and correct format)
SKILL.md under 500 lines
Description explains WHAT and WHEN
Examples use actual codebase conventions
No deeply nested references (max 1 level)
Consistent terminology throughout
Validation steps for critical operations
Scripts include error handling

Codebase-Specific Considerations

Event Sourcing Patterns

Skills dealing with event sourcing should reference the flow:

Command (user intention)
Decider (validation, event production)
Event (immutable fact)
Reactor (side effects)
ReadModel (query optimization)

Ruby Conventions

Always demonstrate:

Keyword shorthand: create_event(duty_id:, name:)
bin/rails commands: bin/rails generate migration
Dry-rb patterns: Success(event), Failure(errors)

Testing Philosophy

Skills about testing should emphasize:

Test BEHAVIOR not IMPLEMENTATION
Focus on events created and data correctness
Test validation failures with proper errors
Test noop scenarios
Avoid testing that classes derive from bases or respond_to methods

Technology Stack

Reference when relevant:

Tailwind CSS for styling
Stimulus for JavaScript interactivity
Turbo for SPA-like navigation
Pundit for authorization
Sidekiq for background jobs

Templates

See common skill templates:

cat TEMPLATES.md

Examples

See working examples of skills for this codebase:

cat EXAMPLES.md

Quality Checklist

Before finalizing any skill:

Name uses gerund form (verb + -ing)
Name is lowercase with hyphens only
Description states WHAT and WHEN clearly
SKILL.md is under 500 lines
Examples use actual codebase patterns
Ruby keyword shorthand in all examples
Uses bin/rails not rails
References are one level deep only
Scripts include error handling
No time-sensitive information
Consistent terminology throughout
Validation steps for critical operations
Adds value beyond what's in CLAUDE.md
Solves a real repeated problem

Anti-Patterns

Avoid:

❌ Skills that just restate CLAUDE.md content
❌ Skills for single-step operations
❌ Vague or overly generic descriptions
❌ Assuming tools/gems are installed
❌ Deeply nested file references (> 1 level)
❌ Mixing terminology (pick one term and stick to it)
❌ Missing concrete examples
❌ Scripts that punt error handling to Claude
❌ Time-sensitive information (dates, versions)

Iteration Process

Build evaluation first: Test Claude WITHOUT the skill to identify gaps
Create minimal skill: Address the specific gaps only
Test with fresh context: Use new Claude instance to test
Observe navigation: Notice how Claude uses your references
Iterate based on behavior: Refine based on actual performance gaps

Remember: Conciseness is essential. Every line competes for context window space. Challenge every explanation with "Does Claude really need this?" Default to assuming Claude is knowledgeable.

skill-name-in-kebab-case

SKILL.md