### Quick Start

Source: https://github.com/voodootikigod/skills-check/blob/main/README.md

A brief guide to get started with skills-check, including initializing a registry and checking for staleness.

```APIDOC
## Quick Start

### 1. Initialize a registry

Scan your skills directory and map products to npm packages. This creates a `skills-check.json` registry file.

**Interactive mode:**
```bash
skills-check init ./skills
```

**Non-interactive mode (auto-detect):**
```bash
skills-check init ./skills --yes
```

### 2. Check for staleness

Run the check command to identify stale skill versions.

```bash
skills-check check
```

**Example Output:**
```
skills-check
==================================================

STALE (2):
  Vercel AI SDK            6.0.105 → 6.1.0 (minor)
    skills: ai-sdk-core, ai-sdk-tools, ai-sdk-react, ai-sdk-multimodal

  Payload CMS              3.78.0 → 3.80.0 (minor)
    skills: payload-core, payload-data, payload-admin

CURRENT (15): upstash-redis, next, turbo, ...

Run "skills-check report --format markdown" for a full report.
```

### 3. Generate a report

Create a detailed report in various formats.

**Markdown format (for PRs, issues):**
```bash
skills-check report --format markdown > STALENESS.md
```

**JSON format (for automation):**
```bash
skills-check report --format json
```
```

--------------------------------

### Quick Start

Source: https://github.com/voodootikigod/skills-check/blob/main/packages/cli/README.md

A quick guide to get started with skills-check, including initializing a registry, checking for staleness, generating reports, and using AI-assisted refresh.

```APIDOC
## Quick Start

### 1. Initialize a Registry

Scan your skills directory and map products to npm packages. This creates a `skills-check.json` registry file.

```bash
# Interactive mode
skills-check init ./skills

# Non-interactive mode (auto-detects common packages)
skills-check init ./skills --yes
```

### 2. Check for Staleness

Run the check command to see which skills need updating.

```bash
skills-check check
```

**Example Output:**

```
skills-check
==================================================

STALE (2):
  Vercel AI SDK            6.0.105 → 6.1.0 (minor)
    skills: ai-sdk-core, ai-sdk-tools, ai-sdk-react

  Payload CMS              3.78.0 → 3.80.0 (minor)
    skills: payload-core, payload-data, payload-admin

CURRENT (15): upstash-redis, next, turbo, ...

Run "skills-check report --format markdown" for a full report.
```

### 3. Generate a Report

Create a detailed report in markdown or JSON format.

```bash
# Markdown report (for PRs, issues, dashboards)
skills-check report --format markdown > STALENESS.md

# JSON report (for automation)
skills-check report --format json
```

### 4. AI-Assisted Refresh

Use an LLM to propose targeted updates to stale skill files. Requires provider SDK and API key setup.

```bash
# Interactive mode (review each change)
skills-check refresh ./skills

# Auto-apply all changes
skills-check refresh -y

# Preview only (no writes)
skills-check refresh --dry-run
```

**Provider Setup Examples:**

```bash
# Anthropic (Claude)
npm install @ai-sdk/anthropic
export ANTHROPIC_API_KEY=sk-...

# OpenAI
npm install @ai-sdk/openai
export OPENAI_API_KEY=sk-...

# Google (Gemini)
npm install @ai-sdk/google
export GOOGLE_GENERATIVE_AI_API_KEY=...
```
```

--------------------------------

### Installation

Source: https://github.com/voodootikigod/skills-check/blob/main/README.md

Instructions on how to install and run the skills-check CLI tool.

```APIDOC
## Installation

Install the tool globally using npm:

```bash
npm install -g skills-check
```

Alternatively, run it directly using npx:

```bash
npx skills-check check
```
```

--------------------------------

### Start Web Development Server

Source: https://github.com/voodootikigod/skills-check/blob/main/CLAUDE.md

Navigates to the web package directory and starts the Next.js development server.

```bash
cd packages/web && pnpm run dev
```

--------------------------------

### Install and Run skills-check

Source: https://github.com/voodootikigod/skills-check/blob/main/packages/cli/README.md

Install the package globally or execute it directly using npx.

```bash
npm install -g skills-check
```

```bash
npx skills-check check
```

--------------------------------

### Installation

Source: https://github.com/voodootikigod/skills-check/blob/main/packages/cli/README.md

Install the skills-check CLI globally using npm or run it directly with npx.

```APIDOC
## Installation

Install the skills-check CLI globally using npm or run it directly with npx.

### Install Globally

```bash
npm install -g skills-check
```

### Run Directly

```bash
npx skills-check check
```
```

--------------------------------

### Install skills-check Globally or via npx

Source: https://context7.com/voodootikigod/skills-check/llms.txt

Install the skills-check CLI globally using npm or run it directly without installation using npx.

```bash
# Global installation
npm install -g skills-check
```

```bash
# Or run directly without installing
npx skills-check check
```

--------------------------------

### Example skills-check Registry File

Source: https://context7.com/voodootikigod/skills-check/llms.txt

An example of a skills-check.json registry file, mapping products to npm packages and specifying verification details.

```json
{
  "$schema": "https://skillscheck.ai/schema.json",
  "version": 1,
  "lastCheck": "2026-02-28T00:00:00Z",
  "products": {
    "ai-sdk": {
      "displayName": "Vercel AI SDK",
      "package": "ai",
      "verifiedVersion": "6.0.105",
      "verifiedAt": "2026-02-28T00:00:00Z",
      "changelog": "https://github.com/vercel/ai/releases",
      "skills": ["ai-sdk-core", "ai-sdk-tools", "ai-sdk-react"],
      "agents": ["ai-sdk-engineer"]
    }
  }
}
```

--------------------------------

### Install skills-check CLI

Source: https://github.com/voodootikigod/skills-check/blob/main/README.md

Install the skills-check command-line interface globally using npm.

```bash
npm install -g skills-check
```

--------------------------------

### Example skills-check Check Output

Source: https://context7.com/voodootikigod/skills-check/llms.txt

Example output from the 'skills-check check' command, highlighting stale and current products with version information.

