@ivannxbt/ai-config 0.1.0

package/.agents/skills/marketing-psychology/SKILL.md

@@ -0,0 +1,455 @@
+---
+name: marketing-psychology
+description: "When the user wants to apply psychological principles, mental models, or behavioral science to marketing. Also use when the user mentions 'psychology,' 'mental models,' 'cognitive bias,' 'persuasion,' 'behavioral science,' 'why people buy,' 'decision-making,' or 'consumer behavior.' This skill provides 70+ mental models organized for marketing application."
+metadata:
+  version: 1.1.0
+---
+
+# Marketing Psychology & Mental Models
+
+You are an expert in applying psychological principles and mental models to marketing. Your goal is to help users understand why people buy, how to influence behavior ethically, and how to make better marketing decisions.
+
+## How to Use This Skill
+
+**Check for product marketing context first:**
+If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.md` in older setups), read it before applying mental models. Use that context to tailor recommendations to the specific product and audience.
+
+Mental models are thinking tools that help you make better decisions, understand customer behavior, and create more effective marketing. When helping users:
+
+1. Identify which mental models apply to their situation
+2. Explain the psychology behind the model
+3. Provide specific marketing applications
+4. Suggest how to implement ethically
+
+---
+
+## Foundational Thinking Models
+
+These models sharpen your strategy and help you solve the right problems.
+
+### First Principles
+Break problems down to basic truths and build solutions from there. Instead of copying competitors, ask "why" repeatedly to find root causes. Use the 5 Whys technique to tunnel down to what really matters.
+
+**Marketing application**: Don't assume you need content marketing because competitors do. Ask why you need it, what problem it solves, and whether there's a better solution.
+
+### Jobs to Be Done
+People don't buy products—they "hire" them to get a job done. Focus on the outcome customers want, not features.
+
+**Marketing application**: A drill buyer doesn't want a drill—they want a hole. Frame your product around the job it accomplishes, not its specifications.
+
+### Circle of Competence
+Know what you're good at and stay within it. Venture outside only with proper learning or expert help.
+
+**Marketing application**: Don't chase every channel. Double down where you have genuine expertise and competitive advantage.
+
+### Inversion
+Instead of asking "How do I succeed?", ask "What would guarantee failure?" Then avoid those things.
+
+**Marketing application**: List everything that would make your campaign fail—confusing messaging, wrong audience, slow landing page—then systematically prevent each.
+
+### Occam's Razor
+The simplest explanation is usually correct. Avoid overcomplicating strategies or attributing results to complex causes when simple ones suffice.
+
+**Marketing application**: If conversions dropped, check the obvious first (broken form, page speed) before assuming complex attribution issues.
+
+### Pareto Principle (80/20 Rule)
+Roughly 80% of results come from 20% of efforts. Identify and focus on the vital few.
+
+**Marketing application**: Find the 20% of channels, customers, or content driving 80% of results. Cut or reduce the rest.
+
+### Local vs. Global Optima
+A local optimum is the best solution nearby, but a global optimum is the best overall. Don't get stuck optimizing the wrong thing.
+
+**Marketing application**: Optimizing email subject lines (local) won't help if email isn't the right channel (global). Zoom out before zooming in.
+
+### Theory of Constraints
+Every system has one bottleneck limiting throughput. Find and fix that constraint before optimizing elsewhere.
+
+**Marketing application**: If your funnel converts well but traffic is low, more conversion optimization won't help. Fix the traffic bottleneck first.
+
+### Opportunity Cost
+Every choice has a cost—what you give up by not choosing alternatives. Consider what you're saying no to.
+
+**Marketing application**: Time spent on a low-ROI channel is time not spent on high-ROI activities. Always compare against alternatives.
+
+### Law of Diminishing Returns
+After a point, additional investment yields progressively smaller gains.
+
+**Marketing application**: The 10th blog post won't have the same impact as the first. Know when to diversify rather than double down.
+
+### Second-Order Thinking
+Consider not just immediate effects, but the effects of those effects.
+
+**Marketing application**: A flash sale boosts revenue (first order) but may train customers to wait for discounts (second order).
+
+### Map ≠ Territory
+Models and data represent reality but aren't reality itself. Don't confuse your analytics dashboard with actual customer experience.
+
+**Marketing application**: Your customer persona is a useful model, but real customers are more complex. Stay in touch with actual users.
+
+### Probabilistic Thinking
+Think in probabilities, not certainties. Estimate likelihoods and plan for multiple outcomes.
+
+**Marketing application**: Don't bet everything on one campaign. Spread risk and plan for scenarios where your primary strategy underperforms.
+
+### Barbell Strategy
+Combine extreme safety with small high-risk/high-reward bets. Avoid the mediocre middle.
+
+**Marketing application**: Put 80% of budget into proven channels, 20% into experimental bets. Avoid moderate-risk, moderate-reward middle.
+
+---
+
+## Understanding Buyers & Human Psychology
+
+These models explain how customers think, decide, and behave.
+
+### Fundamental Attribution Error
+People attribute others' behavior to character, not circumstances. "They didn't buy because they're not serious" vs. "The checkout was confusing."
+
+**Marketing application**: When customers don't convert, examine your process before blaming them. The problem is usually situational, not personal.
+
+### Mere Exposure Effect
+People prefer things they've seen before. Familiarity breeds liking.
+
+**Marketing application**: Consistent brand presence builds preference over time. Repetition across channels creates comfort and trust.
+
+### Availability Heuristic
+People judge likelihood by how easily examples come to mind. Recent or vivid events seem more common.
+
+**Marketing application**: Case studies and testimonials make success feel more achievable. Make positive outcomes easy to imagine.
+
+### Confirmation Bias
+People seek information confirming existing beliefs and ignore contradictory evidence.
+
+**Marketing application**: Understand what your audience already believes and align messaging accordingly. Fighting beliefs head-on rarely works.
+
+### The Lindy Effect
+The longer something has survived, the longer it's likely to continue. Old ideas often outlast new ones.
+
+**Marketing application**: Proven marketing principles (clear value props, social proof) outlast trendy tactics. Don't abandon fundamentals for fads.
+
+### Mimetic Desire
+People want things because others want them. Desire is socially contagious.
+
+**Marketing application**: Show that desirable people want your product. Waitlists, exclusivity, and social proof trigger mimetic desire.
+
+### Sunk Cost Fallacy
+People continue investing in something because of past investment, even when it's no longer rational.
+
+**Marketing application**: Know when to kill underperforming campaigns. Past spend shouldn't justify future spend if results aren't there.
+
+### Endowment Effect
+People value things more once they own them.
+
+**Marketing application**: Free trials, samples, and freemium models let customers "own" the product, making them reluctant to give it up.
+
+### IKEA Effect
+People value things more when they've put effort into creating them.
+
+**Marketing application**: Let customers customize, configure, or build something. Their investment increases perceived value and commitment.
+
+### Zero-Price Effect
+Free isn't just a low price—it's psychologically different. "Free" triggers irrational preference.
+
+**Marketing application**: Free tiers, free trials, and free shipping have disproportionate appeal. The jump from $1 to $0 is bigger than $2 to $1.
+
+### Hyperbolic Discounting / Present Bias
+People strongly prefer immediate rewards over future ones, even when waiting is more rational.
+
+**Marketing application**: Emphasize immediate benefits ("Start saving time today") over future ones ("You'll see ROI in 6 months").
+
+### Status-Quo Bias
+People prefer the current state of affairs. Change requires effort and feels risky.
+
+**Marketing application**: Reduce friction to switch. Make the transition feel safe and easy. "Import your data in one click."
+
+### Default Effect
+People tend to accept pre-selected options. Defaults are powerful.
+
+**Marketing application**: Pre-select the plan you want customers to choose. Opt-out beats opt-in for subscriptions (ethically applied).
+
+### Paradox of Choice
+Too many options overwhelm and paralyze. Fewer choices often lead to more decisions.
+
+**Marketing application**: Limit options. Three pricing tiers beat seven. Recommend a single "best for most" option.
+
+### Goal-Gradient Effect
+People accelerate effort as they approach a goal. Progress visualization motivates action.
+
+**Marketing application**: Show progress bars, completion percentages, and "almost there" messaging to drive completion.
+
+### Peak-End Rule
+People judge experiences by the peak (best or worst moment) and the end, not the average.
+
+**Marketing application**: Design memorable peaks (surprise upgrades, delightful moments) and strong endings (thank you pages, follow-up emails).
+
+### Zeigarnik Effect
+Unfinished tasks occupy the mind more than completed ones. Open loops create tension.
+
+**Marketing application**: "You're 80% done" creates pull to finish. Incomplete profiles, abandoned carts, and cliffhangers leverage this.
+
+### Pratfall Effect
+Competent people become more likable when they show a small flaw. Perfection is less relatable.
+
+**Marketing application**: Admitting a weakness ("We're not the cheapest, but...") can increase trust and differentiation.
+
+### Curse of Knowledge
+Once you know something, you can't imagine not knowing it. Experts struggle to explain simply.
+
+**Marketing application**: Your product seems obvious to you but confusing to newcomers. Test copy with people unfamiliar with your space.
+
+### Mental Accounting
+People treat money differently based on its source or intended use, even though money is fungible.
+
+**Marketing application**: Frame costs in favorable mental accounts. "$3/day" feels different than "$90/month" even though it's the same.
+
+### Regret Aversion
+People avoid actions that might cause regret, even if the expected outcome is positive.
+
+**Marketing application**: Address regret directly. Money-back guarantees, free trials, and "no commitment" messaging reduce regret fear.
+
+### Bandwagon Effect / Social Proof
+People follow what others are doing. Popularity signals quality and safety.
+
+**Marketing application**: Show customer counts, testimonials, logos, reviews, and "trending" indicators. Numbers create confidence.
+
+---
+
+## Influencing Behavior & Persuasion
+
+These models help you ethically influence customer decisions.
+
+### Reciprocity Principle
+People feel obligated to return favors. Give first, and people want to give back.
+
+**Marketing application**: Free content, free tools, and generous free tiers create reciprocal obligation. Give value before asking for anything.
+
+### Commitment & Consistency
+Once people commit to something, they want to stay consistent with that commitment.
+
+**Marketing application**: Get small commitments first (email signup, free trial). People who've taken one step are more likely to take the next.
+
+### Authority Bias
+People defer to experts and authority figures. Credentials and expertise create trust.
+
+**Marketing application**: Feature expert endorsements, certifications, "featured in" logos, and thought leadership content.
+
+### Liking / Similarity Bias
+People say yes to those they like and those similar to themselves.
+
+**Marketing application**: Use relatable spokespeople, founder stories, and community language. "Built by marketers for marketers" signals similarity.
+
+### Unity Principle
+Shared identity drives influence. "One of us" is powerful.
+
+**Marketing application**: Position your brand as part of the customer's tribe. Use insider language and shared values.
+
+### Scarcity / Urgency Heuristic
+Limited availability increases perceived value. Scarcity signals desirability.
+
+**Marketing application**: Limited-time offers, low-stock warnings, and exclusive access create urgency. Only use when genuine.
+
+### Foot-in-the-Door Technique
+Start with a small request, then escalate. Compliance with small requests leads to compliance with larger ones.
+
+**Marketing application**: Free trial → paid plan → annual plan → enterprise. Each step builds on the last.
+
+### Door-in-the-Face Technique
+Start with an unreasonably large request, then retreat to what you actually want. The contrast makes the second request seem reasonable.
+
+**Marketing application**: Show enterprise pricing first, then reveal the affordable starter plan. The contrast makes it feel like a deal.
+
+### Loss Aversion / Prospect Theory
+Losses feel roughly twice as painful as equivalent gains feel good. People will work harder to avoid losing than to gain.
+
+**Marketing application**: Frame in terms of what they'll lose by not acting. "Don't miss out" beats "You could gain."
+
+### Anchoring Effect
+The first number people see heavily influences subsequent judgments.
+
+**Marketing application**: Show the higher price first (original price, competitor price, enterprise tier) to anchor expectations.
+
+### Decoy Effect
+Adding a third, inferior option makes one of the original two look better.
+
+**Marketing application**: A "decoy" pricing tier that's clearly worse value makes your preferred tier look like the obvious choice.
+
+### Framing Effect
+How something is presented changes how it's perceived. Same facts, different frames.
+
+**Marketing application**: "90% success rate" vs. "10% failure rate" are identical but feel different. Frame positively.
+
+### Contrast Effect
+Things seem different depending on what they're compared to.
+
+**Marketing application**: Show the "before" state clearly. The contrast with your "after" makes improvements vivid.
+
+---
+
+## Pricing Psychology
+
+These models specifically address how people perceive and respond to prices.
+
+### Charm Pricing / Left-Digit Effect
+Prices ending in 9 seem significantly lower than the next round number. $99 feels much cheaper than $100.
+
+**Marketing application**: Use .99 or .95 endings for value-focused products. The left digit dominates perception.
+
+### Rounded-Price (Fluency) Effect
+Round numbers feel premium and are easier to process. $100 signals quality; $99 signals value.
+
+**Marketing application**: Use round prices for premium products ($500/month), charm prices for value products ($497/month).
+
+### Rule of 100
+For prices under $100, percentage discounts seem larger ("20% off"). For prices over $100, absolute discounts seem larger ("$50 off").
+
+**Marketing application**: $80 product: "20% off" beats "$16 off." $500 product: "$100 off" beats "20% off."
+
+### Price Relativity / Good-Better-Best
+People judge prices relative to options presented. A middle tier seems reasonable between cheap and expensive.
+
+**Marketing application**: Three tiers where the middle is your target. The expensive tier makes it look reasonable; the cheap tier provides an anchor.
+
+### Mental Accounting (Pricing)
+Framing the same price differently changes perception.
+
+**Marketing application**: "$1/day" feels cheaper than "$30/month." "Less than your morning coffee" reframes the expense.
+
+---
+
+## Design & Delivery Models
+
+These models help you design effective marketing systems.
+
+### Hick's Law
+Decision time increases with the number and complexity of choices. More options = slower decisions = more abandonment.
+
+**Marketing application**: Simplify choices. One clear CTA beats three. Fewer form fields beat more.
+
+### AIDA Funnel
+Attention → Interest → Desire → Action. The classic customer journey model.
+
+**Marketing application**: Structure pages and campaigns to move through each stage. Capture attention before building desire.
+
+### Rule of 7
+Prospects need roughly 7 touchpoints before converting. One ad rarely converts; sustained presence does.
+
+**Marketing application**: Build multi-touch campaigns across channels. Retargeting, email sequences, and consistent presence compound.
+
+### Nudge Theory / Choice Architecture
+Small changes in how choices are presented significantly influence decisions.
+
+**Marketing application**: Default selections, strategic ordering, and friction reduction guide behavior without restricting choice.
+
+### BJ Fogg Behavior Model
+Behavior = Motivation × Ability × Prompt. All three must be present for action.
+
+**Marketing application**: High motivation but hard to do = won't happen. Easy to do but no prompt = won't happen. Design for all three.
+
+### EAST Framework
+Make desired behaviors: Easy, Attractive, Social, Timely.
+
+**Marketing application**: Reduce friction (easy), make it appealing (attractive), show others doing it (social), ask at the right moment (timely).
+
+### COM-B Model
+Behavior requires: Capability, Opportunity, Motivation.
+
+**Marketing application**: Can they do it (capability)? Is the path clear (opportunity)? Do they want to (motivation)? Address all three.
+
+### Activation Energy
+The initial energy required to start something. High activation energy prevents action even if the task is easy overall.
+
+**Marketing application**: Reduce starting friction. Pre-fill forms, offer templates, show quick wins. Make the first step trivially easy.
+
+### North Star Metric
+One metric that best captures the value you deliver to customers. Focus creates alignment.
+
+**Marketing application**: Identify your North Star (active users, completed projects, revenue per customer) and align all efforts toward it.
+
+### The Cobra Effect
+When incentives backfire and produce the opposite of intended results.
+
+**Marketing application**: Test incentive structures. A referral bonus might attract low-quality referrals gaming the system.
+
+---
+
+## Growth & Scaling Models
+
+These models explain how marketing compounds and scales.
+
+### Feedback Loops
+Output becomes input, creating cycles. Positive loops accelerate growth; negative loops create decline.
+
+**Marketing application**: Build virtuous cycles: more users → more content → better SEO → more users. Identify and strengthen positive loops.
+
+### Compounding
+Small, consistent gains accumulate into large results over time. Early gains matter most.
+
+**Marketing application**: Consistent content, SEO, and brand building compound. Start early; benefits accumulate exponentially.
+
+### Network Effects
+A product becomes more valuable as more people use it.
+
+**Marketing application**: Design features that improve with more users: shared workspaces, integrations, marketplaces, communities.
+
+### Flywheel Effect
+Sustained effort creates momentum that eventually maintains itself. Hard to start, easy to maintain.
+
+**Marketing application**: Content → traffic → leads → customers → case studies → more content. Each element powers the next.
+
+### Switching Costs
+The price (time, money, effort, data) of changing to a competitor. High switching costs create retention.
+
+**Marketing application**: Increase switching costs ethically: integrations, data accumulation, workflow customization, team adoption.
+
+### Exploration vs. Exploitation
+Balance trying new things (exploration) with optimizing what works (exploitation).
+
+**Marketing application**: Don't abandon working channels for shiny new ones, but allocate some budget to experiments.
+
+### Critical Mass / Tipping Point
+The threshold after which growth becomes self-sustaining.
+
+**Marketing application**: Focus resources on reaching critical mass in one segment before expanding. Depth before breadth.
+
+### Survivorship Bias
+Focusing on successes while ignoring failures that aren't visible.
+
+**Marketing application**: Study failed campaigns, not just successful ones. The viral hit you're copying had 99 failures you didn't see.
+
+---
+
+## Quick Reference
+
+When facing a marketing challenge, consider:
+
+| Challenge | Relevant Models |
+|-----------|-----------------|
+| Low conversions | Hick's Law, Activation Energy, BJ Fogg, Friction |
+| Price objections | Anchoring, Framing, Mental Accounting, Loss Aversion |
+| Building trust | Authority, Social Proof, Reciprocity, Pratfall Effect |
+| Increasing urgency | Scarcity, Loss Aversion, Zeigarnik Effect |
+| Retention/churn | Endowment Effect, Switching Costs, Status-Quo Bias |
+| Growth stalling | Theory of Constraints, Local vs Global Optima, Compounding |
+| Decision paralysis | Paradox of Choice, Default Effect, Nudge Theory |
+| Onboarding | Goal-Gradient, IKEA Effect, Commitment & Consistency |
+
+---
+
+## Task-Specific Questions
+
+1. What specific behavior are you trying to influence?
+2. What does your customer believe before encountering your marketing?
+3. Where in the journey (awareness → consideration → decision) is this?
+4. What's currently preventing the desired action?
+5. Have you tested this with real customers?
+
+---
+
+## Related Skills
+
+- **page-cro**: Apply psychology to page optimization
+- **copywriting**: Write copy using psychological principles
+- **popup-cro**: Use triggers and psychology in popups
+- **pricing-page optimization**: See page-cro for pricing psychology
+- **ab-test-setup**: Test psychological hypotheses

package/.agents/skills/microsoft-foundry/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: microsoft-foundry
+description: "Use this skill to work with Microsoft Foundry (Azure AI Foundry) and tools from Foundry MCP server: deploy AI models, manage hosted agent and prompt agent (create, deploy, invoke, run, troubleshoot Foundry Agents), manage RBAC permissions and role assignments, manage quotas and capacity, create Foundry resources. USE FOR: Microsoft Foundry, AI Foundry, hosted agent, create agent, deploy agent, debug agent, invoke agent, run agent, agent chat, evaluate agent, agent monitoring, deploy model, model catalog, knowledge index, create Foundry project, new Foundry project, set up Foundry, onboard to Foundry, create Foundry resource, create AI Services, AIServices kind, register resource provider, enable Cognitive Services, setup AI Services account, create resource group for Foundry, RBAC, role assignment, quota, capacity, TPM, deployment failure, QuotaExceeded. DO NOT USE FOR: Azure Functions (use azure-functions), App Service (use azure-create-app), generic Azure resource creation (use azure-create-app)."
+license: MIT
+metadata:
+  author: Microsoft
+  version: "1.0.0"
+---
+
+# Microsoft Foundry Skill
+
+This skill helps developers work with Microsoft Foundry resources, covering model discovery and deployment, complete dev lifecycle of AI agent, evaluation workflows, and troubleshooting.
+
+## Sub-Skills
+
+> **MANDATORY: Before executing ANY workflow, you MUST read the corresponding sub-skill document.** Do not call MCP tools for a workflow without reading its skill document. This applies even if you already know the MCP tool parameters — the skill document contains required workflow steps, pre-checks, and validation logic that must be followed. This rule applies on every new user message that triggers a different workflow, even if the skill is already loaded.
+
+This skill includes specialized sub-skills for specific workflows. **Use these instead of the main skill when they match your task:**
+
+| Sub-Skill | When to Use | Reference |
+|-----------|-------------|-----------|
+| **deploy** | Containerize, build, push to ACR, create/update/start/stop/clone agent deployments | [deploy](foundry-agent/deploy/deploy.md) |
+| **invoke** | Send messages to an agent, single or multi-turn conversations | [invoke](foundry-agent/invoke/invoke.md) |
+| **troubleshoot** | View container logs, query telemetry, diagnose failures | [troubleshoot](foundry-agent/troubleshoot/troubleshoot.md) |
+| **create** | Create new hosted agent applications. Supports Microsoft Agent Framework, LangGraph, or custom frameworks in Python or C#. Downloads starter samples from foundry-samples repo. | [create](foundry-agent/create/create.md) |
+| **project/create** | Creating a new Azure AI Foundry project for hosting agents and models. Use when onboarding to Foundry or setting up new infrastructure. | [project/create/create-foundry-project.md](project/create/create-foundry-project.md) |
+| **resource/create** | Creating Azure AI Services multi-service resource (Foundry resource) using Azure CLI. Use when manually provisioning AI Services resources with granular control. | [resource/create/create-foundry-resource.md](resource/create/create-foundry-resource.md) |
+| **models/deploy-model** | Unified model deployment with intelligent routing. Handles quick preset deployments, fully customized deployments (version/SKU/capacity/RAI), and capacity discovery across regions. Routes to sub-skills: `preset` (quick deploy), `customize` (full control), `capacity` (find availability). | [models/deploy-model/SKILL.md](models/deploy-model/SKILL.md) |
+| **quota** | Managing quotas and capacity for Microsoft Foundry resources. Use when checking quota usage, troubleshooting deployment failures due to insufficient quota, requesting quota increases, or planning capacity. | [quota/quota.md](quota/quota.md) |
+| **rbac** | Managing RBAC permissions, role assignments, managed identities, and service principals for Microsoft Foundry resources. Use for access control, auditing permissions, and CI/CD setup. | [rbac/rbac.md](rbac/rbac.md) |
+
+> 💡 **Tip:** For a complete onboarding flow: `project/create` → agent workflows (`deploy` → `invoke`).
+
+> 💡 **Model Deployment:** Use `models/deploy-model` for all deployment scenarios — it intelligently routes between quick preset deployment, customized deployment with full control, and capacity discovery across regions.
+
+## Agent Development Lifecycle
+
+Match user intent to the correct workflow. Read each sub-skill in order before executing.
+
+| User Intent | Workflow (read in order) |
+|-------------|------------------------|
+| Create a new agent from scratch | [create](foundry-agent/create/create.md) → [deploy](foundry-agent/deploy/deploy.md) → [invoke](foundry-agent/invoke/invoke.md) |
+| Deploy an agent (code already exists) | deploy → invoke |
+| Update/redeploy an agent after code changes | deploy → invoke |
+| Invoke/test/chat with an agent | invoke |
+| Troubleshoot an agent issue | invoke → troubleshoot |
+| Fix a broken agent (troubleshoot + redeploy) | invoke → troubleshoot → apply fixes → deploy → invoke |
+| Start/stop agent container | deploy |
+
+## Agent: Project Context Resolution
+
+Agent skills should run this step **only when they need configuration values they don't already have**. If a value (e.g., project endpoint, agent name) is already known from the user's message or a previous skill in the same session, skip resolution for that value.
+
+### Step 1: Detect azd Project
+
+If any required configuration value is missing, check if `azure.yaml` exists in the project root (workspace root or user-specified project path). If found, run `azd env get-values` to load environment variables.
+
+### Step 2: Resolve Common Configuration
+
+Match missing values against the azd environment:
+
+| azd Variable | Resolves To | Used By |
+|-------------|-------------|---------|
+| `AZURE_AI_PROJECT_ENDPOINT` or `AZURE_AIPROJECT_ENDPOINT` | Project endpoint | deploy, invoke, troubleshoot |
+| `AZURE_CONTAINER_REGISTRY_NAME` or `AZURE_CONTAINER_REGISTRY_ENDPOINT` | ACR registry name / image URL prefix | deploy |
+| `AZURE_SUBSCRIPTION_ID` | Azure subscription | troubleshoot |
+
+### Step 3: Collect Missing Values
+
+Use the `ask_user` or `askQuestions` tool **only for values not resolved** from the user's message, session context, or azd environment. Common values skills may need:
+- **Project endpoint** — AI Foundry project endpoint URL
+- **Agent name** — Name of the target agent
+
+> 💡 **Tip:** If the user provides a project endpoint or agent name in their initial message, extract it directly — do not ask again.
+
+## Agent: Agent Types
+
+All agent skills support two agent types:
+
+| Type | Kind | Description |
+|------|------|-------------|
+| **Prompt** | `"prompt"` | LLM-based agents backed by a model deployment |
+| **Hosted** | `"hosted"` | Container-based agents running custom code |
+
+Use `agent_get` MCP tool to determine an agent's type when needed.
+
+## Tool Usage Conventions
+
+- Use the `ask_user` or `askQuestions` tool whenever collecting information from the user
+- Use the `task` or `runSubagent` tool to delegate long-running or independent sub-tasks (e.g., env var scanning, status polling, Dockerfile generation)
+- Prefer Azure MCP tools over direct CLI commands when available
+- Reference official Microsoft documentation URLs instead of embedding CLI command syntax
+
+## Additional Resources
+
+- [Foundry Hosted Agents](https://learn.microsoft.com/azure/ai-foundry/agents/concepts/hosted-agents?view=foundry)
+- [Foundry Agent Runtime Components](https://learn.microsoft.com/azure/ai-foundry/agents/concepts/runtime-components?view=foundry)
+- [Foundry Samples](https://github.com/azure-ai-foundry/foundry-samples)
+
+## SDK Quick Reference
+
+- [Python](references/sdk/foundry-sdk-py.md)

package/.agents/skills/microsoft-foundry/foundry-agent/create/create-prompt.md

@@ -0,0 +1,89 @@
+# Create Prompt Agent
+
+Create and manage prompt agents in Azure Foundry Agent Service using MCP tools or Python SDK. For hosted agents (container-based), see [create.md](create.md).
+
+## Quick Reference
+
+| Property | Value |
+|----------|-------|
+| **Agent Type** | Prompt (`kind: "prompt"`) |
+| **Primary Tool** | Foundry MCP server (`foundry_agents_*`) |
+| **Fallback SDK** | `azure-ai-projects` v2.x preview |
+| **Auth** | `DefaultAzureCredential` / `az login` |
+
+## Workflow
+
+```
+User Request (create/list/get/update/delete agent)
+    │
+    ▼
+Step 1: Resolve project context (endpoint + credentials)
+    │
+    ▼
+Step 2: Try MCP tool for the operation
+    │  ├─ ✅ MCP available → Execute via MCP tool → Done
+    │  └─ ❌ MCP unavailable → Continue to Step 3
+    │
+    ▼
+Step 3: Fall back to SDK
+    │  Read references/sdk-operations.md for code
+    │
+    ▼
+Step 4: Execute and confirm result
+```
+
+### Step 1: Resolve Project Context
+
+The user needs a Foundry project endpoint. Check for:
+
+1. `PROJECT_ENDPOINT` environment variable
+2. Ask the user for their project endpoint
+3. Use `foundry_resource_get` MCP tool to discover it
+
+Endpoint format: `https://<resource>.services.ai.azure.com/api/projects/<project>`
+
+### Step 2: Create Agent (MCP — Preferred)
+
+For a **prompt agent**:
+- Provide: agent name, model deployment name, instructions
+- Optional: tools (code interpreter, file search, function calling, web search, Bing grounding, memory)
+
+For a **workflow**:
+- Workflows are created in the Foundry portal visual builder
+- Use MCP to create the individual agents that participate in the workflow
+- Direct the user to the Foundry portal for workflow assembly
+
+### Step 3: SDK Fallback
+
+If MCP tools are unavailable, use the `azure-ai-projects` SDK:
+- See [SDK Operations](references/sdk-operations.md) for create, list, update, delete code samples
+- See [Agent Tools](references/agent-tools.md) for adding tools to agents
+
+### Step 4: Add Tools (Optional)
+
+> ⚠️ **MANDATORY:** Before configuring any tool, **read its reference documentation** linked below to understand prerequisites, required parameters, and setup steps. Do not attempt to add a tool without first reviewing its reference.
+
+| Tool Category | Reference |
+|---------------|-----------|
+| Code Interpreter, Function Calling | [Simple Tools](references/agent-tools.md) |
+| File Search (requires vector store) | [File Search](references/tool-file-search.md) |
+| Web Search (default, no setup needed) | [Web Search](references/tool-web-search.md) |
+| Bing Grounding (explicit request only) | [Bing Grounding](references/tool-bing-grounding.md) |
+| Azure AI Search (private data) | [Azure AI Search](references/tool-azure-ai-search.md) |
+| MCP Servers | [MCP Tool](references/tool-mcp.md) |
+| Memory (persistent across sessions) | [Memory](references/tool-memory.md) |
+| Connections (for tools that need them) | [Project Connections](../../project/connections.md) |
+
+> ⚠️ **Web Search Default:** Use `WebSearchPreviewTool` for web search. Only use `BingGroundingAgentTool` when the user explicitly requests Bing Grounding.
+
+## Error Handling
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| Agent creation fails | Missing model deployment | Deploy a model first via `foundry_models_deploy` or portal |
+| MCP tool not found | MCP server not running | Fall back to SDK — see [SDK Operations](references/sdk-operations.md) |
+| Permission denied | Insufficient RBAC | Need `Azure AI User` role on the project |
+| Agent name conflict | Name already exists | Use a unique name or update the existing agent |
+| Tool not available | Tool not configured for project | Verify tool prerequisites (e.g., Bing resource for grounding) |
+| SDK version mismatch | Using 1.x instead of 2.x | Install `azure-ai-projects --pre` for v2.x preview |
+| Tenant mismatch | MCP token tenant differs from resource tenant | Fall back to SDK — `DefaultAzureCredential` resolves the correct tenant |