Contributing to InvestSkill

Thank you for your interest in contributing! We welcome contributions of all kinds—bug reports, feature requests, documentation, and code improvements.

Code of Conduct

Be respectful, inclusive, and professional. We’re building a community for investment research enthusiasts and professionals.

Ways to Contribute

1. 🐛 Report Bugs

Found an issue? Help us fix it.

Open a Bug Report →

Include:

• Platform (Claude Code, Cursor, Gemini CLI, etc.)
• Your version: npm test shows version
• Steps to reproduce
• Expected vs. actual behavior
• Error messages (full output)

2. 💡 Suggest Features

Have an idea for a new skill or improvement?

Start a Discussion →

Describe:

• Feature overview
• Use case example
• Why it helps users
• Implementation ideas (optional)

3. 📚 Improve Documentation

Documentation improvements are always welcome:

• Typo fixes
• Clearer examples
• Better organization
• Updated screenshots

Improvements to:

• README files
• Inline code comments
• Guides and tutorials
• FAQs

4. 🎯 Add a New Skill

Want to create a new analysis framework?

See ADDING-NEW-SKILLS.md for:

• Complete 12-step walkthrough
• File structure & templates
• Platform sync checklist
• Testing procedures
• Review process

5. 🧪 Fix Bugs

Found and fixed a bug? We’d love your PR!

6. ✨ Enhance Existing Skills

Improvements to existing frameworks:

• Better algorithms
• More comprehensive analysis
• Faster computation
• Better documentation

Development Setup

Prerequisites

• Node.js 18.0.0+
• git
• GitHub account

Local Setup

# Clone repository
git clone https://github.com/yennanliu/InvestSkill.git
cd InvestSkill

# Install dependencies (if any)
npm install

# Run test suite
npm test

# Run validation
npm run pre-release

# Verify setup
npm run verify

Test Before Submitting

# All checks
npm run pre-release

# Or individually
npm test                          # Unit tests
npm run validate                  # Prompt quality
npm run verify                    # Setup verification
npm run integration-tests         # Platform artifacts

All tests must pass before submitting a PR.

Submitting Changes

Before You Start

1. Check if your idea is already discussed in Issues or Discussions
2. For new skills: read ADDING-NEW-SKILLS.md
3. For bugs: confirm it’s reproducible locally

Creating a Pull Request

1. Fork the repository

   git clone https://github.com/YOUR-USERNAME/InvestSkill.git
   cd InvestSkill
   

2. Create a feature branch

   git checkout -b feature/your-feature-name
   # or: git checkout -b fix/issue-name
   

3. Make your changes

   • Keep commits focused (one feature/fix per commit)
   • Write clear commit messages
   • Reference issues: fixes #123

4. Test your changes

   npm test                    # Unit tests
   npm run integration-tests   # Platform tests
   npm run pre-release         # Full validation
   

5. Push to your fork

   git push origin feature/your-feature-name
   

6. Open a Pull Request

   • Reference the issue being fixed: fixes #123
   • Describe what your change does
   • Explain why it’s needed
   • Include test results (screenshots, output, etc.)

PR Checklist

• [ ] Tests pass: npm test shows 270+ passed
• [ ] Linting passes: No warnings
• [ ] Documentation updated
• [ ] Commit messages are clear
• [ ] Changes follow project conventions
• [ ] Added new tests if needed

Code Standards

Naming Conventions

• Files: kebab-case (stock-eval.md)
• Functions: camelCase (getStockMetrics())
• Constants: UPPER_SNAKE_CASE (MAX_RETRIES)
• Classes: PascalCase (StockAnalyzer)

JavaScript Style

• Use 'use strict' at top of files
• 2-space indentation
• Semicolons required
• No trailing commas in objects

Markdown Style

• 80-character line limit
• Clear section headers (# Main, ## Sub, ### Detail)
• Code blocks with language tags
• Tables for structured data
• Links in markdown: [text](url)

Comments

• Code comments: Why, not what

  // Filter out delisted tickers (removed from exchanges)
  const activeTickers = tickers.filter(t => !delistedSet.has(t));
  

• Documentation: Clear, concise, complete

  ### Feature Name
  Brief description. Key benefits. Use case.
  

Adding a New Skill

See ADDING-NEW-SKILLS.md for the comprehensive guide.

Quick summary:

1. Create skill directory: plugins/us-stock-analysis/skills/skill-name/
2. Write SKILL.md (Claude Code skill definition)
3. Copy to prompts/skill-name.md (universal prompt, no frontmatter)
4. Register in plugin.json
5. Update .cursor/rules/, GEMINI.md, .github/copilot-instructions.md
6. Update README files & CHANGELOG
7. Run full test suite
8. Submit PR with all changes

Review Process

What We Look For

✅ Good PRs have:

• Clear purpose & description
• Tests passing (270+ unit tests, 22 integration tests)
• Updated documentation
• Focused, logical commits
• Follows project conventions

❌ Issues that delay approval:

• Tests failing
• Documentation not updated
• Unclear commit messages
• Style inconsistencies
• Too many unrelated changes

Timeline

• Small fixes: 1-3 days
• New skills: 3-7 days
• Major changes: 1-2 weeks

Reviewers will provide feedback, or approve and merge.

Questions?

• How do I add a new skill? → ADDING-NEW-SKILLS.md
• I’m stuck. → GitHub Discussions
• Found a bug. → GitHub Issues
• Need help? → FAQ.md

Resources