```text
skills-check
==================================================

STALE (2):
  Vercel AI SDK            6.0.105 → 6.1.0 (minor)
    skills: ai-sdk-core, ai-sdk-tools, ai-sdk-react, ai-sdk-multimodal

  Payload CMS              3.78.0 → 3.80.0 (minor)
    skills: payload-core, payload-data, payload-admin

CURRENT (15): upstash-redis, next, turbo, ...

Run "skills-check report --format markdown" for a full report.
```

--------------------------------

### Example .skill-policy.yml configuration

Source: https://context7.com/voodootikigod/skills-check/llms.txt

A sample .skill-policy.yml file demonstrating configuration for sources, banned patterns, metadata requirements, freshness, content restrictions, audit settings, and required skills.

```yaml
version: 1

sources:
  allow:
    - "@anthropic/*"
    - "@vercel/*"
  deny:
    - "@untrusted/*"

banned:
  - skill: "deprecated-tool"
    reason: "Use modern-tool instead"

metadata:
  required_fields:
    - name
    - description
    - compatibility
  require_license: true
  allowed_licenses:
    - MIT
    - Apache-2.0

freshness:
  max_age_days: 90
  max_version_drift: minor
  require_version_tracking: true

content:
  deny_patterns:
    - pattern: "rm -rf /"
      reason: "Destructive command not allowed"

audit:
  require_clean: true
  min_severity_to_block: high

required:
  - skill: "security-guidelines"
    source: "@company/skills"
```

--------------------------------

### Configure AI Provider SDKs

Source: https://github.com/voodootikigod/skills-check/blob/main/packages/cli/README.md

Install the required provider SDK and set the corresponding API key environment variable.

```bash
# Anthropic (Claude)
npm install @ai-sdk/anthropic
export ANTHROPIC_API_KEY=sk-...

# OpenAI
npm install @ai-sdk/openai
export OPENAI_API_KEY=sk-...

# Google (Gemini)
npm install @ai-sdk/google
export GOOGLE_GENERATIVE_AI_API_KEY=...
```

--------------------------------

### Configure LLM providers

Source: https://context7.com/voodootikigod/skills-check/llms.txt

Install necessary SDKs and set environment variables for supported LLM providers.

```bash
npm install @ai-sdk/anthropic
export ANTHROPIC_API_KEY=sk-...

npm install @ai-sdk/openai
export OPENAI_API_KEY=sk-...

npm install @ai-sdk/google
export GOOGLE_GENERATIVE_AI_API_KEY=...
```

--------------------------------

### Install Dependencies with pnpm

Source: https://github.com/voodootikigod/skills-check/blob/main/CLAUDE.md

Always use pnpm for installing dependencies in this project. Never use npm.

```bash
pnpm install
```

--------------------------------

### Install js-tiktoken dependency

Source: https://github.com/voodootikigod/skills-check/blob/main/PLAN.md

Command to install the required tokenization library in the CLI package.

```bash
cd packages/cli && npm install js-tiktoken
```

--------------------------------

### CI Integration

Source: https://github.com/voodootikigod/skills-check/blob/main/packages/cli/README.md

Example GitHub Actions configuration to fail a build if stale skills are detected.

```yaml
# GitHub Actions — fail if any skills are stale
- name: Check skill freshness
  run: npx skills-check check --ci
```

--------------------------------

### Skill Fingerprint JSON Output Example

Source: https://github.com/voodootikigod/skills-check/blob/main/README.md

An example of the JSON output format for the `skills-check fingerprint --json` command, detailing skill names, versions, fingerprints, token counts, and paths.

```json
{
  "skills": [
    {
      "name": "react-patterns",
      "version": "1.2.0",
      "fingerprints": {
        "watermark": "sk_abc123...",
        "frontmatter_sha256": "e3b0c44...",
        "content_sha256": "a1b2c3d...",
        "content_prefix_sha256": "f4e5d6c..."
      },
      "token_count": 1842,
      "path": "skills/react/SKILL.md"
    }
  ]
}
```

--------------------------------

### Skill Frontmatter Example

Source: https://github.com/voodootikigod/skills-check/blob/main/README.md

Skills declare their product version in YAML frontmatter using the `compatibility` field in `package@semver` format. The legacy `product-version` field is also supported.

```yaml
---
name: ai-sdk-core
description: "Generate text with Vercel AI SDK..."
compatibility: "ai@^6.0.0"
---
```

--------------------------------

### Weekly cron workflow configuration

Source: https://github.com/voodootikigod/skills-check/blob/main/README.md

Full workflow example scheduled to run weekly with specific quality gate settings.

```yaml
name: Skill Quality Check
on:
  schedule:
    - cron: "0 9 * * 1"   # Monday 09:00 UTC
  workflow_dispatch:

permissions:
  contents: read
  issues: write

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: voodootikigod/skills-check@v1
        with:
          commands: check,audit,lint,budget
          audit-fail-on: high
          budget-max-tokens: 100000
          fail-on-stale: "false"
```

--------------------------------

### Example fingerprint JSON output

Source: https://context7.com/voodootikigod/skills-check/llms.txt

The structure of the generated fingerprint registry file.

```json
{
  "version": 1,
  "generatedAt": "2026-03-01T12:00:00Z",
  "entries": [
    {
      "skillId": "react-patterns",
      "version": "1.2.0",
      "source": "@company/skills",
      "frontmatterHash": "e3b0c44298fc1c14...",
      "contentHash": "a1b2c3d4e5f6...",
      "prefixHash": "f4e5d6c7b8a9...",
      "watermark": "skill:react-patterns/1.2.0 @company/skills",
      "tokenCount": 1842,
      "path": "skills/react/SKILL.md"
    }
  ]
}
```

--------------------------------

### Run skills-check check via npx

Source: https://github.com/voodootikigod/skills-check/blob/main/README.md

Execute the skills-check check command directly without global installation using npx.

```bash
npx skills-check check
```

--------------------------------

### Run skills-check check --ci

Source: https://github.com/voodootikigod/skills-check/blob/main/README.md

