test: add smoke tests for skills and plugin installs

.github/workflows/smoke-tests.yml

@@ -0,0 +1,45 @@
+name: Smoke tests
+
+on:
+  workflow_dispatch:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  smoke-tests:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v5
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24
+
+      - name: Set up Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version-file: package.json
+
+      - name: Install root smoke-test dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Install codex-plugin dependencies
+        working-directory: packages/codex-plugin
+        run: bun install --frozen-lockfile
+
+      - name: Build codex-plugin
+        working-directory: packages/codex-plugin
+        run: bun run build
+
+      - name: Run smoke tests with pinned skills CLI
+        run: bun test
+
+      - name: Run smoke tests with skills@latest
+        env:
+          SMOKE_SKILLS_CLI_CHANNEL: latest
+        run: bun test

README.md

@@ -252,6 +252,28 @@ Contributions welcome! Skills should be:
 
 When adding or editing skills, follow the [agentskills.io specification](https://agentskills.io/specification) and [Claude Code best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices). The maintainer checklist lives in [AGENTS.md](./AGENTS.md), with supporting details in [docs/skill-conventions.md](./docs/skill-conventions.md).
 
+### Validation
+
+Before opening a PR, run the local validation checks that match the current repository setup:
+
+```bash
+bun install
+bun test
+```
+
+This repository's smoke suite covers:
+
+- `SKILL.md` frontmatter parsing
+- marketplace drift between shipped skills/plugins and metadata
+- Codex plugin installation in project and pseudo-global modes
+- Claude Code layout checks
+- standalone skill installation checks
+
+The GitHub Actions smoke workflow runs the same suite twice:
+
+- once with the pinned local `skills` CLI version from `package.json`
+- once with `skills@latest` as a lightweight forward-compatibility signal
+
 ## Roadmap / Work in Progress
 
 This is just the start! The following features are planned or in progress.

package.json

@@ -0,0 +1,9 @@
+{
+  "name": "agent-skills-smoke-tests",
+  "private": true,
+  "packageManager": "bun@1.3.11",
+  "devDependencies": {
+    "gray-matter": "^4.0.3",
+    "skills": "1.4.9"
+  }
+}

tests/claude-layout-smoke.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, test } from "bun:test";
+import { cpSync, existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import {
+  createTempDir,
+  cleanupTempDir,
+  parseFrontmatter,
+  readJsonFile,
+  repoRoot
+} from "./helpers/smoke-test-helpers";
+
+type ClaudeMarketplacePlugin = {
+  name: string;
+  source: string;
+  skills: string[];
+};
+
+type ClaudeMarketplaceManifest = {
+  name: string;
+  plugins: ClaudeMarketplacePlugin[];
+};
+
+function getClaudeMarketplace(): ClaudeMarketplaceManifest {
+  return readJsonFile<ClaudeMarketplaceManifest>(
+    join(repoRoot, ".claude-plugin", "marketplace.json")
+  );
+}
+
+describe("claude layout smoke", () => {
+  test("parses the Claude marketplace and resolves plugin skills under the plugin source", () => {
+    const manifest = getClaudeMarketplace();
+
+    expect(manifest.name).toBeString();
+    expect(manifest.plugins.length).toBeGreaterThan(0);
+
+    for (const plugin of manifest.plugins) {
+      const pluginSourceRoot = resolve(repoRoot, plugin.source);
+
+      expect(existsSync(pluginSourceRoot)).toBe(true);
+      expect(plugin.skills.length).toBeGreaterThan(0);
+
+      for (const skillPath of plugin.skills) {
+        const absoluteSkillPath = resolve(pluginSourceRoot, skillPath);
+
+        expect(absoluteSkillPath.startsWith(join(repoRoot, "skills"))).toBe(true);
+        expect(existsSync(absoluteSkillPath)).toBe(true);
+        expect(existsSync(join(absoluteSkillPath, "SKILL.md"))).toBe(true);
+
+        const frontmatter = parseFrontmatter(
+          readFileSync(join(absoluteSkillPath, "SKILL.md"), "utf8")
+        );
+
+        expect(frontmatter.name).toBeString();
+        expect(frontmatter.name).toBe(plugin.name);
+      }
+    }
+  });
+
+  test("copies skills into the documented personal Claude layout", () => {
+    const tempRoot = createTempDir("claude-personal-layout-smoke-");
+
+    try {
+      const manifest = getClaudeMarketplace();
+      const personalSkillsRoot = join(tempRoot, ".claude", "skills");
+
+      for (const plugin of manifest.plugins) {
+        const sourceSkillRoot = resolve(repoRoot, plugin.skills[0]!);
+        const targetSkillRoot = join(personalSkillsRoot, plugin.name);
+
+        cpSync(sourceSkillRoot, targetSkillRoot, { recursive: true, dereference: true });
+
+        expect(existsSync(join(targetSkillRoot, "SKILL.md"))).toBe(true);
+        expect(
+          readFileSync(join(targetSkillRoot, "SKILL.md"), "utf8")
+        ).toContain(`name: ${plugin.name}`);
+      }
+    } finally {
+      cleanupTempDir(tempRoot);
+    }
+  });
+
+  test("copies skills into the documented project Claude layout", () => {
+    const tempRoot = createTempDir("claude-project-layout-smoke-");
+
+    try {
+      const manifest = getClaudeMarketplace();
+      const projectRoot = join(tempRoot, "project");
+      const projectSkillsRoot = join(projectRoot, ".claude", "skills");
+
+      for (const plugin of manifest.plugins) {
+        const sourceSkillRoot = resolve(repoRoot, plugin.skills[0]!);
+        const targetSkillRoot = join(projectSkillsRoot, plugin.name);
+
+        cpSync(sourceSkillRoot, targetSkillRoot, { recursive: true, dereference: true });
+
+        expect(existsSync(join(targetSkillRoot, "SKILL.md"))).toBe(true);
+        expect(
+          readFileSync(join(targetSkillRoot, "SKILL.md"), "utf8")
+        ).toContain(`name: ${plugin.name}`);
+      }
+    } finally {
+      cleanupTempDir(tempRoot);
+    }
+  });
+});