us-stock-analyzer

intent

analyze any us-listed stock end-to-end using finskills api data (real-time quotes, fundamentals, analyst consensus, earnings history). delivers a structured investment report covering business quality, financial health, valuation, analyst sentiment, and key risks in a single turn. use this when a user asks to "analyze", "research", "evaluate", or "deep dive" a specific ticker, requests a buy/sell/hold verdict, or wants fundamental analysis.

inputs

external connection: finskills api

• endpoint: https://finskills.net/v1/
• auth: X-API-Key header with value from FINSKILLS_API_KEY env var
• setup: register free at https://finskills.net. pro plan required for full historical data, financials, and batch quotes. free tier supports single-stock real-time quotes and profile lookups
• rate limits: check response headers for X-RateLimit-Remaining and X-RateLimit-Reset. free tier allows 100 requests/day. pro tier 10,000/day
• auth expiry: api keys do not expire but may be revoked. if 401 response, regenerate key at https://finskills.net/account/api-keys

user inputs (required before starting):

• ticker symbol (e.g., AAPL, NVDA, MSFT). ask user if not provided
• analysis depth (optional, defaults to standard): quick (level 1, quote + profile only), standard (level 2, all endpoints except holders), deep (level 3, all endpoints including institutional holders and 5-year financials)
• investment horizon (optional, defaults to long-term): short-term (less than 3 months), medium (3 to 12 months), long-term (more than 12 months)

context required:

• current date/time for calculating trailing-twelve-month (ttm) periods and age of financial statements
• user's risk tolerance (optional, inferred from conversation or default to neutral)

procedure

step 1: validate inputs and resolve missing data

input: ticker symbol, analysis depth, investment horizon
process:

• if ticker not provided, ask user to provide it. validate format (1-5 uppercase letters, optional dot for nyse listings)
• if analysis depth not specified, default to standard (level 2)
• if investment horizon not specified, default to long-term
• confirm finskills api key is set in environment. if not found, halt with error message and direct user to setup instructions

output: ticker (normalized), analysis_depth, investment_horizon, api_key_status (confirmed or error)

step 2: fetch real-time quote data (all levels)

input: ticker symbol, finskills api key
api call:

GET https://finskills.net/v1/stocks/quote/{TICKER}
X-API-Key: {FINSKILLS_API_KEY}

extract fields:

• price, change, changePercent, volume, marketCap, week52High, week52Low, avgVolume
• if response code 404, ticker does not exist or is delisted. halt analysis
• if response code 401, api key invalid or expired. halt and direct to regenerate key
• if response code 429, rate limit exceeded. retry with exponential backoff (max 3 retries, starting 2 seconds)
• if response code 5xx, finskills api down. halt and inform user to retry later
• if response time exceeds 10 seconds, timeout. retry once, then proceed with cached data if available

output: quote_data (dict), data_age (seconds since last update), source_timestamp

step 3: fetch company profile (all levels)

input: ticker symbol, finskills api key
api call:

GET https://finskills.net/v1/stocks/profile/{TICKER}
X-API-Key: {FINSKILLS_API_KEY}

extract fields:

• name, sector, industry, description, employees, website, country, exchange, ceo, founded_year
• if any field missing (null), note "data unavailable" for that field in final report

output: profile_data (dict), data_age (seconds since last update)

step 4: fetch financial statements (standard and deep levels only)

input: ticker symbol, finskills api key, analysis depth
api call:

GET https://finskills.net/v1/stocks/financials/{TICKER}?periods=5
X-API-Key: {FINSKILLS_API_KEY}

extract fields (most recent period and ttm where applicable):

from income statement: revenue, grossProfit, operatingIncome, netIncome, eps, interestExpense
from balance sheet: totalDebt, cashAndEquivalents, currentAssets, currentLiabilities, totalAssets, totalEquity, inventory, accounts_receivable
from cash flow: operatingCashFlow, freeCashFlow (= operatingCashFlow - capitalExpenditures), capitalExpenditures

• if financials are null or empty, flag "financial data stale or unavailable" and note most recent period available
• if financial statements are more than 90 days old, note "⚠️ financial data may be stale (sec filing lag)"
• calculate ebitda = operatingIncome + depreciation + amortization (if depreciation/amortization not provided in api, estimate as (operatingIncome - netIncome) * 0.3)

output: financials_data (dict with 5-year history), most_recent_period, data_age

step 5: fetch analyst recommendations (standard and deep levels only)

input: ticker symbol, finskills api key, analysis depth
api call:

GET https://finskills.net/v1/stocks/recommendations/{TICKER}
X-API-Key: {FINSKILLS_API_KEY}

extract fields:

• strongBuy, buy, hold, sell, strongSell counts
• consensus_rating (string: strong buy, buy, hold, underperform, sell)
• mean_target_price, target_price_high, target_price_low
• number_of_analysts
• if no analysts covering stock, note "minimal analyst coverage"
• if target price is null, set to current price and note "no price target"