Use this command to check skill freshness in a CI environment. Ensure the skills-check tool is installed via npm.

```yaml
- name: Check skill freshness
  run: npx skills-check check --ci
```

--------------------------------

### PR gate configuration

Source: https://github.com/voodootikigod/skills-check/blob/main/README.md

Standard PR gate setup with issue reporting disabled.

```yaml
- uses: voodootikigod/skills-check@v1
  with:
    commands: check,audit,lint
    open-issues: "false"
    fail-on-stale: "true"
    audit-fail-on: high
    lint-fail-on: error
```

--------------------------------

### Generate Skill Fingerprint Registry

Source: https://github.com/voodootikigod/skills-check/blob/main/README.md

Creates a fingerprint registry of installed skills for integrity verification. Options include specifying an output file, injecting watermarks, outputting as JSON, enabling CI mode for strict exit codes, and controlling verbosity or quiet output.

```bash
skills-check fingerprint
```

```bash
skills-check fingerprint ./skills --json
```

```bash
skills-check fingerprint ./skills -o fingerprints.json
```

```bash
skills-check fingerprint ./skills --inject-watermarks
```

```bash
skills-check fingerprint --quiet
```

--------------------------------

### Check Skills Against Policy

Source: https://github.com/voodootikigod/skills-check/blob/main/README.md

Use this command to verify installed skills against organizational policy. Flags allow specifying a custom policy file, filtering by skill name, enabling CI mode for strict exit codes, setting output formats, defining a report file path, and setting a failure threshold based on severity.

```bash
skills-check policy check
```

```bash
skills-check policy check --policy ./my-policy.yml
```

```bash
skills-check policy check --ci --fail-on violation
```

--------------------------------

### Initialize Policy File

Source: https://github.com/voodootikigod/skills-check/blob/main/README.md

Generates a starter `.skill-policy.yml` file. Use the `-o` flag to specify the output path for the new policy file.

```bash
skills-check policy init
```

--------------------------------

### Policy Initialization

Source: https://github.com/voodootikigod/skills-check/blob/main/PLAN.md

Generates a starter policy configuration.

```APIDOC
## generateStarterPolicy

### Description
Generates a YAML template with common defaults for a new policy file.

### Response
- **string** - A YAML formatted string containing the starter policy template.
```

--------------------------------

### Initialize a Registry

Source: https://github.com/voodootikigod/skills-check/blob/main/packages/cli/README.md

Create a skills-check.json registry file by scanning a directory for skill mappings.

```bash
# Interactive — prompts for each mapping
skills-check init ./skills

# Non-interactive — auto-detects common packages
skills-check init ./skills --yes
```

--------------------------------

### Initialize skills-check registry interactively

Source: https://github.com/voodootikigod/skills-check/blob/main/README.md

Scan a skills directory and interactively map products to npm packages to create a skills-check.json registry file.

```bash
skills-check init ./skills
```

--------------------------------

### CLI Reference: init

Source: https://github.com/voodootikigod/skills-check/blob/main/packages/cli/README.md

Initializes a skills-check registry by scanning a skills directory and mapping products to npm packages.

```APIDOC
## `skills-check init [dir]`

Scan a skills directory and generate a `skills-check.json` registry.

### Parameters

#### Path Parameters

- **dir** (string) - Required - The path to the skills directory.

#### Flags

- **-y, --yes** (boolean) - Non-interactive mode, auto-detect package mappings.
- **-o, --output <path>** (string) - Output path for registry file.
```

--------------------------------

### CLI Reference: init

Source: https://github.com/voodootikigod/skills-check/blob/main/README.md

Initializes a skills-check registry by scanning a skills directory.

```APIDOC
## `skills-check init [dir]`

Scan a skills directory and generate a `skills-check.json` registry.

### Parameters

#### Flags

- **`-y, --yes`** (boolean) - Non-interactive mode, auto-detect package mappings.
- **`-o, --output <path>`** (string) - Output path for registry file.
```

--------------------------------

### Initialize registry with output path

Source: https://github.com/voodootikigod/skills-check/blob/main/README.md

Initialize the skills-check registry and specify a custom output path for the registry file using the --output flag.

```bash
skills-check init [dir] -o <path>
```

--------------------------------

### Generate starter policy

Source: https://github.com/voodootikigod/skills-check/blob/main/PLAN.md

Creates a YAML template with default policy configurations.

```typescript
export function generateStarterPolicy(): string;
```

--------------------------------

### Run test suites with skills-check

Source: https://context7.com/voodootikigod/skills-check/llms.txt

Execute test suites using various agent harnesses, trial counts, and cost constraints.

```bash
skills-check test --agent claude-code
skills-check test --agent generic --agent-cmd "my-agent run {prompt}"
skills-check test --trials 3 --pass-threshold 2
skills-check test --timeout 60
skills-check test --max-cost 5.00
skills-check test --update-baseline
skills-check test --ci
skills-check test --provider anthropic --model claude-sonnet-4-20250514
```

--------------------------------

### Programmatic API Usage

Source: https://context7.com/voodootikigod/skills-check/llms.txt

Use the TypeScript API to perform audits, linting, budget analysis, and policy checks programmatically. Ensure the package is installed and imported from 'skills-check/api'.

