@v587d/capital-generation 2.7.0 → 2.7.1

package/selected-skills/InvestSkill/ADDING-NEW-SKILLS.md

@@ -0,0 +1,546 @@
+# Adding a New Skill to InvestSkill
+
+Comprehensive guide for contributing a new analysis skill to the InvestSkill project.
+
+> **Fast path.** Most of the steps below are automated:
+>
+> ```bash
+> node scripts/new-skill.js my-analysis --category advanced \
+>   --title "My Analysis" --desc "One-line description" \
+>   --zh-title "中文名" --goal "I want to …" --goal-zh "我想要…"
+> ```
+>
+> This scaffolds `SKILL.md` with the full output contract already in place (Data Verification gate, `Data & Sources` header, Thesis Invalidation, Investment Signal block, disclaimer), generates `prompts/my-analysis.md`, adds the skill to the site's `SKILL_CATEGORIES`, inserts "goal → skill" rows in both `CHOOSE-A-SKILL` pages, adds README / cross-AI table rows and directory-tree lines, and writes a `CHANGELOG.md` line under `[Unreleased]`. You then write the analysis, run `node scripts/sync-prompts.js my-analysis`, update the two Cookbook skill counts, and run `npm test`. The manual walkthrough below explains what each of those files is for.
+>
+> **The prompt is generated, never hand-edited.** `prompts/<name>.md` is produced from `SKILL.md` by `scripts/sync-prompts.js` (frontmatter stripped, `/us-stock-analysis:x` → `x`, `/x` → `x`, "Claude analyzes" → "The assistant analyzes"). `npm test` runs `sync-prompts.js --check` and fails on drift. Write anything platform-specific platform-neutrally in `SKILL.md` itself.
+>
+> **The output contract is enforced.** `scripts/check-skill-contract.js` (in `npm test`) fails if any analysis skill lacks the Data Verification gate, the `Data & Sources` header, a Thesis Invalidation section, the signal block, or the disclaimer. Output tools, aliases, and meta skills are exempt via `scripts/lib/skill-registry.js`.
+
+---
+
+## Table of Contents
+
+1. [Understanding Skills](#understanding-skills)
+2. [File Structure](#file-structure)
+3. [Step-by-Step Walkthrough](#step-by-step-walkthrough)
+4. [Testing Your Skill](#testing-your-skill)
+5. [Platform Sync Checklist](#platform-sync-checklist)
+6. [Review Process](#review-process)
+
+---
+
+## Understanding Skills
+
+An InvestSkill **skill** is a reusable investment analysis framework available across multiple platforms:
+
+- **Claude Code Plugin**: `/skill-name` command with parameters
+- **Cursor IDE**: `@prompts/skill-name.md` file reference in rules
+- **Gemini CLI**: `@prompts/skill-name.md` file reference in GEMINI.md
+- **GitHub Copilot**: Context-loaded from `.github/copilot-instructions.md`
+- **Universal**: Copy-paste from `prompts/skill-name.md`
+
+### Skill Categories
+
+| Category (`--category`) | Purpose | Examples |
+|--------------------------|---------|----------|
+| Core Stock Analysis (`core`) | Fundamental evaluation and valuation | stock-eval, stock-valuation, technical-analysis, economics-analysis |
+| Financial Reports (`reports`) | Document analysis | financial-report-analyst, 10k-digest, earnings-call-analysis |
+| Market Monitoring (`monitoring`) | Activity tracking | insider-trading, dividend-analysis, short-interest |
+| Advanced Research (`advanced`) | Specialized evaluation | bear-case, position-ladder, thesis-tracker, industry-map |
+| Meta & Output (`meta`) | Orchestration, validation, output | full-report, result-validator, chart-master, report-generator |
+| Aliases | Redirect stubs — installed, **not counted as frameworks** | fundamental-analysis → stock-eval, dcf-valuation → stock-valuation, research-bundle → full-report |
+
+The advertised framework count is derived: skill directories − output tools − aliases (`scripts/lib/skill-registry.js`). Do not hardcode it anywhere; `npm test` checks every doc that states it.
+
+---
+
+## File Structure
+
+When adding a new skill named `my-analysis`, create these files:
+
+```
+InvestSkill/
+├── plugins/us-stock-analysis/skills/my-analysis/
+│   ├── SKILL.md                  ← Claude Code skill definition
+│   └── ...                         ← Any supporting files
+├── prompts/
+│   └── my-analysis.md             ← Universal prompt — GENERATED by scripts/sync-prompts.js
+├── site/build/build-site.js       ← Add to SKILL_CATEGORIES (new-skill.js does this)
+├── site/content/CHOOSE-A-SKILL*.md ← "goal → skill" row, both languages
+├── .cursor/rules/
+│   └── invest-skill.mdc           ← Update with new skill reference
+├── .github/
+│   └── copilot-instructions.md    ← Update with new skill
+├── GEMINI.md                      ← Update with new skill
+├── README.md                      ← Update features list
+├── README-*.md                    ← Update platform-specific guides
+└── CHANGELOG.md                   ← Record the addition
+```
+
+---
+
+## Step-by-Step Walkthrough
+
+### Step 1: Create Skill Directory
+
+```bash
+mkdir -p plugins/us-stock-analysis/skills/my-analysis
+cd plugins/us-stock-analysis/skills/my-analysis
+```
+
+### Step 2: Create SKILL.md File
+
+Create `SKILL.md` with this structure:
+
+```markdown
+---
+description: Brief one-line description of the skill
+---
+
+# My Analysis Skill
+
+## Overview
+[2-3 sentences explaining what this skill does and when to use it]
+
+## Framework
+
+### Phase 1: [Phase Name]
+[Describe the first analysis phase]
+
+### Phase 2: [Phase Name]
+[Describe the second phase]
+
+## Inputs Required
+
+- **Stock Ticker**: AAPL, MSFT, etc.
+- **Optional Data**: [Any additional data needed]
+
+## Output Format
+
+All analyses include:
+
+1. **Executive Summary** — Key findings (2-3 sentences)
+2. **Quantitative Analysis** — Specific metrics and numbers
+3. **Qualitative Assessment** — Market dynamics, competitive factors
+4. **Investment Signal Block** — Standard signal box
+
+### Investment Signal Block
+
+```
+╔══════════════════════════════════════════════╗
+║              INVESTMENT SIGNAL               ║
+╠══════════════════════════════════════════════╣
+║ Signal:      BULLISH / NEUTRAL / BEARISH     ║
+║ Confidence:  HIGH / MEDIUM / LOW             ║
+║ Horizon:     SHORT / MEDIUM / LONG-TERM      ║
+║ Score:       X.X / 10                        ║
+╠══════════════════════════════════════════════╣
+║ Action:      BUY / HOLD / SELL               ║
+║ Conviction:  STRONG / MODERATE / WEAK        ║
+╚══════════════════════════════════════════════╝
+```
+
+## Example
+
+> Analyze Apple (AAPL) using the [skill name] framework
+
+[Provide a realistic example output matching the signal block format]
+
+## Notes
+
+- [Any important caveats or assumptions]
+- [Limitations of the framework]
+- [When to use vs. when to use other skills]
+
+---
+
+**Framework Version**: 1.0  
+**Last Updated**: [Date]  
+**Status**: Active
+```
+
+### Step 3: Generate prompts/my-analysis.md
+
+```bash
+node scripts/sync-prompts.js my-analysis
+```
+
+The universal prompt is **generated** from `SKILL.md` — never edit it by hand. `npm test` runs `sync-prompts.js --check` and fails if the two drift. The generator strips the frontmatter and rewrites Claude Code syntax (`/us-stock-analysis:x` → `x`, `/x` → `x`); anything else platform-specific must be written platform-neutrally in `SKILL.md`.
+
+### Step 4: Manifests
+
+Skills are **auto-discovered** from `plugins/us-stock-analysis/skills/` — there is no `skills[]` array to edit in `plugin.json`. The version is bumped at release time (`npm run release`), in all three manifests at once (`plugin.json`, `.claude-plugin/marketplace.json`, `package.json`); see the Release Timing Rule in `CLAUDE.md`. If you do bump in the branch, keep all three equal — `npm test` checks parity.
+
+### Step 5: Update the site
+
+Add the skill to `SKILL_CATEGORIES` in `site/build/build-site.js` (otherwise it renders under "Other"), and add a "goal → skill" row to `site/content/CHOOSE-A-SKILL.md` **and** `CHOOSE-A-SKILL-zh-TW.md`. `new-skill.js` does both. Update the skill counts in `site/content/COOKBOOK.md` and `COOKBOOK-zh-TW.md` ("N available skills") — `npm test` checks them.
+
+### Step 6: Update .cursor/rules/invest-skill.mdc
+
+Add a reference to the new skill in the rules file. Find the section listing all frameworks and add:
+
+```
+@prompts/my-analysis.md for My Analysis Skill — [brief description]
+```
+
+### Step 7: Update .github/copilot-instructions.md
+
+Add the skill to the framework list:
+
+```markdown
+## Available Frameworks
+
+### [Category Name] (N)
+- My Analysis Skill (`@prompts/my-analysis.md`) — [description]
+```
+
+### Step 8: Update GEMINI.md
+
+Add to the appropriate section:
+
+```markdown
+@prompts/my-analysis.md for My Analysis Skill — [brief description]
+```
+
+### Step 9: Update README.md
+
+1. Add to features list
+2. Add skill to appropriate section
+3. Add usage example
+4. Update the skill/framework count to the new total (in every header and intro that states it)
+
+### Step 10: Update Platform-Specific README Files
+
+Update each of these:
+- `README-claude-code.md` — Add `/my-analysis` command and example
+- `README-cursor.md` — Add to skill table
+- `README-gemini.md` — Add to framework list
+
+### Step 11: Update CHANGELOG.md
+
+Add to the `[Unreleased]` section:
+
+```markdown
+## [Unreleased]
+
+### Added
+- New `/my-analysis` skill for [description]
+  - [Key feature 1]
+  - [Key feature 2]
+  - [Key feature 3]
+```
+
+### Step 12: Commit Changes
+
+```bash
+git add -A
+git commit -m "feat: add my-analysis skill for [description]
+
+- New SKILL.md with [key features]
+- Universal prompt: prompts/my-analysis.md
+- Registered in all platforms: Claude Code, Cursor, Gemini, Copilot
+- Platform docs updated: README*.md
+
+Total skills: N → N+1"
+```
+
+---
+
+## Testing Your Skill
+
+### 1. Run Unit Tests
+
+```bash
+npm test
+```
+
+`npm test` runs four suites: structure and counts (`test-skills.js`), the skill contract (`check-skill-contract.js`), prompt sync (`sync-prompts.js --check`), and the install script (`test-install.js`). All must pass; the exact check count grows with each skill, so no number is stated here.
+
+To check that the skill *behaves* — not just that it is shaped right — run the opt-in behavioural eval against the fictional fixture: `EVAL_CMD='claude -p' node scripts/eval-skills.js --skills my-analysis` (see `scripts/eval-skills.js` and `data/fixtures/ZEPH.md`).
+
+### 2. Verify File Structure
+
+```bash
+# Check SKILL.md exists
+ls plugins/us-stock-analysis/skills/my-analysis/SKILL.md
+
+# Check prompts/ sync
+ls prompts/my-analysis.md
+
+# Check frontmatter removed from prompts version
+head -1 prompts/my-analysis.md  # Should NOT start with ---
+```
+
+### 3. Validate JSON Manifests
+
+```bash
+jq empty plugins/us-stock-analysis/.claude-plugin/plugin.json
+jq empty .claude-plugin/marketplace.json
+echo "✅ JSON valid"
+```
+
+### 4. Test Signal Block Format
+
+The SKILL.md must include a properly formatted signal block at the end:
+
+```bash
+grep -A 10 "INVESTMENT SIGNAL" plugins/us-stock-analysis/skills/my-analysis/SKILL.md
+```
+
+### 5. Test Across Platforms (Manual)
+
+**Claude Code:**
+```bash
+claude
+/plugin list | grep my-analysis
+/us-stock-analysis:my-analysis AAPL
+```
+
+**Cursor:**
+```bash
+cursor .
+# In AI Chat:
+@prompts/my-analysis.md Analyze AAPL
+```
+
+**Gemini CLI:**
+```bash
+cd /path/to/InvestSkill
+gemini
+> @prompts/my-analysis.md Analyze AAPL
+```
+
+---
+
+## Platform Sync Checklist
+
+Use this checklist to ensure your skill is available across all platforms:
+
+```
+Claude Code Plugin
+  ☐ Registered in plugins/us-stock-analysis/.claude-plugin/plugin.json
+  ☐ SKILL.md file created with frontmatter
+  ☐ Tested with /us-stock-analysis:my-analysis
+  ☐ Appears in /plugin list
+
+Cursor IDE Rules
+  ☐ Added to .cursor/rules/invest-skill.mdc
+  ☐ Referenced with @prompts/my-analysis.md
+  ☐ Tested in Cursor AI Chat (Cmd+K)
+
+Gemini CLI
+  ☐ Added to GEMINI.md
+  ☐ Referenced with @prompts/my-analysis.md
+  ☐ prompts/my-analysis.md exists (no frontmatter)
+  ☐ Tested with > @prompts/my-analysis.md
+
+GitHub Copilot
+  ☐ Added to .github/copilot-instructions.md
+  ☐ Works in VS Code / JetBrains
+
+Universal Access
+  ☐ prompts/my-analysis.md created (AI-agnostic)
+  ☐ No slash commands or platform-specific syntax
+  ☐ Compatible with ChatGPT, Claude.ai, etc.
+
+Documentation
+  ☐ README.md updated
+  ☐ README-claude-code.md updated
+  ☐ README-cursor.md updated
+  ☐ README-gemini.md updated
+  ☐ CHANGELOG.md updated
+
+Quality
+  ☐ Frontmatter in SKILL.md only (not in prompts/)
+  ☐ Signal block at end of both files
+  ☐ npm test passes (270+ tests)
+  ☐ No JSON validation errors
+```
+
+---
+
+## Review Process
+
+### Before Submitting PR
+
+1. **Run pre-release validation**:
+   ```bash
+   npm run pre-release
+   ```
+
+2. **Check test coverage**:
+   ```bash
+   npm test 2>&1 | tail -20
+   ```
+
+3. **Verify version bumps**:
+   ```bash
+   jq '.version' plugins/us-stock-analysis/.claude-plugin/plugin.json
+   jq '.metadata.version' .claude-plugin/marketplace.json
+   # Both should match (e.g., 1.5.0)
+   ```
+
+4. **Test locally across platforms** (if possible)
+
+5. **Lint markdown**:
+   ```bash
+   # Check for common markdown issues
+   grep -r "^---" prompts/my-analysis.md  # Should be empty
+   ```
+
+### PR Checklist
+
+When submitting your PR, include:
+
+- [ ] New skill file: `plugins/us-stock-analysis/skills/my-analysis/SKILL.md`
+- [ ] Universal prompt: `prompts/my-analysis.md` (no frontmatter)
+- [ ] Registration: Updated `plugin.json`, `marketplace.json`
+- [ ] Platform sync: Updated `.cursor/`, `.github/`, `GEMINI.md`
+- [ ] Documentation: Updated all README files
+- [ ] Changelog: Added to `CHANGELOG.md`
+- [ ] Tests pass: `npm test` shows 270+ passed
+- [ ] No JSON errors: `npm run validate` passes
+- [ ] Version bumped: Both manifest files updated
+
+### Merge Criteria
+
+Your PR will be merged when:
+
+✅ All tests pass  
+✅ Platform sync complete (5/5 platforms)  
+✅ Documentation updated (all guides)  
+✅ Changelog entry added  
+✅ Version consistency verified  
+
+---
+
+## Common Patterns
+
+### Pattern 1: Valuation Skills
+
+Skills that estimate stock fair value:
+
+```markdown
+## Output Format
+
+1. **Valuation Summary** — Fair value range ($X - $Y)
+2. **Methodology** — How the range was calculated
+3. **Scenarios** — Bull/Base/Bear cases
+4. **Sensitivity Analysis** — How sensitive to key assumptions
+5. **Margin of Safety** — Discount to fair value at current price
+6. **Investment Signal Block** — BUY/HOLD/SELL recommendation
+```
+
+### Pattern 2: Quality Assessment Skills
+
+Skills that evaluate company fundamentals:
+
+```markdown
+## Scoring Framework
+
+- **Metric A**: 0-30 points
+- **Metric B**: 0-30 points
+- **Metric C**: 0-40 points
+- **Total**: 0-100 with letter grade (A/B/C/D/F)
+
+## Risk Factors
+
+[List the top risks to the investment thesis]
+```
+
+### Pattern 3: Technical/Market Monitoring Skills
+
+Skills that analyze charts, insider activity, or market signals:
+
+```markdown
+## Key Indicators
+
+1. **Indicator A** — What it means, how to interpret
+2. **Indicator B** — What it means, how to interpret
+3. **Indicator C** — What it means, how to interpret
+
+## Signal Interpretation
+
+- **Green flags**: When to be bullish
+- **Red flags**: When to be bearish
+- **Neutral**: When the signal is unclear
+```
+
+---
+
+## Troubleshooting
+
+### "npm test" fails after adding skill
+
+**Problem**: Tests fail with "skill not registered" or similar
+
+**Solution**:
+1. Verify `plugin.json` has your skill name
+2. Verify SKILL.md file exists
+3. Verify frontmatter is present in SKILL.md (not in prompts/)
+4. Run: `jq '.skills' plugins/us-stock-analysis/.claude-plugin/plugin.json | grep my-analysis`
+
+### Signal block not rendering in GitHub/Cursor
+
+**Problem**: Signal block appears broken in some platforms
+
+**Solution**:
+1. Ensure it's the last section of SKILL.md and prompts/*.md
+2. Verify box-drawing characters are UTF-8 encoded
+3. Test in raw text editor (not markdown preview)
+
+### Prompts file has frontmatter
+
+**Problem**: `prompts/my-analysis.md` starts with `---`
+
+**Solution**:
+```bash
+# Remove lines 1-3 (the YAML frontmatter)
+tail -n +4 plugins/us-stock-analysis/skills/my-analysis/SKILL.md > prompts/my-analysis.md
+```
+
+### Skill not available in Cursor/Gemini
+
+**Problem**: `@prompts/my-analysis.md` not recognized
+
+**Solution**:
+1. Verify `prompts/my-analysis.md` exists
+2. Verify added to `.cursor/rules/invest-skill.mdc`
+3. Verify added to `GEMINI.md`
+4. Restart IDE/CLI
+5. Check file permissions: `chmod 644 prompts/my-analysis.md`
+
+---
+
+## Example: Real Skill Addition
+
+See the v1.3.0 release for a real-world example:
+
+- **Stock Valuation Skill**: PR adding `/stock-valuation`
+  - Multi-method valuation (DCF, CCA, EV/EBITDA, P/E, residual income)
+  - Football field summary
+  - Risk-adjusted expected return
+  - Registered across all 5 platforms
+
+Review the commit to see all the changes needed:
+
+```bash
+git log --oneline | grep "stock-valuation"
+# Find the commit and run: git show <commit-hash>
+```
+
+---
+
+## Support
+
+Need help?
+
+- 📖 [Check PLATFORM-COMPATIBILITY.md](PLATFORM-COMPATIBILITY.md) for platform-specific details
+- 💬 [Open a GitHub Discussion](https://github.com/yennanliu/InvestSkill/discussions)
+- 🐛 [File an issue](https://github.com/yennanliu/InvestSkill/issues)
+
+---
+
+**Last Updated**: 2026-07-05  
+**Total Skills**: 27 skill directories (26 advertised frameworks + `report-generator` output tool)  
+**Next Review**: When adding new skill