Comprehensive Finance Consultant Agent Skill

SKILL.md — Finance Consultant Skill Registry

> The canonical registry and contract documentation for the Finance Consultant skill. > This file describes how skills/agents/tools/hooks are registered, resolved, > executed, and validated, including input/output JSON schemas.

---

1. Identity

| Field | Value | | --- | --- | | Skill name | finance-consultant | | Version | 1.1.0 | | Language | TypeScript (ESM, Node.js >= 18) | | Runtime dependencies | zod only |\n| Research grounding | 29 applied papers (RESEARCH-PAPER-KNOWLEDGE-BRAIN.md) | | Entry point | dist/registry/index.js (buildSkill) | | LLM provider | OpenAI-compatible (provider-agnostic with failover) |

2. Architecture summary

A modular skill-registry pattern with a chain-of-thought router orchestrating specialized sub-advisor agents over a deterministic financial tool layer, all wired together by an execution engine and instrumented with a hook lifecycle.

ConsultationRequest
      |
  ConsultationEngine ──(hooks)──> HookRegistry / EventEmitter
      |
  Orchestrator (router: CoT-LLM → keyword fallback)
      |  selects 1..6 advisor categories
  Sub-Advisors (6)
   |  each: compute deterministic baseline metrics (tools)
   |  each: LLM call (JSON mode) → parse → validate → graceful fallback
  Orchestrator.aggregate (prioritize, headline, disclaimers)
      |
  FinanceConsultation (Zod-validated)

See assets/system-architecture.md for the full diagram and module map.

3. Registration

3.1 Agents (SkillAgentRegistry)

Agents register via SkillAgentRegistry.register(agent) or registerAll([...]). There is exactly one orchestrator and six advisors.

| Agent id | Kind | Category | Allowed tools | | --- | --- | --- | --- | | orchestrator | orchestrator | — | — (routing only) | | budget-cashflow-advisor | advisor | budget-cashflow | cashflow-analyzer, budget-allocation, net-worth-calculator | | debt-management-advisor | advisor | debt-management | debt-payoff-strategist, amortization-calculator, payoff-time-estimator | | investing-advisor | advisor | investing | asset-allocation-recommender, compound-interest-calculator, net-worth-calculator | | retirement-tax-advisor | advisor | retirement-tax | retirement-projection, tax-estimator, compound-interest-calculator | | insurance-risk-advisor | advisor | insurance-risk | insurance-coverage-evaluator, net-worth-calculator | | goal-planning-advisor | advisor | goal-planning | savings-goal-projection, emergency-fund-calculator, compound-interest-calculator |

Registry self-check (agents.validate()) enforces: exactly one orchestrator, all six categories covered, no duplicate ids, advisor ids match the category→id map.

3.2 Tools (ToolRegistry)

13 financial tools. Each declares inputSchema/outputSchema (JSON Schema) and a category. Tools are deterministic and cacheable. Execution validates input and output against the schemas; invalid outputs are rejected as execution errors.

| Tool | Category | Description | | --- | --- | --- | | net-worth-calculator | balance-sheet | assets, liabilities, net worth, liquid net worth | | cashflow-analyzer | budget-cashflow | monthly income, expenses, net cash flow, savings rate | | emergency-fund-calculator | savings | months covered, shortfall, status | | debt-payoff-strategist | debt-management | snowball vs avalanche simulation | | amortization-calculator | debt-management | payment, schedule, total interest | | payoff-time-estimator | debt-management | single-balance time + interest | | compound-interest-calculator | investing | FV of PV + contributions | | retirement-projection | retirement-tax | nest egg + safe-withdrawal income | | savings-goal-projection | goal-planning | on-track + required contribution | | asset-allocation-recommender | investing | stocks/bonds/cash/alts by risk | | tax-estimator | retirement-tax | simplified bracket estimate | | insurance-coverage-evaluator | insurance-risk | coverage gaps | | budget-allocation | budget-cashflow | 50/30/20 split |

3.3 Hooks (HookRegistry)

Lifecycle hooks fire at well-defined stages. Built-ins: audit log, metrics, state sync, and typed event emission. Any failure is isolated and reported to error hooks without aborting the consultation.

Stages: consultation.before, consultation.after, router.before, router.after, advisor.before, advisor.after, tool.before, tool.after, llm.before, llm.after, context.compressed, error.