```typescript
import {
  runAudit,
  runLint,
  runBudget,
  runPolicyCheck,
  runVerify,
  runTests,
  discoverSkillFiles,
  loadConfig,
  createProgress
} from "skills-check/api";

// Discover skill files in a directory
const skillFiles = await discoverSkillFiles("./skills");
console.log(`Found ${skillFiles.length} skill files`);

// Run security audit
const auditReport = await runAudit(["./skills"], {
  failOn: "high",
  skipUrls: true,
  packagesOnly: false
});

console.log(`Audit: ${auditReport.summary.total} findings`);
console.log(`  Critical: ${auditReport.summary.critical}`);
console.log(`  High: ${auditReport.summary.high}`);

for (const finding of auditReport.findings) {
  console.log(`[${finding.severity}] ${finding.file}:${finding.line} - ${finding.message}`);
}

// Run linting with auto-fix
const lintReport = await runLint(["./skills"], {
  fix: true,
  failOn: "error"
});

console.log(`Lint: ${lintReport.errors} errors, ${lintReport.warnings} warnings`);
console.log(`Fixed: ${lintReport.fixed} issues`);

// Analyze token budget
const budgetReport = await runBudget(["./skills"], {
  detailed: true,
  model: "claude-sonnet"
});

console.log(`Total tokens: ${budgetReport.totalTokens}`);
console.log(`Cost per 1K loads: $${budgetReport.cost.costPer1KLoads.toFixed(4)}`);

for (const skill of budgetReport.skills) {
  console.log(`  ${skill.name}: ${skill.totalTokens} tokens`);
}

// Check redundancy
for (const match of budgetReport.redundancy) {
  console.log(`Overlap detected: ${match.nameA} <-> ${match.nameB}`);
  console.log(`  Similarity: ${(match.similarity * 100).toFixed(1)}%`);
  console.log(`  Suggestion: ${match.suggestion}`);
}

// Run policy check
const policy = {
  version: 1,
  sources: { allow: ["@company/*"] },
  freshness: { max_age_days: 90 }
};

const policyReport = await runPolicyCheck(
  ["./skills"],
  policy,
  ".skill-policy.yml"
);

console.log(`Policy: ${policyReport.summary.blocked} blocked, ${policyReport.summary.violations} violations`);

// Verify version bumps
const verifyReport = await runVerify({
  all: true,
  skipLlm: false,
  provider: "anthropic"
});

console.log(`Verify: ${verifyReport.summary.passed} passed, ${verifyReport.summary.failed} failed`);

// Load configuration
const config = await loadConfig(process.cwd());
console.log(`Default format: ${config.format}`);
```

--------------------------------

### Initialize skills-check Registry

Source: https://context7.com/voodootikigod/skills-check/llms.txt

Create a skills-check.json registry file by scanning a skills directory. Supports interactive and non-interactive modes, and custom output paths.

```bash
# Interactive mode — prompts for each mapping
skills-check init ./skills
```

```bash
# Non-interactive mode — auto-detects common packages
skills-check init ./skills --yes
```

```bash
# Custom output path
skills-check init ./skills -o ./config/skills-check.json
```

--------------------------------

### Create New Issues

Source: https://github.com/voodootikigod/skills-check/blob/main/AGENTS.md

Commands to initialize new tasks or bugs with dependencies.

```bash
bd create "Issue title" --description="Detailed context" -t bug|feature|task -p 0-4 --json
bd create "Issue title" --description="What this issue is about" -p 1 --deps discovered-from:bd-123 --json
```

--------------------------------

### Initialize skills-check registry non-interactively

Source: https://github.com/voodootikigod/skills-check/blob/main/README.md

Scan a skills directory and auto-detect common package mappings to create a skills-check.json registry file.

```bash
skills-check init ./skills --yes
```

--------------------------------

### Quick Reference for bd Commands

Source: https://github.com/voodootikigod/skills-check/blob/main/AGENTS.md

Basic commands for managing issues within the beads system.

```bash
bd ready              # Find available work
bd show <id>          # View issue details
bd update <id> --claim  # Claim work atomically
bd close <id>         # Complete work
bd sync               # Sync with git
```

--------------------------------

### Build All Packages with pnpm

Source: https://github.com/voodootikigod/skills-check/blob/main/CLAUDE.md

Builds all packages in the monorepo, respecting the dependency order defined by Turborepo.

```bash
pnpm run build
```

--------------------------------

### Accessing results output

Source: https://github.com/voodootikigod/skills-check/blob/main/README.md

Demonstrates how to reference the action's results output in a subsequent step.

```yaml
- uses: voodootikigod/skills-check@v1
  id: skills-check
  with:
    commands: check,audit
- run: echo "Results: ${{ steps.skills-check.outputs.results }}"
```

--------------------------------

### Biome Formatting Command

Source: https://github.com/voodootikigod/skills-check/blob/main/CLAUDE.md

Run the Biome formatter before committing to ensure consistent line-length wrapping.

```bash
npx biome check --write
```

--------------------------------

### Run skills-check Command

Source: https://context7.com/voodootikigod/skills-check/llms.txt

Detect version drift by comparing skill frontmatter against the npm registry. Supports various options for custom paths, output formats, and CI integration.

```bash
# Basic check
skills-check check
```

```bash
# Check with custom registry path
skills-check check --registry ./config/skills-check.json
```

```bash
# Check a single product
skills-check check --product ai-sdk
```

```bash
# JSON output for automation
skills-check check --json
```

```bash
# CI mode — exit code 1 if any stale products found
skills-check check --ci
```

```bash
# Show all products including current ones
skills-check check --verbose
```

--------------------------------

### Run a Single Test File

Source: https://github.com/voodootikigod/skills-check/blob/main/CLAUDE.md

Navigates to the CLI package directory and runs a specific test file using Vitest.

```bash
cd packages/cli && pnpm vitest run src/severity.test.ts
```

--------------------------------

### Run skills-check budget --max-tokens 50000 --format json

Source: https://github.com/voodootikigod/skills-check/blob/main/README.md

Check the token budget for skills, setting a maximum of 50,000 tokens and outputting results in JSON format. Useful for cost management.

```yaml
- name: Check token budget
  run: npx skills-check budget --max-tokens 50000 --format json
```

--------------------------------

### Check Ready Work with JSON Output

Source: https://github.com/voodootikigod/skills-check/blob/main/AGENTS.md

Retrieve available tasks in a machine-readable format.

```bash
bd ready --json
```

--------------------------------

### POST /testing/run

Source: https://github.com/voodootikigod/skills-check/blob/main/PLAN.md

Orchestrates the execution of testable skills by discovering cases, running agent trials, and aggregating results.

```APIDOC
## POST /testing/run

### Description
Orchestrates the full test lifecycle: discovers skills, parses cases, executes agent trials via a harness, and runs graders to produce a test report.

### Method
POST

### Endpoint
/testing/run

### Parameters
#### Request Body
- **dir** (string) - Required - The directory path containing testable skills.
- **options** (TestOptions) - Required - Configuration for test execution including trials, timeout, and threshold settings.
```

