Contributing

How to contribute to the UX Writing Skill project

Thanks for your interest in improving this skill! Contributions are welcome and appreciated.

Ways to contribute

1. Report issues

• Found a typo or error? Open an issue
• Unclear instructions? Let us know
• Missing a common pattern? Suggest it

2. Share examples

• Real-world before/after improvements
• Industry-specific patterns (healthcare, fintech, etc.)
• Unique voice applications
• Edge cases or tricky scenarios

3. Add templates

• New UI patterns (e.g., chat interfaces, voice assistants)
• Specialized content types (legal, medical, technical)
• Workflow templates
• Evaluation frameworks

4. Improve documentation

• Clarify existing instructions
• Add more examples to patterns
• Translate to other languages
• Update outdated references

5. Extend reference materials

• Accessibility guidelines
• Localization best practices
• Industry-specific standards
• Research citations

For non-technical contributors

New to GitHub? No problem! You don’t need to be a developer to contribute. Here are simple ways to share your expertise.

Option 1: Open an issue

1. Go to the repository on GitHub
2. Click the “Issues” tab at the top
3. Click the green “New issue” button
4. Describe your contribution:
   • Paste your suggested text or example
   • Explain what it improves or adds
   • Include any context that’s helpful
5. Click “Submit new issue”

That’s it! A maintainer will review and incorporate your contribution.

Option 2: Edit files directly on GitHub

You can edit files right in your browser without installing anything:

1. Navigate to the file you want to edit (like examples/real-world-improvements.md)
2. Click the pencil icon (✏️) in the top right corner
3. Make your changes in the editor
4. Scroll down to the “Propose changes” section
5. Write a brief description of what you changed
6. Click “Propose changes” (green button)
7. Click “Create pull request” on the next screen

GitHub will handle the technical parts automatically. A maintainer will review your changes and merge them.

Option 3: Send it directly

If GitHub feels overwhelming, you can:

• Email your contribution to the maintainer (see README for contact)
• Share a Google Doc with your suggested additions
• Post in community channels where this skill is discussed

Someone will help get your contribution into the repository.

What makes a good contribution?

Whether you’re submitting an issue or editing directly:

• Be specific: Instead of “add more examples,” share the actual example
• Explain the value: Why is this helpful? What problem does it solve?
• Keep it realistic: Use examples from actual products when possible
• Follow the existing format: Look at similar content and match the style

Don’t worry about perfection

Submit your idea even if:

• You’re not sure about the formatting
• Your example isn’t polished yet
• You’re uncertain if it fits

Maintainers can help refine it. The hard part is having the expertise — you have that!

Need help?

Stuck on something? Open an issue with the title “Help: [what you need]” and describe where you’re stuck. The community is here to help.

Contribution guidelines

Content standards

All contributions should follow these principles:

1. Evidence-based: Based on established UX writing best practices or user research
2. Actionable: Provides clear, practical guidance
3. Concise: Respects the reader’s time
4. Well-structured: Easy to scan and reference
5. Example-rich: Shows, doesn’t just tell

Style guidelines

• Use sentence case for headings
• Use em dashes (—) not hyphens (-) for breaks
• Keep examples realistic and specific
• Include both “do” and “don’t” examples where helpful
• Score examples against the four quality standards when relevant

File organization

ux-writing/
├── SKILL.md (core principles and patterns)
├── README.md (GitHub documentation)
├── references/ (supporting materials)
│   ├── voice-chart-template.md
│   ├── content-usability-checklist.md
│   └── patterns-detailed.md
├── examples/ (real-world applications)
│   └── real-world-improvements.md
└── templates/ (fillable guides)
    ├── error-message-template.md
    ├── empty-state-template.md
    └── onboarding-flow-template.md

Adding new content

New examples go in examples/

• Show before/after with scoring
• Explain why the improvement works
• Keep consistent with existing format

New templates go in templates/

• Provide clear structure and guidance
• Include checklist for verification
• Show filled examples

New reference materials go in references/

• Comprehensive coverage of topic
• Links to authoritative sources
• Maintains consistent voice

Submitting changes

1. Fork the repository
2. Create a feature branch (git checkout -b add-chat-pattern)
3. Make your changes following the guidelines above
4. Test the skill — verify Claude can use your additions effectively
5. Update CHANGELOG.md with your changes under “Unreleased”
6. Submit a pull request with clear description of what and why

Pull request template

## What does this PR do?
[Brief description of changes]

## Why is this needed?
[Explain the problem this solves or value it adds]

## What type of contribution is this?
- [ ] Bug fix
- [ ] New example
- [ ] New template
- [ ] New reference material
- [ ] Documentation improvement
- [ ] Other (please describe)

## Have you:
- [ ] Tested the skill with your changes?
- [ ] Followed the style guidelines?
- [ ] Updated CHANGELOG.md?
- [ ] Added examples where applicable?

## Additional context
[Any other relevant information]

Code of conduct

Our standards

• Respectful: Treat all contributors with respect
• Constructive: Provide helpful, actionable feedback
• Inclusive: Welcome contributions from all backgrounds
• Patient: Remember everyone is learning

Unacceptable behavior

• Harassment or discrimination
• Unconstructive criticism
• Spam or promotional content
• Sharing private information

Questions?

Not sure if your idea fits? Open an issue to discuss before investing time in a full PR.

Recognition

Contributors will be acknowledged in:

• CHANGELOG.md for specific contributions
• README.md for significant additions
• Special recognition for ongoing contributors

License

By contributing, you agree that your contributions will be licensed under the same MIT License that covers this project.

---

Thank you for helping make UX writing more systematic and accessible!