4. Resolution & execution

1. Host calls buildSkill(opts) → composition root wires runtime + tools + hooks +

agents + engine and runs agents.validate().

1. Host calls skill.consult(ConsultationRequest) → ConsultationEngine.
2. Engine fires consultation.before, then orchestrator.route(...):

• explicit focusAreas → used directly (confidence 1.0)
• else CoT LLM routing (constrained to the 6 categories, JSON)
• else deterministic keyword heuristic

1. Engine resolves each selected category to its advisor and runs them

(sequential, or bounded-parallel via enableSubAdvisorParallelism).

1. Each advisor (runAdvisor):

• computes deterministic baseline metrics via allowed tools,
• builds its system prompt with profile summary + metrics,
• context-budgets the messages through ContextManager,
• calls the LLM in JSON mode, parses + normalizes,
• on any failure, synthesizes a deterministic fallback AdvisorOutput,
• force-merges validated metrics so numbers are never hallucinated,
• validates the final output against AdvisorOutputSchema.

1. orchestrator.aggregate(...) produces a prioritized FinanceConsultation,

validated against FinanceConsultationSchema.

1. Engine fires consultation.after.

5. Input / output JSON schemas

5.1 Input — ConsultationRequest

{
  "query": "string (required, minLength 1)",
  "profile": "FinancialProfile (required)",
  "focusAreas": ["budget-cashflow" | "debt-management" | "investing" | "retirement-tax" | "insurance-risk" | "goal-planning"] // optional
}

Full schema: assets/schemas/consultation-request.schema.json and financial-profile.schema.json.

5.2 Output — FinanceConsultation

{
  "headlineSummary": "string",
  "riskToleranceAssessed": "conservative" | "moderate" | "aggressive",
  "advisorOutputs": [
    {
      "advisorId": "string",
      "category": "",
      "summary": "string",
      "findings": ["string"],
      "recommendations": [
        { "title": "string", "rationale": "string", "action": "string",
          "priority": "low|medium|high", "estimatedImpact": "string?",
          "references": ["string"] }
      ],
      "metrics": { "": "string|number|boolean" },
      "confidence": 0..1,
      "fallbackUsed": boolean,
      "citations": [ /* CitationRef: {key,authors,year,title,venue,finding} */ ]
    }
  ],
  "prioritizedRecommendations": [ /* Recommendation */ ],
  "nextSteps": ["string"],
  "disclaimers": ["string"],
  "citations": [ /* aggregated CitationRef, deduplicated */ ]
}

Full schema: assets/schemas/consultation.schema.json.

5.3 Tool I/O

Every tool exposes inputSchema and outputSchema (JSON Schema, draft-07 subset). Inspect at runtime via skill.tools.listSchemas(). Validation is enforced by validateAgainstSchema on both input and output of every execution.

6. Configuration & feature flags

Type-safe config via Zod (src/config/schema.ts). Resolved from defaults + env overrides (src/config/env.ts) or an explicit override document.

| Env var | Default | Effect | | --- | --- | --- | | LOG_LEVEL | info | log severity | | LLM_MODEL | gpt-4o-mini | primary model | | LLM_BASE_URL | OpenAI | provider endpoint | | LLM_TEMPERATURE / LLM_MAX_TOKENS / LLM_TIMEOUT_MS / LLM_MAX_RETRIES | 0.2 / 2048 / 30000 / 3 | sampling/retry | | FC_SOFT_TOKEN_BUDGET / FC_HARD_TOKEN_BUDGET / FC_RESERVED_OUTPUT_TOKENS | 6000 / 8000 / 1024 | context policy | | FC_ENABLE_COT_ROUTING | true | chain-of-thought router | | FC_ENABLE_PARALLELISM | false | parallel sub-advisors | | FC_ENABLE_TOOL_CACHE | true | tool result caching | | FC_ENABLE_CONTEXT_COMPRESSION | true | history compression | | FC_ENABLE_RAG | true | reference grounding flag | | FC_ENABLE_FALLBACK | true | graceful degradation |

Config JSON: config/default.config.json; schema: config/config.schema.json; flags: config/feature-flags.json; example env: .env.example.

7. Production-grade guarantees

• No placeholders: every function is fully implemented (no TODOs/stubs).
• Type-safe: strict TypeScript; Zod config + domain validation; JSON-Schema tool I/O.
• Graceful degradation: router, advisors, and aggregation all have deterministic

