# Margin Simulation

> Simulates agency margin, delivery cost, cost-to-serve, leakage, FTE economics, vendor costs, and profitability by client, scope, campaign, or retainer. Applies Monte Carlo simulation for uncertainty quantification and leakage detection for margin erosion sources. Use when asked to evaluate P&L, margin, EBITDA impact, pricing, fee sufficiency, or commercial viability. Also trigger when someone say…

- **Type:** Skill
- **Install:** `agentstack add skill-afelipeg-anthropic-skills-for-enterprise-marketing-os-margin-simulation`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [afelipeg](https://agentstack.voostack.com/s/afelipeg)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [afelipeg](https://github.com/afelipeg)
- **Source:** https://github.com/afelipeg/Anthropic-Skills-for-enterprise-marketing-os/tree/main/skills/margin-simulation

## Install

```sh
agentstack add skill-afelipeg-anthropic-skills-for-enterprise-marketing-os-margin-simulation
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Margin Simulation

Model the full commercial viability of any agency engagement — from a single campaign to a multi-year retainer — using deterministic P&L analysis, Monte Carlo simulation for uncertainty quantification, leakage detection, sensitivity analysis, and scenario modeling.

## How This Skill Thinks

This skill does not just calculate margin. It orchestrates a pipeline:

1. **Script execution** (`scripts/margin_engine.py`): Runs the deterministic P&L, Monte Carlo simulation (5,000 draws), leakage detection, and sensitivity analysis programmatically
2. **Reference lookup** (`references/leakage_and_pricing.md`): Provides benchmark data, leakage taxonomy, pricing strategies, and the 70/30 model impact on margin
3. **Qualitative judgment** (Claude): Interprets results in context — client relationship dynamics, market positioning, competitive pressure, historical patterns — and shapes the recommendation
4. **Visual output** (Visualizer): Renders the margin dashboard as an inline widget with Monte Carlo distribution, leakage waterfall, and scenario cards

The script produces numbers. Claude produces insight. The Visualizer makes it actionable. None of these replaces the other.

## Quick Reference

| Resource | Purpose | Usage |
|----------|---------|-------|
| `scripts/margin_engine.py` | Core simulation engine — deterministic P&L + Monte Carlo (5K runs) + leakage detection + sensitivity analysis + scenario modeling | `python margin_engine.py --input config.json --output margin.json` |
| `references/leakage_and_pricing.md` | Leakage taxonomy (8 patterns, 3 severity tiers), margin benchmarks by engagement type, Monte Carlo methodology, pricing strategies, 70/30 impact analysis | Read for benchmarks and methodology explanation |

### How to Use the Script

Build a config JSON from the user's inputs, then run the engine:

```python
import sys
sys.path.insert(0, "/scripts")
from margin_engine import MarginSimulator

config = {
    "client_name": "FreshBrew Coffee",
    "engagement_type": "retainer",
    "monthly_revenue": 15000,
    "contract_months": 12,
    "margin_target": 0.30,

    "fte_costs": [
        {"name": "Creative (mid)", "monthly_amount": 1250, "seniority": "mid", "fte": 0.5},
        {"name": "Account (mid)", "monthly_amount": 560, "seniority": "mid", "fte": 0.2},
        {"name": "Data (mid)", "monthly_amount": 450, "seniority": "mid", "fte": 0.15},
    ],
    "vendor_costs": [],
    "tool_costs": [{"name": "Design tools", "monthly_amount": 150}],
    "ai_infrastructure": 500,

    # Leakage flags — True means protection exists
    "has_revision_cap": True,
    "has_pm_hours": False,
    "has_change_order": True,
    "has_client_sla": True,
    "has_vendor_caps": True,
    "has_seniority_match": True,
    "has_adhoc_cap": True,
    "has_tool_passthrough": False,
}

sim = MarginSimulator(config)
result = sim.run()
# result.margin_pct, result.monte_carlo, result.leakage_items, result.scenarios, etc.
```

If the user has already run `fte-capacity-sizing`, use those FTE costs directly — the capacity model's output feeds this simulation's input.

**Calibration note**: Monte Carlo results depend on uncertainty parameters. Default uncertainty is ±10% on FTE costs, ±15% on vendor costs. If the user provides actual variance data or historical overrun rates, use those instead. The simulation uses N=5,000 draws by default; this produces stable percentiles (±0.5pp). Numpy is preferred but the engine falls back to pure Python if unavailable.

## Trigger Conditions

Activate this skill when:

- The user asks about margin, profitability, P&L, or EBITDA for a client or scope
- The user wants to know if a fee can support the delivery cost
- The user asks "what should we charge?" or "is this fee enough?"
- The `fte-capacity-sizing` produces a cost model that needs financial validation
- The `scope-audit` identifies commercial risk and routes here
- The `agency-request-intake-router` flags a financial concern
- The user is building a proposal and needs pricing validation

## Simulation Process

Work through all eight steps. The script handles Steps 2-7 computationally; you handle Steps 1 and 8 (context gathering and recommendation framing).

### Step 1 — Capture Revenue and Cost Inputs

Gather from the user or from upstream skills:

- **Revenue**: Monthly fee, retainer amount, or project fee (÷ months)
- **FTE costs**: From `fte-capacity-sizing` output or direct input (role × rate × FTE)
- **Vendor costs**: Production, media ops, freelancers, specialized services
- **Tool costs**: SaaS subscriptions, platform licenses, API costs
- **AI infrastructure**: Claude API, MCP hosting, agent pipeline costs (default: $500/mo)
- **Contract term**: Duration in months (default: 12)
- **Margin target**: Default 30%, adjustable by user

If any cost category is missing, flag it as ⚠️ and use benchmarks from `references/leakage_and_pricing.md`.

### Step 2 — Build Deterministic P&L

Calculate the base-case margin:

```
Total delivery cost = FTE cost + Vendor cost + Tool cost + AI infra
                    + Overhead (12% of FTE + Vendor)
                    + Rework buffer (10% of FTE cost)
                    + Risk buffer (5% of FTE + Vendor)

Gross margin = Revenue - Total delivery cost
Margin % = Gross margin / Revenue × 100
OI / EBITDA impact = Gross margin × Contract months
```

### Step 3 — Detect Leakage

Check the scope for each of 8 leakage patterns. For each unprotected source, calculate the monthly cost impact and the adjusted margin. See `references/leakage_and_pricing.md` → "Leakage Taxonomy" for the full pattern catalog.

### Step 4 — Run Monte Carlo Simulation

Execute 5,000 Monte Carlo draws to model margin uncertainty. Each draw applies random perturbation to costs, plus stochastic scope creep and client delay events. The output is a margin distribution with P10/Mean/P90 range and probability of falling below target.

Read `references/leakage_and_pricing.md` → "Monte Carlo Methodology" for the full algorithm specification.

### Step 5 — Run Sensitivity Analysis

Test each cost driver with a ±20% shock to identify which driver has the largest marginal impact on margin. This answers: "Where should I negotiate?" — focus energy on the most sensitive driver.

### Step 6 — Build Scenarios

Generate 4 scenarios:
- **Base case**: Deterministic P&L as calculated
- **Optimistic**: 15% cost reduction (AI uplift, no scope creep)
- **Pessimistic**: 30% cost increase (scope creep + rework + delays)
- **With leakage**: Base cost + all detected leakage impacts

### Step 7 — Determine Verdict

Issue a commercial verdict based on margin level, Monte Carlo risk, and leakage exposure:

| Condition | Verdict |
|-----------|---------|
| Margin ≥ 40% | Highly viable |
| Margin 30-40% (target met) | Viable |
| Margin 15-30% | Tight — vulnerable to creep |
| Margin 0-15% | Underfunded — near breakeven |
| Margin  50%, flag structural risk regardless of base margin.

### Step 8 — Frame the Recommendation

This is your qualitative layer — the script produces numbers, you produce judgment:
- What should the user do about it? (Renegotiate? Reduce scope? Increase AI automation?)
- What's the client context? (New relationship worth investing in? Legacy client with history of creep?)
- What are the alternatives? (Walk away? Restructure as project-based? Phase the work?)

## Output Format

Produce the margin simulation in TWO forms: first as an **inline visual artifact** (rendered in chat via the Visualizer), then as a **structured markdown report** below it.

### Visual Artifact (Primary)

Render the margin dashboard as an inline HTML widget using the Visualizer. The widget should display:

- A **header bar** color-coded by verdict: dark green (Highly viable), green (Viable), amber (Tight), orange (Underfunded), red (Non-viable)
- A **top metrics row** with 4 cards: Monthly revenue, Total cost, Margin %, OI/EBITDA
- A **cost waterfall** — stacked horizontal bar showing FTE / Vendor / Tools / AI / Overhead / Rework / Buffer as proportional segments, labeled with $ and %
- A **Monte Carlo range** — a mini horizontal bar showing P10–Mean–P90 with probability badges:
  - P(below target) as a percentage badge
  - P(negative) as a red badge if > 5%
- A **leakage section** — each leakage source as a row with severity badge, monthly $ impact, and fix
- A **scenario comparison** — 4 cards (Base / Optimistic / Pessimistic / With leakage) each showing margin % and verdict
- An **action footer** with `sendPrompt()` buttons:
  - "Generate change order to improve margin for [client]" → `change-order-generator`
  - "Resize team to reduce cost for [client]" → `fte-capacity-sizing`
  - "Draft executive memo on commercial risk for [client]" → `executive-growth-memo`

Use CSS variables for light/dark mode. Keep it compact — a finance dashboard card.

### Markdown Report (Secondary)

After the visual artifact, produce the full simulation as markdown:

```
## 💰 MARGIN SIMULATION — [Client / Project Name]

### Executive summary
[2-3 sentences: verdict, base margin, Monte Carlo risk, top leakage source, key recommendation]

### Revenue
| Metric | Value |
|--------|-------|
| Monthly revenue | $[X] |
| Contract term | [N] months |
| Total contract value | $[X] |

### Cost structure
| Category | Monthly | % of revenue | Notes |
|----------|---------|-------------|-------|
| FTE / labor | $[X] | [Y]% | [role breakdown] |
| Vendor / third-party | $[X] | [Y]% | |
| Tools / platforms | $[X] | [Y]% | |
| AI infrastructure | $[X] | [Y]% | Claude, MCP, agents |
| Overhead (12%) | $[X] | [Y]% | |
| Rework buffer (10%) | $[X] | [Y]% | |
| Risk buffer (5%) | $[X] | [Y]% | |
| **Total delivery cost** | **$[X]** | **[Y]%** | |

### Margin
| Metric | Value |
|--------|-------|
| Gross margin | $[X]/mo |
| Margin % | [X]% |
| OI / EBITDA impact | $[X] over [N] months |
| Target margin | [X]% |
| Verdict | [verdict] |

### Monte Carlo simulation (N=5,000)
| Metric | Value |
|--------|-------|
| Mean margin | [X]% |
| Median margin | [X]% |
| P10 (pessimistic) | [X]% |
| P90 (optimistic) | [X]% |
| Std deviation | [X]pp |
| P(below target) | [X]% |
| P(negative) | [X]% |

### Leakage analysis
| Source | Severity | Monthly impact | Fix |
|--------|----------|---------------|-----|
[One row per leakage source]
| **Total leakage** | | **$[X]/mo** | |
| **Adjusted margin** | | **[X]%** | |

### Sensitivity analysis
| Cost driver | Base value | +20% shock | Margin impact |
|------------|-----------|------------|---------------|
[Ranked by absolute impact]

### Scenario comparison
| Scenario | Cost | Margin | Verdict |
|----------|------|--------|---------|
[4 scenarios]

### Recommendations
[Numbered list of specific actions based on verdict, Monte Carlo, leakage, and sensitivity]
```

### When Information Is Incomplete

If the user provides only partial cost data:
- Use benchmarks from `references/leakage_and_pricing.md` for missing categories
- If FTE costs are unknown, suggest running `fte-capacity-sizing` first
- Flag estimated values with `⚠️ Estimated`
- Run the simulation with available data and note confidence level

## Examples

**Example 1 — Viable retainer:**

User: "FreshBrew pays $15K/month. Our team costs $4K/month (from capacity model). No vendor costs. Tools are $300/month. Is this viable?"

→ Total cost: ~$5,800/mo. Margin: 61%. Monte Carlo P10: 48%. Verdict: Highly viable. No leakage if revision cap and CO mechanism are in place.

**Example 2 — Thin margin with leakage:**

User: "Client pays $25K/month. FTE cost is $14K, vendors $3K, tools $1K. No revision caps, no change order process, no client approval SLA."

→ Base margin: 18% (Tight). 3 leakage sources add $4.5K/mo. Adjusted margin: 0.2%. Monte Carlo P(negative): 35%. Verdict: Underfunded. Recommendation: fix leakage sources first — that alone recovers 18pp of margin.

**Example 3 — Non-viable project:**

User: "We quoted $50K for a 3-month project. Team cost is $22K/month including senior strategist and creative director."

→ Revenue: $16.7K/mo. Cost: $28K/mo. Margin: -68%. Verdict: Non-viable. Fee would need to be $105K+ to hit 30% margin, or scope must be cut by 60%.

## Skill Chaining

| Condition | Next skill |
|-----------|-----------|
| Need FTE cost inputs | `fte-capacity-sizing` (upstream) |
| Leakage requires scope fix | `scope-audit` or `change-order-generator` |
| Need to reduce headcount to improve margin | `fte-capacity-sizing` (resize) |
| Leadership needs commercial risk summary | `executive-growth-memo` |
| Margin approved, campaign ready | `campaign-launch-qa` |

## Source & license

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

- **Author:** [afelipeg](https://github.com/afelipeg)
- **Source:** [afelipeg/Anthropic-Skills-for-enterprise-marketing-os](https://github.com/afelipeg/Anthropic-Skills-for-enterprise-marketing-os)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-afelipeg-anthropic-skills-for-enterprise-marketing-os-margin-simulation
- Seller: https://agentstack.voostack.com/s/afelipeg
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.