--------------------------------

### POST /testing/harness/execute

Source: https://github.com/voodootikigod/skills-check/blob/main/PLAN.md

Executes a prompt using a configured agent harness (e.g., Claude Code, Generic Shell, or Mock).

```APIDOC
## POST /testing/harness/execute

### Description
Executes a prompt within a specific working directory using the selected agent harness implementation.

### Method
POST

### Endpoint
/testing/harness/execute

### Parameters
#### Request Body
- **prompt** (string) - Required - The instruction prompt for the agent.
- **options** (object) - Required - Execution context including workDir, timeout, and optional skills list.
```

--------------------------------

### Analyze skill token budget

Source: https://github.com/voodootikigod/skills-check/blob/main/README.md

Measure token usage and detect redundancy across skill files.

```bash
# Analyze all skills in current directory
skills-check budget

# Detailed per-section breakdown
skills-check budget ./skills --detailed

# Fail if total tokens exceed 50k
skills-check budget --max-tokens 50000

# Save a baseline snapshot
skills-check budget --save baseline.json

# Compare against a saved baseline
skills-check budget --compare baseline.json

# JSON output for CI
skills-check budget --format json
```

--------------------------------

### Check for Staleness

Source: https://github.com/voodootikigod/skills-check/blob/main/packages/cli/README.md

Run the check command to identify stale product versions.

```bash
skills-check check
```

--------------------------------

### Full quality gate configuration

Source: https://github.com/voodootikigod/skills-check/blob/main/README.md

Executes multiple analysis commands with specific thresholds for audit, lint, and budget.

```yaml
- uses: voodootikigod/skills-check@v1
  with:
    commands: check,audit,lint,budget
    audit-fail-on: high
    lint-fail-on: error
    budget-max-tokens: 50000
    fail-on-stale: "true"
```

--------------------------------

### Check with verbose output

Source: https://github.com/voodootikigod/skills-check/blob/main/README.md

Run the check command with verbose output to display all products, including those that are currently up-to-date.

```bash
skills-check check -v
```

--------------------------------

### Check a single product

Source: https://github.com/voodootikigod/skills-check/blob/main/README.md

Perform a staleness check for a specific product by providing its name using the --product flag.

```bash
skills-check check -p <name>
```

--------------------------------

### Run skills-check fingerprint --json -o fingerprints.json

Source: https://github.com/voodootikigod/skills-check/blob/main/README.md

Generate skill fingerprints in JSON format and save them to 'fingerprints.json'. This is useful for tracking skill versions and dependencies.

```yaml
- name: Generate skill fingerprints
  run: npx skills-check fingerprint --json -o fingerprints.json
```

--------------------------------

### Lint All Packages with Biome

Source: https://github.com/voodootikigod/skills-check/blob/main/CLAUDE.md

Applies linting rules to all packages in the monorepo using Biome.

```bash
pnpm run lint
```

--------------------------------

### Agent Harness Implementations

Source: https://github.com/voodootikigod/skills-check/blob/main/PLAN.md

Concrete implementations for different agent execution strategies.

```typescript
export class ClaudeCodeHarness implements AgentHarness { ... }
```

```typescript
export class GenericHarness implements AgentHarness { ... }
```

```typescript
export class MockHarness implements AgentHarness { ... }
```

--------------------------------

### Skill Frontmatter

Source: https://github.com/voodootikigod/skills-check/blob/main/packages/cli/README.md

How skills declare their product version using YAML frontmatter.

```APIDOC
## Skill Frontmatter

Skills declare their product version in YAML frontmatter:

```yaml
---
name: ai-sdk-core
product-version: "6.0.105"
---
```

The `init` command reads this field and groups skills by shared version + name prefix.
```

--------------------------------

### Declare Multiple Dependencies in YAML

Source: https://context7.com/voodootikigod/skills-check/llms.txt

List multiple dependencies for a skill by separating them with commas within the 'compatibility' field in the YAML frontmatter.

```yaml
---
name: fullstack-next
compatibility: "next@^15.0.0, react@^19.0.0, ai@^6.0.0"
---

```

--------------------------------

### Verify skill versioning

Source: https://github.com/voodootikigod/skills-check/blob/main/README.md

Validate that semver bumps align with actual content changes in skill files.

```bash
# Verify all skills
skills-check verify --all

# Verify a single skill
skills-check verify --skill ./skills/react/SKILL.md

# Compare two specific versions
skills-check verify --before v1/SKILL.md --after v2/SKILL.md

# Suggest the appropriate bump level
skills-check verify --all --suggest

# Skip LLM (heuristic-only mode)
skills-check verify --all --skip-llm
```

--------------------------------

### Run skills-check usage --store file://telemetry.jsonl --check-policy --ci

Source: https://github.com/voodootikigod/skills-check/blob/main/README.md

Analyze skill usage, storing telemetry in 'telemetry.jsonl', checking policies, and running in a CI environment. Useful for monitoring and compliance.

```yaml
- name: Analyze skill usage
  run: npx skills-check usage --store file://telemetry.jsonl --check-policy --ci
```

--------------------------------

### Run Tests with pnpm

Source: https://github.com/voodootikigod/skills-check/blob/main/CLAUDE.md

Executes tests for the CLI package using Vitest.

```bash
pnpm test
```

--------------------------------

### Project-Level Configuration in .skillscheckrc.yml

Source: https://context7.com/voodootikigod/skills-check/llms.txt

Define project-level default configurations for skills-check in a .skillscheckrc.yml file. This includes settings for formatting, auditing, linting, budgeting, policy, and verification.

```yaml
format: terminal

audit:
  failOn: high
  skipUrls: false

lint:
  failOn: error
  fix: false

budget:
  maxTokens: 100000
  model: claude-sonnet
  detailed: false

policy:
  failOn: violation
  policyPath: .skill-policy.yml

verify:
  skipLlm: false
  provider: anthropic

test:
  agent: generic
  trials: 3
  timeout: 30
```

--------------------------------

