@brunosps00/dev-workflow 1.0.1 → 1.0.4

package/lib/install-aws-skills.js

@@ -0,0 +1,345 @@
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execSync } = require('child_process');
+const { ensureDir, writeFile } = require('./utils');
+const { multiSelect } = require('./prompts');
+const { addMcpServer } = require('./mcp');
+const { CATEGORIES, listCategories, resolveDirs } = require('./aws-categories');
+
+const UPSTREAM_REPO = 'https://github.com/aws/agent-toolkit-for-aws.git';
+const MCP_NAME = 'aws-mcp';
+const DEFAULT_REGION = 'us-east-1';
+
+// AWS MCP Server endpoints — see https://docs.aws.amazon.com/aws-mcp/.
+// Knowledge MCP (https://knowledge-mcp.global.api.aws) is deprecated by AWS in
+// favor of the unified server. We intentionally only register the unified one.
+const REGIONAL_ENDPOINTS = {
+  'us-east-1': 'https://aws-mcp.us-east-1.api.aws/mcp',
+  'eu-central-1': 'https://aws-mcp.eu-central-1.api.aws/mcp',
+};
+
+function buildMcpConfig(region) {
+  const endpoint = REGIONAL_ENDPOINTS[region] || REGIONAL_ENDPOINTS[DEFAULT_REGION];
+  return {
+    command: 'uvx',
+    args: [
+      'mcp-proxy-for-aws@latest',
+      endpoint,
+      '--metadata',
+      `AWS_REGION=${region}`,
+    ],
+    transport: 'stdio',
+    timeout: 100000,
+  };
+}
+
+const AWS_MCP_INSTRUCTIONS = `# AWS MCP Server — How the agent should use it
+
+Installed by \`/dw-install-aws-skills\` (or \`npx @brunosps00/dev-workflow install-aws-skills\`). Lives at \`.dw/references/aws-mcp-instructions.md\` and is automatically discoverable by any \`dw-*\` command that touches AWS code paths.
+
+## Available MCP tools (from \`aws-mcp\` server)
+
+| Tool | When to call it | Destructive? |
+|------|-----------------|---------------|
+| \`aws___search_documentation\` | The user asks "how does X work in AWS", "what's the limit of Y", "best practice for Z" — anything conceptual or capability-oriented. Returns indexed hits from docs.aws.amazon.com. | No (read-only) |
+| \`aws___read_documentation\` | A specific docs.aws.amazon.com URL is already in context (cited by the user, returned by a previous search, in an error message) and you need the full page content. | No (read-only) |
+| \`aws___retrieve_skill\` | The user is starting a specific AWS task and you want a curated skill (CDK setup, Bedrock invocation pattern, etc.). Pulls from the bundled skill catalog. | No (read-only) |
+| \`aws___call_aws\` | The user explicitly asked for an AWS API operation — list, describe, create, modify, delete. Executes against the user's IAM credentials. | **YES — can mutate cloud state** |
+| \`aws___run_script\` | Heavier analysis or orchestration that needs Python: parsing JSON returned by \`call_aws\`, aggregating across services, running an ad-hoc query. | **YES — can call APIs from the script** |
+
+## Destructive operations — required behavior
+
+<critical>
+Before invoking \`aws___call_aws\` for any of the following, STATE the operation in chat, the target resource (account ID, region, resource ID/name), and the expected effect. WAIT for explicit user confirmation:
+
+- Any \`create*\`, \`put*\`, \`update*\`, \`modify*\`, \`delete*\`, \`terminate*\`, \`stop*\` API
+- Any IAM change (role, policy, user, group, identity provider, permission boundary)
+- Any operation that affects billing (provisioning, scaling, premium support, marketplace subscriptions)
+- Any operation in production accounts (detect via account ID or tags if available)
+
+For read-only operations (\`list*\`, \`describe*\`, \`get*\`), proceed without confirmation — but cite the call in the report.
+
+The user's IAM principal determines what the call CAN do. dev-workflow does NOT validate scope. If a destructive call fails with AccessDenied, that is by design — surface the error and stop.
+</critical>
+
+## Region behavior
+
+The MCP server endpoint is regional (currently \`us-east-1\` and \`eu-central-1\`). The AWS operations the server performs default to the region encoded in the proxy \`--metadata AWS_REGION=<x>\` argument inside \`.claude/settings.json\`. Override per-query by saying "list EC2 instances in eu-west-1" — the server honors regions in the prompt.
+
+To change the default permanently, edit the args array in \`.claude/settings.json\` (\`AWS_REGION=<x>\`) and pick the corresponding endpoint URL, or re-run \`/dw-install-aws-skills --region=<x>\`.
+
+## When NOT to call
+
+- Pure code review with no AWS surface. Use \`dw-review\` rules + project conventions.
+- Questions about non-AWS clouds (Azure, GCP, vendor SaaS). The AWS MCP only returns AWS content; calling it on unrelated topics wastes budget.
+- Trivial syntactic questions answerable from the codebase or current model knowledge — fetching docs is overkill.
+
+## Source-grounding discipline
+
+Every claim about AWS that comes from these tools MUST be cited per the \`dw-source-grounding\` skill format:
+
+\`\`\`
+[source: <docs.aws.amazon.com URL>, version: <as displayed>, retrieved: YYYY-MM-DD]
+\`\`\`
+
+For \`aws___call_aws\` results, cite the API name + region + a one-line summary of what was returned (do not paste full JSON blobs into the response unless the user asks).
+
+## Companion skills
+
+The \`.agents/skills/aws/\` directory holds skills installed by \`/dw-install-aws-skills\`. Skills under \`aws-cdk\`, \`aws-cloudformation\`, \`aws-iam\`, etc. encode best practices that often answer the question without a network round-trip. Prefer loading the matching skill BEFORE calling the MCP tools.
+
+## Prerequisites the user maintains
+
+- \`uv\` (Python tool runner) — used by \`uvx\` to invoke \`mcp-proxy-for-aws\`.
+- \`aws cli\` ≥ 2.32.0 — proxy uses it for credential discovery.
+- Valid AWS credentials — typically via \`aws login\`, IAM access keys, or SSO profile. Verify with \`aws sts get-caller-identity\`.
+
+If credentials expire (most commonly with short-lived session tokens), the agent's tool calls will fail with \`ExpiredTokenException\`. Tell the user to refresh and re-try; do not silently swallow the error.
+
+## Refresh / uninstall
+
+- **Refresh:** re-run \`/dw-install-aws-skills\` (or \`npx @brunosps00/dev-workflow install-aws-skills\`). The command clears \`.agents/skills/aws/\` and pulls upstream fresh.
+- **Uninstall:** delete \`.agents/skills/aws/\` and remove the \`aws-mcp\` entry from \`.claude/settings.json\` \`mcpServers\`.
+
+## Attribution
+
+Skills are sourced from [\`aws/agent-toolkit-for-aws\`](https://github.com/aws/agent-toolkit-for-aws) (Apache 2.0). The MCP server is documented at [docs.aws.amazon.com/aws-mcp/](https://docs.aws.amazon.com/aws-mcp/). The proxy is [\`aws/mcp-proxy-for-aws\`](https://github.com/aws/mcp-proxy-for-aws).
+`;
+
+function check(cmd) {
+  try {
+    execSync(cmd, { stdio: 'pipe', timeout: 10000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function printPrereqInstructions(missing) {
+  console.log('\n  Missing prerequisites — install these before re-running:\n');
+  if (missing.has('git')) {
+    console.log('  git:');
+    console.log('    macOS:    brew install git   (or use Xcode Command Line Tools)');
+    console.log('    Linux:    apt install git    (or distro equivalent)');
+    console.log('    Windows:  https://git-scm.com/download/win\n');
+  }
+  if (missing.has('uv')) {
+    console.log('  uv (Python tool runner — runs uvx):');
+    console.log('    macOS/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh');
+    console.log('    Windows:     powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"\n');
+  }
+  if (missing.has('aws')) {
+    console.log('  aws cli (version 2.32.0 or later):');
+    console.log('    https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html');
+    console.log('    macOS:    brew install awscli');
+    console.log('    Windows:  winget install Amazon.AWSCLI');
+    console.log('    Linux:    See AWS docs for arch-specific .zip\n');
+  }
+  if (missing.has('creds')) {
+    console.log('  AWS credentials:');
+    console.log('    Easiest:   aws login           (rotates every 15 min, valid 12h)');
+    console.log('    SSO:       aws configure sso');
+    console.log('    Keys:      aws configure        (IAM access keys)');
+    console.log('    Verify:    aws sts get-caller-identity\n');
+  }
+}
+
+function shallowClone(targetDir) {
+  ensureDir(path.dirname(targetDir));
+  execSync(`git clone --depth=1 ${UPSTREAM_REPO} "${targetDir}"`, {
+    stdio: 'inherit',
+    timeout: 180000,
+  });
+}
+
+function expandGlob(repoRoot, pattern) {
+  // Supports two forms: "core-skills/*" and "specialized-skills/<x>/*".
+  // Globbing kept minimal — no node-glob dependency.
+  const skillsRoot = path.join(repoRoot, 'skills');
+  const parts = pattern.split('/');
+  if (parts[parts.length - 1] !== '*') {
+    // exact path
+    const fullPath = path.join(skillsRoot, pattern);
+    return fs.existsSync(fullPath) ? [fullPath] : [];
+  }
+  const parentRel = parts.slice(0, -1).join('/');
+  const parent = path.join(skillsRoot, parentRel);
+  if (!fs.existsSync(parent)) return [];
+  return fs
+    .readdirSync(parent, { withFileTypes: true })
+    .filter((e) => e.isDirectory())
+    .map((e) => path.join(parent, e.name));
+}
+
+function collectAllSkillDirs(repoRoot) {
+  const out = [];
+  for (const pattern of ['core-skills/*', 'specialized-skills/*/*']) {
+    out.push(...expandGlob(repoRoot, pattern));
+  }
+  return out;
+}
+
+function copyTree(srcDir, destDir) {
+  ensureDir(destDir);
+  for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
+    const srcPath = path.join(srcDir, entry.name);
+    const destPath = path.join(destDir, entry.name);
+    if (entry.isDirectory()) {
+      copyTree(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+function rmRecursive(targetPath) {
+  if (!fs.existsSync(targetPath)) return;
+  fs.rmSync(targetPath, { recursive: true, force: true });
+}
+
+function hasExecutable(skillDir) {
+  if (!fs.existsSync(skillDir)) return false;
+  for (const entry of fs.readdirSync(skillDir, { withFileTypes: true })) {
+    if (!entry.isFile()) continue;
+    if (/\.(sh|py|js|ts|mjs|cjs|ps1|bat)$/i.test(entry.name)) return true;
+  }
+  return false;
+}
+
+function parseFlag(name) {
+  for (const arg of process.argv.slice(2)) {
+    if (arg.startsWith(`--${name}=`)) {
+      return arg.slice(name.length + 3);
+    }
+  }
+  return null;
+}
+
+async function run() {
+  const projectRoot = process.cwd();
+
+  console.log('\n  dev-workflow install-aws-skills');
+  console.log(`  ${'='.repeat(40)}\n`);
+
+  // 1. Detect prerequisites
+  const missing = new Set();
+  if (!check('git --version')) missing.add('git');
+  if (!check('uv --version')) missing.add('uv');
+  if (!check('aws --version')) missing.add('aws');
+
+  if (!missing.has('aws')) {
+    // Only check creds if the CLI itself is present.
+    if (!check('aws sts get-caller-identity')) missing.add('creds');
+  }
+
+  if (missing.size > 0) {
+    console.log('  \x1b[31m✗ prerequisites not met\x1b[0m');
+    printPrereqInstructions(missing);
+    process.exit(1);
+  }
+
+  console.log('  \x1b[32m✓\x1b[0m git, uv, aws cli, and AWS credentials all detected\n');
+
+  // 2. Region
+  const regionFlag = parseFlag('region');
+  const region = regionFlag || DEFAULT_REGION;
+  if (!REGIONAL_ENDPOINTS[region]) {
+    console.log(
+      `  \x1b[33m! region "${region}" has no known endpoint; falling back to ${DEFAULT_REGION}.\x1b[0m`,
+    );
+    console.log('  Supported regions:', Object.keys(REGIONAL_ENDPOINTS).join(', '));
+  }
+  const effectiveRegion = REGIONAL_ENDPOINTS[region] ? region : DEFAULT_REGION;
+  console.log(`  Region: ${effectiveRegion} (endpoint ${REGIONAL_ENDPOINTS[effectiveRegion]})\n`);
+
+  // 3. Select categories
+  const categories = listCategories();
+  const lines = categories.map((c) => `${c} — ${CATEGORIES[c].description}`);
+  const selected = await multiSelect('Select AWS skill categories to install:', lines);
+  const selectedNames = selected.map((s) => s.split(' — ')[0]);
+  console.log(`\n  Selected: ${selectedNames.join(', ')}\n`);
+
+  // 4. Clone upstream
+  const tmpDir = path.join(os.tmpdir(), `.dw-aws-skills-${Date.now()}`);
+  try {
+    console.log(`  Cloning ${UPSTREAM_REPO} (shallow)...`);
+    shallowClone(tmpDir);
+    console.log(`  \x1b[32m✓\x1b[0m cloned to ${tmpDir}\n`);
+
+    // 5. Resolve which dirs to copy
+    const resolved = resolveDirs(selectedNames);
+    let skillDirs;
+    if (resolved === '__ALL__') {
+      skillDirs = collectAllSkillDirs(tmpDir);
+    } else {
+      skillDirs = [];
+      for (const pattern of resolved) {
+        skillDirs.push(...expandGlob(tmpDir, pattern));
+      }
+    }
+
+    if (skillDirs.length === 0) {
+      console.log('  \x1b[33m! No skills matched the selected categories.\x1b[0m');
+      console.log('  Nothing copied. The MCP server will still be registered.\n');
+    } else {
+      const destRoot = path.join(projectRoot, '.agents', 'skills', 'aws');
+      console.log(`  Refreshing ${destRoot} (existing content removed)...`);
+      rmRecursive(destRoot);
+      ensureDir(destRoot);
+
+      let copied = 0;
+      let skipped = 0;
+      for (const srcDir of skillDirs) {
+        const skillName = path.basename(srcDir);
+        if (hasExecutable(srcDir)) {
+          skipped++;
+          continue;
+        }
+        // Flatten — destination has no core-skills/ vs specialized-skills/ split.
+        const destDir = path.join(destRoot, skillName);
+        copyTree(srcDir, destDir);
+        copied++;
+      }
+      console.log(`  \x1b[32m✓\x1b[0m copied ${copied} skill(s) to .agents/skills/aws/`);
+      if (skipped > 0) {
+        console.log(`  \x1b[33m! skipped ${skipped} skill(s) that ship executable scripts\x1b[0m`);
+      }
+      console.log();
+    }
+
+    // 6. Register MCP
+    const mcpConfig = buildMcpConfig(effectiveRegion);
+    const mcpStatus = addMcpServer(projectRoot, MCP_NAME, mcpConfig);
+    if (mcpStatus === 'added') {
+      console.log(`  \x1b[32m✓\x1b[0m registered ${MCP_NAME} MCP in .claude/settings.json (region ${effectiveRegion})`);
+    } else {
+      console.log(`  \x1b[33m—\x1b[0m ${MCP_NAME} MCP already present, left unchanged`);
+      console.log('     To change region, edit .claude/settings.json directly or remove the entry and re-run.');
+    }
+
+    // 7. Write instructions
+    const instructionsPath = path.join(projectRoot, '.dw', 'references', 'aws-mcp-instructions.md');
+    const status = writeFile(instructionsPath, AWS_MCP_INSTRUCTIONS, true);
+    console.log(`  \x1b[32m✓\x1b[0m ${status} ${instructionsPath}`);
+  } finally {
+    rmRecursive(tmpDir);
+  }
+
+  console.log(`\n  ${'='.repeat(40)}`);
+  console.log('  Done.');
+  console.log();
+  console.log('  Next steps:');
+  console.log('    1. Restart Claude Code (or Codex / Copilot / OpenCode) so the MCP loads.');
+  console.log('    2. Ask something AWS-specific to validate, e.g.');
+  console.log('       "What\'s the limit on Lambda concurrent executions?"');
+  console.log('    3. The agent can now call AWS APIs via aws___call_aws — review');
+  console.log('       .dw/references/aws-mcp-instructions.md for destructive-op protocol.');
+  console.log('    4. To refresh from upstream, re-run this command.');
+  console.log(`    5. Region override: re-run with --region=<aws-region> (currently: ${effectiveRegion}).`);
+  console.log('    6. To uninstall: rm -rf .agents/skills/aws/ and remove the');
+  console.log('       "aws-mcp" entry from .claude/settings.json mcpServers.');
+  console.log();
+}
+
+module.exports = { run };

package/lib/install-azure-skills.js

@@ -0,0 +1,231 @@
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execSync } = require('child_process');
+const { ensureDir, writeFile } = require('./utils');
+const { multiSelect } = require('./prompts');
+const { addMcpServer } = require('./mcp');
+const { CATEGORIES, listCategories, resolvePrefixes, matchesPrefixes } = require('./azure-categories');
+
+const UPSTREAM_REPO = 'https://github.com/MicrosoftDocs/Agent-Skills.git';
+const MCP_NAME = 'microsoft-learn';
+const MCP_CONFIG = {
+  type: 'http',
+  url: 'https://learn.microsoft.com/api/mcp',
+};
+
+const AZURE_MCP_INSTRUCTIONS = `# Azure Documentation MCP — How the agent should use it
+
+Installed by \`/dw-install-azure-skills\` (or \`npx @brunosps00/dev-workflow install-azure-skills\`). Lives at \`.dw/references/azure-mcp-instructions.md\` and is automatically discoverable by any \`dw-*\` command that touches Azure code paths.
+
+## Available MCP tools (from \`microsoft-learn\` server)
+
+| Tool | When to call it |
+|------|-----------------|
+| \`microsoft_docs_search\` | The user asks "how does X work in Azure", "what's the limit of Y", "best practice for Z" — anything conceptual or capability-oriented. Returns indexed hits from learn.microsoft.com. |
+| \`microsoft_docs_fetch\` | A specific Learn URL is already in context (cited by the user, returned by a previous search, in an error message) and you need the full page content. Pass the URL. |
+| \`microsoft_code_sample_search\` | The user wants an official code snippet — \`az cli\` invocation, .NET / Python / TypeScript SDK call, ARM/Bicep template, Terraform AzureRM example. Returns first-party samples. |
+
+## When NOT to call
+
+- Pure code review with no Azure surface. Use \`dw-review\` rules + project conventions.
+- Questions about non-Microsoft tech (AWS, GCP, vendor SaaS). The Microsoft MCP only returns Learn content; calling it on unrelated topics wastes budget.
+- Trivial syntactic questions answerable from the codebase or from current model knowledge — fetching docs is overkill.
+
+## Source-grounding discipline
+
+Every claim about Azure that comes from these tools MUST be cited per the \`dw-source-grounding\` skill format:
+
+\`\`\`
+[source: <Learn URL>, version: <as displayed on the doc>, retrieved: YYYY-MM-DD]
+\`\`\`
+
+If a tool call returns no result, fall back to web search and clearly label the answer as uncertain. Do not invent Azure API surface — Azure surface drifts and a wrong claim has cascading consequences in TechSpec → Tasks → implementation.
+
+## Companion skills
+
+The \`.agents/skills/azure/\` directory holds per-service skills installed by \`/dw-install-azure-skills\`. They contain curated guidance per service (e.g., \`azure-container-apps\`, \`azure-openai\`). When the user's task touches a service, prefer loading the matching skill BEFORE calling the MCP tools — the skill often answers without a network round-trip.
+
+## Refresh / uninstall
+
+- **Refresh:** re-run \`/dw-install-azure-skills\` (or \`npx @brunosps00/dev-workflow install-azure-skills\`). The command clears \`.agents/skills/azure/\` and pulls upstream fresh.
+- **Uninstall:** delete \`.agents/skills/azure/\` and remove the \`microsoft-learn\` entry from \`.claude/settings.json\` \`mcpServers\`.
+
+## Attribution
+
+Skills are sourced from [\`MicrosoftDocs/Agent-Skills\`](https://github.com/MicrosoftDocs/Agent-Skills) (CC-BY-4.0). The MCP server is documented at [Microsoft Learn](https://learn.microsoft.com/en-us/training/support/mcp-get-started).
+`;
+
+function checkGit() {
+  try {
+    execSync('git --version', { stdio: 'pipe', timeout: 5000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function shallowClone(targetDir) {
+  ensureDir(path.dirname(targetDir));
+  execSync(`git clone --depth=1 ${UPSTREAM_REPO} "${targetDir}"`, {
+    stdio: 'inherit',
+    timeout: 180000,
+  });
+}
+
+function listSkillDirs(repoRoot) {
+  const skillsDir = path.join(repoRoot, 'skills');
+  if (!fs.existsSync(skillsDir)) return [];
+  return fs
+    .readdirSync(skillsDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name);
+}
+
+function copySkillTree(srcDir, destDir) {
+  ensureDir(destDir);
+  const entries = fs.readdirSync(srcDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(srcDir, entry.name);
+    const destPath = path.join(destDir, entry.name);
+    if (entry.isDirectory()) {
+      copySkillTree(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+function rmRecursive(targetPath) {
+  if (!fs.existsSync(targetPath)) return;
+  fs.rmSync(targetPath, { recursive: true, force: true });
+}
+
+// Parse --products=csv override from process.argv. Returns array of slugs or null.
+function parseProductsFlag() {
+  for (const arg of process.argv.slice(2)) {
+    if (arg.startsWith('--products=')) {
+      const csv = arg.slice('--products='.length);
+      return csv.split(',').map((s) => s.trim()).filter(Boolean);
+    }
+  }
+  return null;
+}
+
+async function run() {
+  const projectRoot = process.cwd();
+
+  console.log('\n  dev-workflow install-azure-skills');
+  console.log(`  ${'='.repeat(40)}\n`);
+
+  if (!checkGit()) {
+    console.error('  \x1b[31m✗ git not found.\x1b[0m');
+    console.error('  This command needs git to clone the upstream skills repo.');
+    console.error('  Install git and re-run.');
+    process.exit(1);
+  }
+
+  // 1. Decide what to install
+  let prefixes;
+  const explicitProducts = parseProductsFlag();
+  if (explicitProducts) {
+    console.log(`  Explicit --products override: ${explicitProducts.join(', ')}\n`);
+    prefixes = explicitProducts;
+  } else {
+    const categories = listCategories();
+    const lines = [];
+    for (const cat of categories) {
+      const desc = CATEGORIES[cat].description;
+      lines.push(`${cat} — ${desc}`);
+    }
+    const selected = await multiSelect('Select Azure skill categories to install:', lines);
+    // map back from "Category — description" → category name
+    const selectedNames = selected.map((s) => s.split(' — ')[0]);
+    console.log(`\n  Selected: ${selectedNames.join(', ')}\n`);
+    prefixes = resolvePrefixes(selectedNames);
+  }
+
+  // 2. Shallow clone upstream
+  const tmpDir = path.join(os.tmpdir(), `.dw-azure-skills-${Date.now()}`);
+  try {
+    console.log(`  Cloning ${UPSTREAM_REPO} (shallow)...`);
+    shallowClone(tmpDir);
+    console.log(`  \x1b[32m✓\x1b[0m cloned to ${tmpDir}\n`);
+
+    // 3. Filter + copy
+    const allSkills = listSkillDirs(tmpDir);
+    const matched = allSkills.filter((name) => matchesPrefixes(name, prefixes));
+
+    if (matched.length === 0) {
+      console.log('  \x1b[33m! No skills matched the selected categories.\x1b[0m');
+      console.log('  Nothing copied. The MCP server will still be registered.\n');
+    } else {
+      const destRoot = path.join(projectRoot, '.agents', 'skills', 'azure');
+      console.log(`  Refreshing ${destRoot} (existing content removed)...`);
+      rmRecursive(destRoot);
+      ensureDir(destRoot);
+
+      let copied = 0;
+      let skipped = 0;
+      for (const skillName of matched) {
+        const srcDir = path.join(tmpDir, 'skills', skillName);
+        const destDir = path.join(destRoot, skillName);
+        // Skip skills that ship executable scripts outside markdown — limit scope per plan.
+        const hasShell = fs.existsSync(path.join(srcDir, 'scripts')) || hasExecutable(srcDir);
+        if (hasShell) {
+          skipped++;
+          continue;
+        }
+        copySkillTree(srcDir, destDir);
+        copied++;
+      }
+      console.log(`  \x1b[32m✓\x1b[0m copied ${copied} skill(s) to .agents/skills/azure/`);
+      if (skipped > 0) {
+        console.log(`  \x1b[33m! skipped ${skipped} skill(s) that ship executable scripts\x1b[0m`);
+      }
+      console.log();
+    }
+
+    // 4. Register MCP
+    const mcpStatus = addMcpServer(projectRoot, MCP_NAME, MCP_CONFIG);
+    if (mcpStatus === 'added') {
+      console.log(`  \x1b[32m✓\x1b[0m registered ${MCP_NAME} MCP in .claude/settings.json`);
+    } else {
+      console.log(`  \x1b[33m—\x1b[0m ${MCP_NAME} MCP already present, left unchanged`);
+    }
+
+    // 5. Write instructions
+    const instructionsPath = path.join(projectRoot, '.dw', 'references', 'azure-mcp-instructions.md');
+    const status = writeFile(instructionsPath, AZURE_MCP_INSTRUCTIONS, true);
+    console.log(`  \x1b[32m✓\x1b[0m ${status} ${instructionsPath}`);
+  } finally {
+    // 6. Cleanup
+    rmRecursive(tmpDir);
+  }
+
+  console.log(`\n  ${'='.repeat(40)}`);
+  console.log('  Done.');
+  console.log();
+  console.log('  Next steps:');
+  console.log('    1. Restart Claude Code (or Codex / Copilot / OpenCode) so the MCP loads.');
+  console.log('    2. Ask something Azure-specific to validate, e.g.');
+  console.log('       "How do I deploy a containerized app to Azure Container Apps?"');
+  console.log('    3. To refresh from upstream, re-run this command.');
+  console.log('    4. To uninstall: rm -rf .agents/skills/azure/ and remove the');
+  console.log('       "microsoft-learn" entry from .claude/settings.json mcpServers.');
+  console.log();
+}
+
+// Heuristic: any .sh / .py / .js / .ts file at the skill root counts as executable.
+// SKILL.md + references/ + assets/ stays text-only and is safe to copy.
+function hasExecutable(skillDir) {
+  if (!fs.existsSync(skillDir)) return false;
+  const entries = fs.readdirSync(skillDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isFile()) continue;
+    if (/\.(sh|py|js|ts|mjs|cjs|ps1|bat)$/i.test(entry.name)) return true;
+  }
+  return false;
+}
+
+module.exports = { run };

package/lib/mcp.js

@@ -3,38 +3,49 @@ const path = require('path');
 const { ensureDir } = require('./utils');
 const { MCP_SERVERS } = require('./constants');
 
-function installMCPs(projectRoot) {
+// Read .claude/settings.json (or return empty object if missing/malformed).
+function readSettings(projectRoot) {
   const settingsPath = path.join(projectRoot, '.claude', 'settings.json');
-  let settings = {};
-
-  if (fs.existsSync(settingsPath)) {
-    try {
-      settings = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
-    } catch {
-      settings = {};
-    }
+  if (!fs.existsSync(settingsPath)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+  } catch {
+    return {};
   }
+}
 
-  if (!settings.mcpServers) {
-    settings.mcpServers = {};
+// Write .claude/settings.json, ensuring directory exists and JSON ends with newline.
+function writeSettings(projectRoot, settings) {
+  const settingsPath = path.join(projectRoot, '.claude', 'settings.json');
+  ensureDir(path.dirname(settingsPath));
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+}
+
+// Upsert a single MCP server entry into .claude/settings.json. Returns "added" or
+// "skipped". Existing entries are NEVER overwritten — the user's config wins.
+// Shared by installMCPs (default init/update) and install-azure-skills.
+function addMcpServer(projectRoot, name, config) {
+  const settings = readSettings(projectRoot);
+  if (!settings.mcpServers) settings.mcpServers = {};
+  if (settings.mcpServers[name]) {
+    return 'skipped';
   }
+  settings.mcpServers[name] = config;
+  writeSettings(projectRoot, settings);
+  return 'added';
+}
 
+function installMCPs(projectRoot) {
   let added = 0;
   let skipped = 0;
 
   for (const [name, config] of Object.entries(MCP_SERVERS)) {
-    if (settings.mcpServers[name]) {
-      skipped++;
-    } else {
-      settings.mcpServers[name] = config;
-      added++;
-    }
+    const status = addMcpServer(projectRoot, name, config);
+    if (status === 'added') added++;
+    else skipped++;
   }
 
-  ensureDir(path.dirname(settingsPath));
-  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
-
   return { added, skipped };
 }
 
-module.exports = { installMCPs };
+module.exports = { installMCPs, addMcpServer, readSettings, writeSettings };