output: recommendations_data (dict), analyst_count, consensus_label

step 6: fetch earnings history and estimates (standard and deep levels only)

input: ticker symbol, finskills api key, analysis depth
api call:

GET https://finskills.net/v1/stocks/earnings/{TICKER}
X-API-Key: {FINSKILLS_API_KEY}

extract fields:

• last 4 quarters of eps_actual, eps_estimate, beat/miss flag (beat if actual > estimate)
• next quarter eps_estimate, next quarter revenue_estimate
• if earnings estimates are null or older than 30 days, flag "estimates may be stale"
• calculate beat_rate = (number of beats / 4) * 100
• calculate average_surprise = mean(eps_actual - eps_estimate) / eps_estimate * 100

output: earnings_data (dict), beat_rate (%), average_surprise (%), beat_count

step 7: fetch institutional holders (deep level only)

input: ticker symbol, finskills api key
api call:

GET https://finskills.net/v1/stocks/holders/{TICKER}
X-API-Key: {FINSKILLS_API_KEY}

extract fields:

• top 5 holders (name, shares, %)
• total_institutional_ownership_pct
• if holders data is null or not provided, note "holders data unavailable"

output: holders_data (dict or null)

step 8: compute business quality score (all levels)

input: profile_data, financials_data, earnings_data
process:

score each dimension 1-5 (1 = weak, 5 = excellent):

competitive moat: look for market leadership, pricing power, switching costs, network effects, brand strength. sources: industry description, revenue stability, margin trends

• score 5 if: market leader, pricing power evident, high switching costs, recurring revenue > 70%
• score 4 if: strong position, some pricing power, moderate switching costs
• score 3 if: competitive but differentiated, moderate margins, mixed signals
• score 2 if: undifferentiated, price-taker, low switching costs
• score 1 if: declining market share, commoditized, weak competitive position

management quality: look for capital allocation discipline, fcf conversion, debt management, eps growth vs revenue growth disconnect

• score 5 if: fcf conversion > 90%, fcf margin > 15%, debt declining, eps growth aligned with revenue
• score 4 if: fcf conversion > 75%, fcf margin > 10%, stable debt, aligned growth
• score 3 if: fcf conversion > 60%, fcf margin > 5%, moderate debt growth, slightly diverged growth
• score 2 if: fcf conversion < 60%, fcf margin < 5%, rising debt, significant divergence
• score 1 if: negative fcf, extreme leverage, eps inflation disconnect, poor capital allocation

revenue quality: recurring/subscription (high quality) vs one-time (low quality), customer concentration risk

• score 5 if: recurring revenue > 80%, no single customer > 10%
• score 4 if: recurring revenue > 60%, no single customer > 15%
• score 3 if: recurring revenue > 40%, no single customer > 20%
• score 2 if: recurring revenue < 40%, customer concentration > 25%
• score 1 if: mostly one-time revenue, single customer > 30%

growth trajectory: yoy revenue growth trend over 3 years (accelerating, stable, or decelerating)

• score 5 if: growth > 20% and accelerating
• score 4 if: growth 10-20% and stable or accelerating
• score 3 if: growth 5-10% and stable
• score 2 if: growth declining (e.g., 15% slowing to 8%)
• score 1 if: growth negative or approaching zero

calculation: bqs = (moat + management + revenue_quality + growth) / 4, rounded to 1 decimal

output: bqs (float, 1.0-5.0), component_scores (dict), rationale_per_dimension (string)

step 9: compute financial health metrics (standard and deep levels only)

input: financials_data (most recent period and prior year)
process:

calculate each metric. flag with ⚠️ if outside healthy benchmark:

metric	formula	benchmark	flag if
gross margin	(grossProfit / revenue) * 100	industry avg (typically 35-50%)	below 20% or declining 5+ pts yoy
operating margin	(operatingIncome / revenue) * 100	> 15%	below 5% or negative
fcf margin	(freeCashFlow / revenue) * 100	> 10% excellent	below 2%
net debt / ebitda	(totalDebt - cashAndEquivalents) / ebitda	< 2.0x	> 3.0x
roe	(netIncome / totalEquity) * 100	> 15%	< 5% or negative
fcf yield	(freeCashFlow / marketCap) * 100	> 4% attractive	< 1% or negative
current ratio	currentAssets / currentLiabilities	> 1.5	< 1.0 (potential solvency risk)
interest coverage	operatingIncome / interestExpense	> 3.0x	< 1.5x (debt service stress)

• if any required field is null, note "insufficient data to compute" for that metric
• compare yoy change for each metric. flag accelerating deterioration (e.g., margin down 3+ points yoy)

output: metrics_dict (all calculations), flags_list (array of ⚠️ items)