### Run CLI Usage Command with Telemetry Store

Source: https://github.com/voodootikigod/skills-check/blob/main/CLAUDE.md

Executes the 'usage' command of the skills-check CLI tool during development, specifying a local file for telemetry data.

```bash
cd packages/cli && pnpm tsx src/index.ts usage --store file://telemetry.jsonl
```

--------------------------------

### Create deduplication label

Source: https://github.com/voodootikigod/skills-check/blob/main/README.md

CLI command to create the required GitHub label for issue tracking.

```bash
gh label create skill-staleness --color "#e4e669" --description "Skill version drift detected"
```

--------------------------------

### Lint skill files for quality and format

Source: https://context7.com/voodootikigod/skills-check/llms.txt

Validate metadata completeness, structural quality, and format in skill files with auto-fix capabilities. Use --fix to auto-fix missing fields from git context and --inject-watermarks to inject fingerprint watermarks during fix.

```bash
# Lint all skills in current directory
skills-check lint
```

```bash
# Auto-fix missing fields from git context
skills-check lint --fix
```

```bash
# Inject fingerprint watermarks during fix
skills-check lint --fix --inject-watermarks
```

```bash
# CI mode with strict validation
skills-check lint --ci
```

```bash
# Custom fail threshold
skills-check lint --fail-on warning
```

```bash
# JSON output
skills-check lint --format json
```

```bash
# SARIF for GitHub integration
skills-check lint --format sarif -o lint-results.sarif
```

--------------------------------

### Dependency Graph

Source: https://github.com/voodootikigod/skills-check/blob/main/PLAN.md

Visual representation of the task dependencies for the implementation waves.

```text
ss-0dh.6 (shared infra) ──┬──> ss-0dh.1 (budget)
                           ├──> ss-0dh.2 (verify)
                           └──> ss-0dh.3 (lint)

ss-0dh.2 (verify) ──> ss-0dh.5 (test) [future]
```

--------------------------------

### AI-Assisted Refresh

Source: https://github.com/voodootikigod/skills-check/blob/main/packages/cli/README.md

Use an LLM to propose updates to stale skill files.

```bash
# Interactive — review each change
skills-check refresh ./skills

# Auto-apply all changes
skills-check refresh -y

# Preview only (no writes)
skills-check refresh --dry-run
```

--------------------------------

### Product Reference Detection

Source: https://github.com/voodootikigod/skills-check/blob/main/PLAN.md

Interface for detecting product references within skill content.

```typescript
export function detectsProduct(content: string): boolean;
```

--------------------------------

### Fingerprint skills for integrity

Source: https://context7.com/voodootikigod/skills-check/llms.txt

Generate a registry of skills with content hashes and watermarks for verification.

```bash
skills-check fingerprint
skills-check fingerprint ./skills --json
skills-check fingerprint ./skills -o fingerprints.json
skills-check fingerprint ./skills --inject-watermarks
skills-check fingerprint --quiet --ci
```

--------------------------------

### CLI Reference: check

Source: https://github.com/voodootikigod/skills-check/blob/main/packages/cli/README.md

Checks skill versions against the npm registry for staleness.

```APIDOC
## `skills-check check`

Check skill versions against the npm registry.

### Parameters

#### Flags

- **-r, --registry <path>** (string) - Path to registry file (default: `./skills-check.json`).
- **-p, --product <name>** (string) - Check a single product.
- **--json** (boolean) - Machine-readable JSON output.
- **-v, --verbose** (boolean) - Show all products including current.
- **--ci** (boolean) - Exit code 1 if any stale products found.
```

--------------------------------

### Skill Frontmatter Declaration

Source: https://github.com/voodootikigod/skills-check/blob/main/packages/cli/README.md

YAML frontmatter used in skill files to declare the product version.

```yaml
---
name: ai-sdk-core
product-version: "6.0.105"
---
```

--------------------------------

### Session Completion Workflow

Source: https://github.com/voodootikigod/skills-check/blob/main/AGENTS.md

Mandatory steps to sync and push changes before ending a session.

```bash
git pull --rebase
bd sync
git push
git status  # MUST show "up to date with origin"
```

--------------------------------

### Ignore all hallucinated package findings

Source: https://github.com/voodootikigod/skills-check/blob/main/README.md

Create a .skills-checkignore file with a rule to ignore all 'hallucinated-package' findings.

```bash
# Ignore all hallucinated-package findings
hallucinated-package
```

--------------------------------

### CLI Reference: refresh

Source: https://github.com/voodootikigod/skills-check/blob/main/packages/cli/README.md

Uses an LLM to propose targeted updates to stale skill files.

```APIDOC
## `skills-check refresh [skills-dir]`

Use an LLM to propose targeted updates to stale skill files.

### Parameters

#### Path Parameters

- **skills-dir** (string) - Optional - The directory containing the skills.

#### Flags

- **-r, --registry <path>** (string) - Path to registry file.
- **-p, --product <name>** (string) - Refresh a single product.
- **--provider <name>** (string) - LLM provider: `anthropic`, `openai`, `google`.
- **--model <id>** (string) - Specific model ID (e.g. `claude-sonnet-4-20250514`).
- **-y, --yes** (boolean) - Auto-apply without confirmation.
- **--dry-run** (boolean) - Show proposed changes, write nothing.
```

--------------------------------

### Mock Executable File Function

Source: https://github.com/voodootikigod/skills-check/blob/main/PLAN.md

This is a mock implementation of `execFile`, likely used for testing purposes to simulate shell command execution.

```typescript
// mock execFile
```

--------------------------------

### Run Skill Tests

Source: https://github.com/voodootikigod/skills-check/blob/main/README.md

Executes evaluation test suites found in skill `tests/` directories. Supports various flags for filtering tests by skill name or type, specifying agent harnesses, setting output formats, defining report paths, configuring trial runs, pass thresholds, timeouts, budget caps, and enabling CI mode for regression detection.

```bash
skills-check test
```

```bash
skills-check test --skill react-patterns
```

```bash
skills-check test --dry
```

```bash
skills-check test --ci
```