fallbacks — a schema-valid consultation is always returned, even with no LLM.

• Context management: ContextManager budgets every LLM call to hard token limits

with configurable compression strategies.

• Provider failover: retry + exponential backoff + ordered endpoint failover.
• Structured logging: newline-delimited JSON logs via Logger (pretty mode in dev).
• Hooks: isolated hook execution; failures never abort the consultation.
• Deterministic numbers: metrics computed by validated tools and force-merged

into outputs, so the LLM never invents financial figures.

8. Programmatic usage

import { buildSkill } from "finance-consultant-skill";

const skill = buildSkill();

const consultation = await skill.consult({
  query: "Balance paying off debt, saving for a house, and retirement.",
  profile: { /* FinancialProfile */ },
  focusAreas: ["debt-management", "goal-planning"],
});

console.log(consultation.headlineSummary);

CLI scripts:

• npm run setup — install, typecheck, build, validate.
• npm run build — compile to dist/.
• npm run typecheck — strict noEmit check.
• npm run validate / npm test — offline self-validation suite.
• npm run demo — end-to-end demo (uses fallback when no API key).
• npm run seed — write sample profiles to assets/seed/.
• npm run clean — remove build artifacts.

9. Extension points

• New tool: implement ToolDefinition, register via skill.tools.register(tool).
• New advisor: implement AdvisorAgent (id must equal ${category}-advisor),

register via skill.agents.register(advisor); the registry self-check covers it.

• Custom hook: skill.hooks.register(stage, id, handler, priority).
• Custom LLM transport: implement LlmTransport, pass via buildSkill({ llmTransport }).
• State persistence: pass a stateSink to buildSkill to snapshot session state.

11. Research grounding

Recommendations are evidence-backed. RESEARCH-PAPER-KNOWLEDGE-BRAIN.md lists 29 curated scientific papers (life-cycle theory, portfolio theory, retirement withdrawal, behavioral finance, savings defaults, financial literacy, household finance, insurance/risk). The machine-readable mirror is src/research/citations.ts.

• Advisor system prompts list the relevant citation: keys per specialty.
• Recommendations include citation: in their references array.
• The orchestrator resolves and dedupes these into a citations block on every

consultation (and per advisor output), each entry carrying authors, year, title, venue, and finding.

• The 4% rule, emergency-fund ordering, allocation-by-risk, and "automate it"

defaults each trace to specific papers (Bengen 1994; Carroll 1997; Markowitz 1952; Madrian & Shea 2001; Chetty et al. 2014).

Integrity: citations are recalled from training; verify against primary sources before academic/regulatory use.

12. RAG grounding layer

When enableRagGrounding is on, a dependency-free offline retriever (src/rag) indexes references/domain/*.md and injects the top-k snippets relevant to each advisor's query+category into that advisor's system prompt. The RagProvider interface is pluggable (LocalMarkdownRagProvider, NoopRagProvider); inject a custom one via buildSkill({ rag }).

13. Pluggable tax-jurisdiction providers

Tax estimation is pluggable via src/tax (TaxProviderRegistry). Built-in: us-federal (default), flat-10, uk-income (all illustrative). The tax-estimator tool accepts an optional jurisdiction and delegates to the registry. Set the default via config tax.defaultJurisdiction (env FC_TAX_JURISDICTION), or register your own provider.

14. Session persistence

src/persistence provides MemorySessionStore (default), FileSystemSessionStore (JSON files, zero deps), and SqliteSessionStore (real CRUD via Node 22+ node:sqlite, with a clear capability error otherwise). The engine saves state and resumes by sessionId; expose Skill.loadSession(id) / Skill.listSessions(). Enable via buildSkill({ store }) or buildSkill({ enablePersistence: true }).

15. Diagnostics & health check

node scripts/diagnostics.js          # human-readable
node scripts/diagnostics.js --json   # machine-readable

Reports skill/agent/tool/hook/research/context/LLM health without network access.

16. Disclaimers

Outputs are informational and educational only — not personalized financial, tax, or legal advice. Projections are estimates based on stated assumptions. Consult a licensed professional before acting.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dungnotnull
• Source: dungnotnull/comprehensive-finance-consultant-agent-skill
• License: MIT

Install and usage instructions live in the source repository linked above.