step 10: perform valuation analysis (standard and deep levels only)

input: quote_data, financials_data, earnings_data, analyst data
process:

calculate trailing multiples:

• p/e (ttm) = price / eps_ttm. note vs sector average if available in api response
• forward p/e = price / eps_next_year_estimate. compare to stock's 5-year historical avg if available
• ev/ebitda = (marketCap + netDebt) / ebitda. classify: < 10x = deep value, 10-15x = fair value, 15-20x = premium, > 20x = stretched
• p/fcf = marketCap / freeCashFlow. compare to growth peers
• peg_ratio = (p/e_forward / eps_3yr_growth_rate). classify: < 1.0 = undervalued, 1.0-1.5 = fair, > 1.5 = overvalued. if 3yr growth not available, note "growth data unavailable"

valuation assessment: synthesize multiples into one label: deep value / fair value / premium / stretched

fair value estimate (two methods):

method 1 (fcf yield): assume fcf yield should be 4-6% for quality business. fair_value_fcf = freeCashFlow / 0.05 (using 5% midpoint). range: 0.04 (bull) to 0.06 (bear)

method 2 (p/e reversion): if stock p/e is above sector median, estimate fair value as: fair_value_pe = sector_median_pe * eps_ttm. if sector data unavailable, use stock's 5-year avg p/e

output: fair_value_low (lower of two methods), fair_value_high (higher of two methods), valuation_label, multiples_dict

step 11: analyze earnings quality and analyst consensus (standard and deep levels only)

input: earnings_data, recommendations_data
process:

earnings quality:

• beat_rate: % of last 4 quarters beating eps estimates. > 50% is good, < 25% is poor
• average_surprise: positive indicates consistent beats, negative indicates consistent misses
• revenue vs eps divergence: if revenue growing but eps flat/negative, flag "accounting risk"
• earnings volatility: calculate std dev of last 4 quarter eps. if std_dev / mean_eps > 30%, note "highly volatile earnings"

analyst consensus:

• extract consensus_rating label
• implied upside = (mean_target_price - current_price) / current_price * 100. positive = bullish, negative = bearish
• analyst breadth: < 5 analysts = low credibility, 5-15 = moderate, > 15 = high coverage
• target range spread = (target_high - target_low) / mean_target * 100. > 30% = wide disagreement among analysts

output: beat_rate (%), avg_surprise (%), divergence_flag (bool), consensus_label (string), upside_pct (float), analyst_breadth (int), target_spread (%)

step 12: identify key risks (all levels)

input: profile_data, financials_data, earnings_data, recommendations_data, valuation_analysis
process:

systematically scan for risk categories. output 3-5 risks ranked by severity:

balance sheet risk:

• leverage: if net_debt_to_ebitda > 3.0x or rising, flag "high leverage"
• liquidity: if current_ratio < 1.0 or cash declining, flag "liquidity risk"
• debt maturity: if due within 12 months > 25% of total debt, flag "refinancing risk"

earnings risk:

• customer concentration: if top customer > 30% of revenue (from profile or earnings notes), flag "customer concentration"
• margin pressure: if operating margin declining > 3 pts yoy, flag "margin compression"
• cyclicality: if industry description mentions cyclical, flag "cyclical revenue exposure"
• estimate cuts: if recent quarters miss estimates, flag "earnings risk"

macro risk:

• interest rate sensitivity: if high debt and rising rate environment, flag "rate sensitivity"
• commodity exposure: if industry = mining, energy, agriculture, flag "commodity price exposure"
• fx exposure: if international revenue > 30%, flag "fx exposure"

regulatory/esg risk:

• regulatory environment: if industry = pharma, tobacco, financial services, utilities, flag "regulatory risk"
• esg concerns: if recent news mentions environmental/governance scandal, note (low priority if not in data)

valuation risk:

• multiple compression: if p/e > 25 and valuation is stretched, flag "downside if multiples compress"
• growth deceleration: if growth has declined > 5 pts yoy, flag "growth deceleration risk"

output: risks_list (array of strings, each with 1 sentence), severity_rank (high/medium/low per risk)

step 13: derive investment verdict (all levels)

input: bqs, financial_health_flags, valuation_analysis, analyst_consensus, earnings_quality, risks_list, investment_horizon
process:

rating logic (decision tree in step 14 below):

synthesize all factors into one of five ratings: strong buy / buy / hold / avoid / sell

12-month price target (base case):

derive from valuation_analysis. use midpoint of fair_value_range, adjusted for analyst mean target if analyst coverage is moderate or high (> 5 analysts). base_target = (valuation_fair_value_mid + analyst_mean_target) / 2 if analyst coverage > 5, else use valuation_fair_value_mid

bull case (upside scenario): assume best-case growth, margin expansion, and multiple re-rating. bull_target = fair_value_high * 1.15, capped at analyst target_high if available

**