```bash
skills-check test --max-cost 5.00
```

```bash
skills-check test --agent claude-code
```

--------------------------------

### Refresh stale skill files

Source: https://context7.com/voodootikigod/skills-check/llms.txt

Use LLMs to propose and apply updates to skill files.

```bash
skills-check refresh ./skills
skills-check refresh ./skills --product ai-sdk
skills-check refresh --dry-run
skills-check refresh ./skills --yes
skills-check refresh --provider anthropic --model claude-sonnet-4-20250514
skills-check refresh --provider openai
skills-check refresh --provider google
```

--------------------------------

### Audit skills with skills-check

Source: https://github.com/voodootikigod/skills-check/blob/main/README.md

Run audits on skill files with support for different output formats and filtering options.

```bash
# Audit all skills in current directory
skills-check audit

# JSON output for CI
skills-check audit ./skills --format json

# SARIF for GitHub Security tab
skills-check audit ./skills --format sarif -o results.sarif

# Write markdown report to file
skills-check audit ./skills --format markdown -o audit-report.md

# Only check package registries (fastest)
skills-check audit ./skills --packages-only

# Skip slow URL checks
skills-check audit ./skills --skip-urls

# Fail only on critical findings
skills-check audit --fail-on critical

# Quiet mode for CI (exit code only)
skills-check audit --quiet --fail-on high
```

--------------------------------

### Analyze token cost of skills

Source: https://context7.com/voodootikigod/skills-check/llms.txt

Measure token cost and detect redundancy in skill files. Analyzes context window consumption and identifies overlap between skills. Use --detailed for a per-section breakdown.

```bash
# Analyze all skills in current directory
skills-check budget
```

```bash
# Detailed per-section breakdown
skills-check budget ./skills --detailed
```

```bash
# Analyze a specific skill
skills-check budget --skill ai-sdk-core
```

```bash
# Fail if total tokens exceed threshold
skills-check budget --max-tokens 50000
```

```bash
# Save a baseline snapshot
skills-check budget --save baseline.json
```

```bash
# Compare against a saved baseline
skills-check budget --compare baseline.json
```

```bash
# JSON output for CI
skills-check budget --format json
```

```bash
# Specify model for cost estimation
skills-check budget --model claude-sonnet
```

```bash
# Markdown report
skills-check budget --format markdown -o budget-report.md
```

--------------------------------

### Audit and write report to file

Source: https://github.com/voodootikigod/skills-check/blob/main/README.md

Perform an audit and write the report to a specified file path using the --output flag.

```bash
skills-check audit -o <path>
```

--------------------------------

### Refresh Skill Files with LLM

Source: https://github.com/voodootikigod/skills-check/blob/main/README.md

Use an LLM to propose targeted updates to stale skill files. Fetches changelogs, generates diffs, and optionally applies changes. Configure LLM provider and model, and use flags for auto-apply or dry-run.

```bash
# Anthropic (Claude)
npm install @ai-sdk/anthropic
export ANTHROPIC_API_KEY=sk-...
```

```bash
# OpenAI
npm install @ai-sdk/openai
export OPENAI_API_KEY=sk-...
```

```bash
# Google (Gemini)
npm install @ai-sdk/google
export GOOGLE_GENERATIVE_AI_API_KEY=...
```

--------------------------------

### Add 'test' Command Registration

Source: https://github.com/voodootikigod/skills-check/blob/main/PLAN.md

This snippet indicates where the 'test' command should be registered within the CLI's main entry point.

```typescript
// Add `test` command registration.
```

--------------------------------

### Compare Package References

Source: https://github.com/voodootikigod/skills-check/blob/main/PLAN.md

Detects additions, removals, and renames of packages between two versions.

```typescript
export interface PackageDiff {
  added: string[];
  removed: string[];
  renamed: Array<{ from: string; to: string }>;
}

export function packageDiff(before: string, after: string): PackageDiff;
```

--------------------------------

### Declare Skill Compatibility in YAML

Source: https://context7.com/voodootikigod/skills-check/llms.txt

Specify the product version compatibility for a skill using the 'compatibility' field in the YAML frontmatter. This is the preferred method over the legacy 'product-version' field.

```yaml
---
name: ai-sdk-core
description: "Generate text with Vercel AI SDK using streamText and generateText"
compatibility: "ai@^6.0.0"
author: "Your Name"
license: MIT
repository: https://github.com/your-org/skills
---

# AI SDK Core

Instructions for using the Vercel AI SDK...
```

--------------------------------

### Run skills-check lint --ci --fail-on error

Source: https://github.com/voodootikigod/skills-check/blob/main/README.md

Lint skill metadata in a CI environment, failing on any errors. This ensures metadata consistency and quality.

```yaml
- name: Lint skill metadata
  run: npx skills-check lint --ci --fail-on error
```

--------------------------------

### Define pricing model interfaces

Source: https://github.com/voodootikigod/skills-check/blob/main/PLAN.md

Structures for managing cost estimation based on token usage.

```typescript
export interface PricingModel {
  name: string;
  inputPer1MTok: number;
}

export const PRICING: Record<string, PricingModel>;

export function estimateCost(tokens: number, model: string, callsPer1K?: number): number;
```

--------------------------------

### Run health checks

Source: https://context7.com/voodootikigod/skills-check/llms.txt

Execute audit, lint, budget, and policy checks as a unified CI gate.

```bash
skills-check health
skills-check health --max-tokens 100000
skills-check health --skip-audit
skills-check health --skip-lint
skills-check health --skip-budget
skills-check health --skip-policy
skills-check health --format json -o health-report.json
```

--------------------------------

### GitHub Action Integration

Source: https://context7.com/voodootikigod/skills-check/llms.txt

Configure the skills-check GitHub Action in your workflow file to automate quality gates. Supports various command combinations and output access.

