skill-preflight 0.1.0

package/dist/report/render.js

@@ -0,0 +1,303 @@
+export function renderReport(report, format) {
+    switch (format) {
+        case "json":
+            return `${JSON.stringify(report, null, 2)}\n`;
+        case "markdown":
+            return renderMarkdown(report);
+        case "html":
+            return renderHtml(report);
+        case "sarif":
+            return renderSarif(report);
+        case "text":
+            return renderText(report);
+    }
+}
+export function parseFormat(value) {
+    if (value === "text" || value === "json" || value === "markdown" || value === "html" || value === "sarif") {
+        return value;
+    }
+    throw new Error(`Unsupported format: ${value}. Use text, json, markdown, html, or sarif.`);
+}
+function renderText(report) {
+    const lines = [];
+    lines.push("SkillPreflight Report");
+    lines.push(`Target: ${report.target}`);
+    lines.push(`Generated: ${report.generatedAt}`);
+    lines.push(`Skills scanned: ${report.summary.count}`);
+    lines.push(`Average score: ${report.summary.averageScore}/100`);
+    lines.push("");
+    for (const skill of report.reports) {
+        lines.push(`${skill.skillName}: ${skill.score}/100 (${skill.grade}) - ${skill.recommendation}`);
+        lines.push(`Path: ${skill.rootPath}`);
+        lines.push("Category scores:");
+        for (const category of skill.categories) {
+            lines.push(`  - ${category.label}: ${category.score}/${category.maxScore}`);
+        }
+        lines.push("Metrics:");
+        lines.push(`  - Files: ${skill.metrics.totalFiles}`);
+        lines.push(`  - Size: ${formatBytes(skill.metrics.totalBytes)}`);
+        lines.push(`  - Estimated activation tokens: ${skill.metrics.estimatedActivationTokens}`);
+        if (skill.findings.length === 0) {
+            lines.push("Findings: none");
+        }
+        else {
+            lines.push("Top findings:");
+            for (const finding of skill.findings.slice(0, 8)) {
+                lines.push(`  - [${finding.severity.toUpperCase()}] ${finding.title}${formatLocation(finding)}`);
+                lines.push(`    ${finding.description}`);
+                lines.push(`    Fix: ${finding.recommendation}`);
+            }
+            if (skill.findings.length > 8) {
+                lines.push(`  - ... ${skill.findings.length - 8} more findings`);
+            }
+        }
+        lines.push("");
+    }
+    return `${lines.join("\n")}\n`;
+}
+function renderMarkdown(report) {
+    const lines = [];
+    lines.push("# SkillPreflight Report");
+    lines.push("");
+    lines.push(`- Target: \`${report.target}\``);
+    lines.push(`- Generated: \`${report.generatedAt}\``);
+    lines.push(`- Skills scanned: ${report.summary.count}`);
+    lines.push(`- Average score: ${report.summary.averageScore}/100`);
+    lines.push(`- High risk skills: ${report.summary.highRiskCount}`);
+    lines.push("");
+    for (const skill of report.reports) {
+        lines.push(`## ${skill.skillName}: ${skill.score}/100 (${skill.grade})`);
+        lines.push("");
+        lines.push(`**Recommendation:** ${skill.recommendation}`);
+        lines.push("");
+        lines.push(`**Path:** \`${skill.rootPath}\``);
+        lines.push("");
+        lines.push("| Category | Score |");
+        lines.push("| --- | ---: |");
+        for (const category of skill.categories) {
+            lines.push(`| ${category.label} | ${category.score}/${category.maxScore} |`);
+        }
+        lines.push("");
+        lines.push("| Metric | Value |");
+        lines.push("| --- | ---: |");
+        lines.push(`| Files | ${skill.metrics.totalFiles} |`);
+        lines.push(`| Size | ${formatBytes(skill.metrics.totalBytes)} |`);
+        lines.push(`| Estimated activation tokens | ${skill.metrics.estimatedActivationTokens} |`);
+        lines.push("");
+        lines.push("### Findings");
+        lines.push("");
+        if (skill.findings.length === 0) {
+            lines.push("No findings.");
+            lines.push("");
+            continue;
+        }
+        for (const finding of skill.findings) {
+            lines.push(`- **[${finding.severity.toUpperCase()}] ${finding.title}**${formatLocation(finding)}`);
+            lines.push(`  ${finding.description}`);
+            lines.push(`  Recommendation: ${finding.recommendation}`);
+        }
+        lines.push("");
+    }
+    return `${lines.join("\n")}\n`;
+}
+function renderHtml(report) {
+    const skillSections = report.reports.map(renderSkillHtml).join("\n");
+    return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>SkillPreflight Report</title>
+  <style>
+    :root { color-scheme: light dark; font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
+    body { margin: 0; background: #f6f7f9; color: #17202a; }
+    main { max-width: 1040px; margin: 0 auto; padding: 32px 20px 56px; }
+    header { margin-bottom: 24px; }
+    h1 { font-size: 28px; margin: 0 0 8px; }
+    h2 { font-size: 22px; margin: 0 0 12px; }
+    .summary, .skill { background: #fff; border: 1px solid #d9dee7; border-radius: 8px; padding: 18px; margin: 16px 0; }
+    .grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(170px, 1fr)); gap: 12px; }
+    .metric { background: #f0f3f7; border-radius: 6px; padding: 12px; }
+    .metric span { display: block; color: #5f6b7a; font-size: 12px; }
+    .metric strong { display: block; font-size: 20px; margin-top: 4px; }
+    table { width: 100%; border-collapse: collapse; margin: 12px 0; }
+    th, td { border-bottom: 1px solid #e5e8ef; padding: 9px; text-align: left; }
+    th:last-child, td:last-child { text-align: right; }
+    .finding { border-left: 4px solid #8a97a8; padding: 10px 12px; background: #f8fafc; margin: 10px 0; border-radius: 4px; }
+    .critical, .high { border-left-color: #c0392b; }
+    .medium { border-left-color: #d9822b; }
+    .low { border-left-color: #3978c3; }
+    code { background: #eef1f5; padding: 2px 5px; border-radius: 4px; }
+    @media (prefers-color-scheme: dark) {
+      body { background: #11161d; color: #e8edf4; }
+      .summary, .skill { background: #18212b; border-color: #2b3847; }
+      .metric, .finding { background: #202b36; }
+      th, td { border-bottom-color: #2b3847; }
+      code { background: #263240; }
+    }
+  </style>
+</head>
+<body>
+  <main>
+    <header>
+      <h1>SkillPreflight Report</h1>
+      <div>Target: <code>${escapeHtml(report.target)}</code></div>
+      <div>Generated: <code>${escapeHtml(report.generatedAt)}</code></div>
+    </header>
+    <section class="summary">
+      <div class="grid">
+        <div class="metric"><span>Skills scanned</span><strong>${report.summary.count}</strong></div>
+        <div class="metric"><span>Average score</span><strong>${report.summary.averageScore}/100</strong></div>
+        <div class="metric"><span>Minimum score</span><strong>${report.summary.minScore}/100</strong></div>
+        <div class="metric"><span>High risk</span><strong>${report.summary.highRiskCount}</strong></div>
+      </div>
+    </section>
+    ${skillSections}
+  </main>
+</body>
+</html>
+`;
+}
+function renderSarif(report) {
+    const ruleMap = new Map();
+    const results = [];
+    for (const skill of report.reports) {
+        for (const finding of skill.findings) {
+            ruleMap.set(finding.id, finding);
+            results.push({
+                ruleId: finding.id,
+                level: sarifLevel(finding),
+                message: {
+                    text: `${finding.title}: ${finding.description} Recommendation: ${finding.recommendation}`
+                },
+                locations: [
+                    {
+                        physicalLocation: {
+                            artifactLocation: {
+                                uri: finding.file ? normalizeSarifUri(finding.file) : normalizeSarifUri(skill.rootPath)
+                            },
+                            region: finding.line ? { startLine: finding.line } : undefined
+                        }
+                    }
+                ],
+                properties: {
+                    category: finding.category,
+                    severity: finding.severity,
+                    scoreImpact: finding.scoreImpact,
+                    skillName: skill.skillName,
+                    skillScore: skill.score
+                }
+            });
+        }
+    }
+    const rules = [...ruleMap.values()].map((finding) => ({
+        id: finding.id,
+        name: finding.title,
+        shortDescription: {
+            text: finding.title
+        },
+        fullDescription: {
+            text: finding.description
+        },
+        help: {
+            text: finding.recommendation
+        },
+        properties: {
+            category: finding.category,
+            severity: finding.severity
+        }
+    }));
+    return `${JSON.stringify({
+        version: "2.1.0",
+        $schema: "https://json.schemastore.org/sarif-2.1.0.json",
+        runs: [
+            {
+                tool: {
+                    driver: {
+                        name: "SkillPreflight",
+                        informationUri: "https://github.com/agent-contracts/skill-preflight",
+                        rules
+                    }
+                },
+                automationDetails: {
+                    id: "skill-preflight"
+                },
+                properties: {
+                    target: report.target,
+                    generatedAt: report.generatedAt,
+                    averageScore: report.summary.averageScore,
+                    highRiskCount: report.summary.highRiskCount
+                },
+                results
+            }
+        ]
+    }, null, 2)}\n`;
+}
+function renderSkillHtml(skill) {
+    const categories = skill.categories
+        .map((category) => `<tr><td>${escapeHtml(category.label)}</td><td>${category.score}/${category.maxScore}</td></tr>`)
+        .join("");
+    const findings = skill.findings.length === 0
+        ? "<p>No findings.</p>"
+        : skill.findings
+            .map((finding) => `<div class="finding ${finding.severity}">
+  <strong>[${finding.severity.toUpperCase()}] ${escapeHtml(finding.title)}</strong>
+  <div>${escapeHtml(formatLocation(finding))}</div>
+  <p>${escapeHtml(finding.description)}</p>
+  <p><strong>Recommendation:</strong> ${escapeHtml(finding.recommendation)}</p>
+</div>`)
+            .join("\n");
+    return `<section class="skill">
+  <h2>${escapeHtml(skill.skillName)}: ${skill.score}/100 (${skill.grade})</h2>
+  <p><strong>Recommendation:</strong> ${escapeHtml(skill.recommendation)}</p>
+  <p><strong>Path:</strong> <code>${escapeHtml(skill.rootPath)}</code></p>
+  <div class="grid">
+    <div class="metric"><span>Files</span><strong>${skill.metrics.totalFiles}</strong></div>
+    <div class="metric"><span>Size</span><strong>${formatBytes(skill.metrics.totalBytes)}</strong></div>
+    <div class="metric"><span>Activation tokens</span><strong>${skill.metrics.estimatedActivationTokens}</strong></div>
+  </div>
+  <table>
+    <thead><tr><th>Category</th><th>Score</th></tr></thead>
+    <tbody>${categories}</tbody>
+  </table>
+  <h3>Findings</h3>
+  ${findings}
+</section>`;
+}
+function formatLocation(finding) {
+    if (!finding.file) {
+        return "";
+    }
+    return finding.line ? ` (${finding.file}:${finding.line})` : ` (${finding.file})`;
+}
+function formatBytes(bytes) {
+    if (bytes < 1024) {
+        return `${bytes} B`;
+    }
+    const kb = bytes / 1024;
+    if (kb < 1024) {
+        return `${kb.toFixed(1)} KB`;
+    }
+    return `${(kb / 1024).toFixed(1)} MB`;
+}
+function escapeHtml(value) {
+    return value
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&#039;");
+}
+function sarifLevel(finding) {
+    if (finding.severity === "critical" || finding.severity === "high") {
+        return "error";
+    }
+    if (finding.severity === "medium") {
+        return "warning";
+    }
+    return "note";
+}
+function normalizeSarifUri(value) {
+    return value.replaceAll("\\", "/");
+}
+//# sourceMappingURL=render.js.map

package/dist/report/render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../../src/report/render.ts"],"names":[],"mappings":"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"}

package/docs/github-action.md

@@ -0,0 +1,74 @@
+# GitHub Action
+
+SkillPreflight can run in a skill repository before users install the skill.
+
+## Basic Workflow
+
+```yaml
+name: SkillPreflight
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: agent-contracts/skill-preflight@v1
+        with:
+          target: "."
+          fail-below: "70"
+```
+
+## SARIF Upload
+
+Use SARIF when you want findings to appear in GitHub code scanning.
+
+```yaml
+name: SkillPreflight
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  security-events: write
+  contents: read
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: agent-contracts/skill-preflight@v1
+        with:
+          target: "."
+          format: sarif
+          out: skill-preflight.sarif
+          fail-below: "70"
+
+      - uses: github/codeql-action/upload-sarif@v3
+        if: always()
+        with:
+          sarif_file: skill-preflight.sarif
+```
+
+## Notes
+
+The composite action runs the published npm package with `npx`.
+
+Before the first public release, replace the action usage with a direct command:
+
+```yaml
+- run: npx -y skill-preflight@latest scan . --fail-below 70
+```

package/docs/release.md

@@ -0,0 +1,57 @@
+# Release Checklist
+
+Use this checklist before publishing SkillPreflight.
+
+## Local Verification
+
+```bash
+npm install
+npm test
+npm pack --dry-run
+node dist/index.js scan examples/risky-skill
+```
+
+## npm Publish
+
+1. Confirm `package.json` name, version, license, and repository fields.
+2. Log in:
+
+```bash
+npm login
+```
+
+3. Publish:
+
+```bash
+npm publish --access public
+```
+
+After publishing, users can run:
+
+```bash
+npx skill-preflight scan ./my-skill
+```
+
+## GitHub Repository
+
+1. Create a public GitHub repository.
+2. Add the remote:
+
+```bash
+git remote add origin https://github.com/agent-contracts/skill-preflight.git
+```
+
+3. Commit and push:
+
+```bash
+git add .
+git commit -m "Initial SkillPreflight MVP"
+git branch -M main
+git push -u origin main
+```
+
+## First Milestones
+
+- Add a public score badge for README files.
+- Add a website or hosted report viewer.
+- Add npm provenance and signed release workflow.

package/docs/rules.md

@@ -0,0 +1,53 @@
+# Rule Catalog
+
+SkillPreflight uses static analysis only. It reads files but does not execute skill scripts.
+
+## Security
+
+- Remote script execution, such as `curl ... | sh`.
+- Dynamic shell, Node.js, or PowerShell execution.
+- PowerShell encoded commands and execution policy bypasses.
+- Broad destructive delete commands.
+- Secret-like local data access, including `.env`, SSH keys, API keys, browser cookies, and login data.
+- Suspicious webhook, paste, and ad-hoc upload endpoints.
+- Prompt injection phrases that attempt to override system or developer instructions.
+
+## Dependency and Install Risk
+
+- npm lifecycle scripts: `preinstall`, `install`, `postinstall`, and `prepare`.
+- Dangerous npm lifecycle scripts that download or dynamically execute code.
+- Node dependencies using `*`, `latest`, `^`, `~`, Git URLs, HTTP URLs, or local file specs.
+- Python `requirements.txt` dependencies that are unpinned.
+- Python dependencies that install from remote URLs or Git repositories.
+- Dependency manifests without lockfiles.
+
+## MCP Config Risk
+
+SkillPreflight detects common MCP JSON files, including `.mcp.json`, `mcp*.json`, and `claude_desktop_config.json`.
+
+It flags:
+
+- MCP servers launched through a shell, such as `bash`, `sh`, `cmd`, or `powershell`.
+- `npx`, `uvx`, and `pipx` MCP servers without pinned package versions.
+- Broad local paths such as user home directories.
+- Hardcoded secret-like values in MCP `env`.
+
+## Token Efficiency
+
+- Large `SKILL.md` files.
+- Large main skill files without a progressive disclosure structure.
+- Repeated long instruction lines.
+
+## Reliability and Maintainability
+
+- Missing README.
+- Missing license.
+- Missing skill metadata frontmatter.
+- Missing examples.
+- Missing tests, fixtures, or evals.
+- Vague operational language.
+
+## Compatibility
+
+- Hardcoded user paths.
+- OS-specific commands without fallback guidance.

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "skill-preflight",
+  "version": "0.1.0",
+  "description": "Pre-install safety, token, and maintainability scorecard for AI agent skills.",
+  "type": "module",
+  "bin": {
+    "skill-preflight": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/index.ts",
+    "test": "npm run build && node --test test/scan.test.mjs",
+    "scan:good": "tsx src/index.ts scan examples/good-skill",
+    "scan:risky": "tsx src/index.ts scan examples/risky-skill",
+    "prepack": "npm run build"
+  },
+  "keywords": [
+    "agent",
+    "skills",
+    "security",
+    "scanner",
+    "codex",
+    "claude",
+    "mcp",
+    "llm"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agent-contracts/skill-preflight.git"
+  },
+  "bugs": {
+    "url": "https://github.com/agent-contracts/skill-preflight/issues"
+  },
+  "homepage": "https://github.com/agent-contracts/skill-preflight#readme",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.0",
+    "tsx": "^4.20.3",
+    "typescript": "^5.8.3"
+  }
+}