```yaml
name: Skill Quality Check
on:
  push:
    branches: [main]
  pull_request:
  schedule:
    - cron: "0 9 * * 1"  # Monday 09:00 UTC

permissions:
  contents: read
  issues: write

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # Full quality gate with multiple commands
      - uses: voodootikigod/skills-check@v1
        with:
          commands: check,audit,lint,budget
          audit-fail-on: high
          lint-fail-on: error
          budget-max-tokens: 50000
          fail-on-stale: "true"

      # Or use individual toggles
      - uses: voodootikigod/skills-check@v1
        with:
          check: "true"
          audit: "true"
          lint: "true"
          audit-fail-on: critical

      # Security-focused PR gate
      - uses: voodootikigod/skills-check@v1
        with:
          commands: audit,lint
          audit-fail-on: medium
          lint-fail-on: warning
          open-issues: "false"

      # Policy enforcement
      - uses: voodootikigod/skills-check@v1
        with:
          commands: policy
          policy-file: .skill-policy.yml
          policy-fail-on: violation

      # Access outputs
      - uses: voodootikigod/skills-check@v1
        id: skills-check
        with:
          commands: check,audit
      - run: |
          echo "Stale count: ${{ steps.skills-check.outputs.stale-count }}"
          echo "Results: ${{ steps.skills-check.outputs.results }}"
```

--------------------------------

### Lint skill files

Source: https://github.com/voodootikigod/skills-check/blob/main/README.md

Validate metadata and structure, with optional auto-fix capabilities.

```bash
# Lint all skills in current directory
skills-check lint

# Auto-fix missing metadata
skills-check lint --fix

# CI mode with warning threshold
skills-check lint --ci --fail-on warning

# JSON output
skills-check lint --format json
```

--------------------------------

### Verify skill version bumps

Source: https://context7.com/voodootikigod/skills-check/llms.txt

Verify that skill version bumps match content changes. Validates that the declared semver bump (major/minor/patch) is appropriate for the actual content diff. Use --suggest to suggest an appropriate bump level and --skip-llm to use heuristic-only mode.

```bash
# Verify all skills
skills-check verify --all
```

```bash
# Verify a single skill
skills-check verify --skill ./skills/react/SKILL.md
```

```bash
# Compare two specific versions
skills-check verify --before v1/SKILL.md --after v2/SKILL.md
```

```bash
# Suggest appropriate bump level
skills-check verify --all --suggest
```

```bash
# Skip LLM (heuristic-only mode)
skills-check verify --all --skip-llm
```

```bash
# Use specific LLM provider
skills-check verify --all --provider anthropic --model claude-sonnet-4-20250514
```

```bash
# JSON output
skills-check verify --format json
```

--------------------------------

### GitHub Actions Integration

Source: https://github.com/voodootikigod/skills-check/blob/main/README.md

The `voodootikigod/skills-check` GitHub Action runs skills-check commands in your CI pipeline. Configure commands and failure thresholds via inputs.

```yaml
- uses: voodootikigod/skills-check@v1
  with:
    commands: check,audit,lint,budget
    audit-fail-on: high
    lint-fail-on: error
    budget-max-tokens: 50000
```

--------------------------------

### Auto-fix Lint and Format Issues with Biome

Source: https://github.com/voodootikigod/skills-check/blob/main/CLAUDE.md

Automatically fixes linting and formatting issues across the project using Biome.

```bash
pnpm biome check --write .
```

--------------------------------

### Linting Rules and Logic

Source: https://github.com/voodootikigod/skills-check/blob/main/PLAN.md

Details on the different rule sets and detection mechanisms used by the lint command.

```APIDOC
## Linting Rules and Detection

### Rule Sets

- **Required Rules**: Fields that must always be present.
  - `name` (string, max 100 chars)
  - `description` (string, 20-500 chars)
  - Implemented by `packages/cli/src/lint/rules/required.ts`.

- **Publish Rules**: Fields required for publishing.
  - `author` (string, non-empty)
  - `license` (string, valid SPDX identifier)
  - `repository` (string, valid URL)
  - Implemented by `packages/cli/src/lint/rules/publish.ts`.

- **Conditional Rules**: Fields required based on content.
  - `product-version`: Required if content references a versioned product.
  - `agents`: Required if content has agent-specific instructions.
  - Implemented by `packages/cli/src/lint/rules/conditional.ts`.

- **Recommended Rules**: Fields that are recommended but not strictly required.
  - `spec-version` (string)
  - `keywords` (array with at least 1 item)
  - Implemented by `packages/cli/src/lint/rules/recommended.ts`.

- **Format Rules**: Validates the format of specific fields.
  - `product-version`: Must be valid semver.
  - `repository`: Must be a valid URL.
  - `license`: Must be a valid SPDX identifier.
  - `name`: Must not contain special characters.
  - Implemented by `packages/cli/src/lint/rules/format.ts`.

### Detection Mechanisms

- **Product References Detection**: Detects if skill content references a product.
  - Matches patterns like "Product Name X.Y", `npm install <pkg>`, `pip install <pkg>`.
  - Uses audit extractors to find package references.
  - Implemented by `packages/cli/src/lint/detection/product-refs.ts`.

- **Agent-Specific Instructions Detection**: Detects if content contains agent-specific instructions.
  - Matches phrases like "In Claude Code", "In Cursor", "For Codex", and agent-specific CLI commands.
  - Implemented by `packages/cli/src/lint/detection/agent-specific.ts`.

### Autofix Logic

- The `autofix` function in `packages/cli/src/lint/autofix.ts` attempts to fix missing fields:
  - `author`: Populated from `git config user.name`.
  - `repository`: Populated from `git remote get-url origin`.
  - `license`: Inserts `"MIT"` with a TODO comment.
- Returns the new file content or `null` if no fixes were made.
- Uses `gray-matter` for frontmatter manipulation.

### SPDX License Validation

- The `isValidSpdx` function in `packages/cli/src/lint/spdx.ts` validates SPDX license identifiers.
- Supports common identifiers (MIT, Apache-2.0, etc.) and SPDX expressions (OR/AND).

### Reporters

- **Terminal Reporter**: Provides per-file output with icons, field names, and messages (`packages/cli/src/lint/reporters/terminal.ts`).
- **JSON Reporter**: Outputs the full lint report in JSON format (`packages/cli/src/lint/reporters/json.ts`).

```