claude-skill-lint 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Robin Cannon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,383 @@
+# claude-skill-lint
+
+Structural validation and token-efficiency tooling for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) skills. Catches the bugs that Claude tolerates but your users pay for.
+
+## The Problem No One Sees
+
+Claude Code skills load into the context window on every invocation. When a skill references a context file that doesn't exist, Claude doesn't throw an error. It hallucinates the missing context and keeps going. When two skills resolve to the same install path, one silently overwrites the other. When a context file is loaded but nothing references it, you're burning tokens for nothing.
+
+These aren't hypothetical failure modes. They're what we found running claude-skill-lint against a real 139-file production suite:
+
+- **32 broken references.** 23 skills referenced a context file that's generated at setup time — in the shareable repo, before setup runs, those skills have no context at all. 9 more referenced a file that had been renamed months earlier. Every one of those skills was silently degraded.
+- **11 orphaned files.** Context and agent files loaded into the window but referenced by zero skills. Dead weight on every invocation.
+- **1 dependency cycle.** Two context files referencing each other, pulling both into the window when only one was needed.
+
+Caught in under two seconds. No LLM calls. Deterministic.
+
+"Tolerate" is not "work correctly."
+
+## Two Layers
+
+| | `claude-skill-lint` | `/te-review` |
+|-|-------------|-------------|
+| **What** | Structural validation | Token efficiency audit |
+| **Speed** | <2s, every PR | ~60s, on demand |
+| **Approach** | Deterministic CI — no LLM | LLM-powered deep analysis |
+| **Catches** | Broken refs, orphans, cycles, collisions, parse errors, size violations, quality regressions | Redundant content, output format waste, instruction bloat, model routing, architecture-level optimization |
+
+claude-skill-lint enforces the structural foundation. `/te-review` (included in [`skills/te-review.md`](skills/te-review.md)) goes deeper — four-pass analysis across architecture, efficiency, and instruction quality, producing a scored assessment (0-24) with a prioritized optimization plan and estimated token savings per fix.
+
+We ran te-review against itself. It scored 20/24. The main finding: the skill didn't constrain its own output the way it tells others to. After adding "top 5 findings per category" and "each subagent returns top 10 findings only," estimated output token savings on large suite reviews dropped by ~50%. The tool practices what it preaches.
+
+Install the deep audit skill:
+
+```bash
+cp node_modules/claude-skill-lint/skills/te-review.md ~/.claude/commands/te-review.md
+```
+
+Then in any Claude Code session:
+
+```
+/te-review suite                    # Full suite audit (scored 0-24)
+/te-review audit my-skill           # Single skill deep dive
+/te-review compare old.md new.md    # Before/after token impact
+```
+
+### What te-review checks
+
+Four sequential passes, each producing up to 5 findings per severity level:
+
+1. **Structural Audit** — CLAUDE.md bloat, unused tool declarations, reference depth, subagent model routing, file size
+2. **Redundancy Detection** — skill-context overlap, cross-skill duplication, CLAUDE.md-skill overlap. High-fanout context files are flagged as highest-ROI optimization targets.
+3. **Output Efficiency** — missing format constraints, missing conciseness directives, unbounded output sections, prose where structured would suffice. Output tokens cost 5x input — this pass often finds the biggest savings.
+4. **Instruction Quality** — motivational fluff, politeness tokens, filler phrases, default-behavior instructions, conflicting constraints, emphasis overuse
+
+## What It Actually Found
+
+### Against a 139-file shared skill suite
+
+```
+$ claude-skill-lint graph .
+✖ 43 errors and 11 warnings in 54 files (139 files checked)
+```
+
+The headline: `inv-output-conventions.md` was renamed to `inv-output-patterns.md` at some point. Nine invention skills still referenced the old name. They silently got no output formatting guidance. A rename bug, invisible at authoring time, caught in seconds.
+
+### Against Anthropic's official skills repo (plugin format)
+
+```
+$ claude-skill-lint graph ~/Development/anthropic-skills/
+✖ 19 errors and 10 warnings in 26 files (63 files checked)
+```
+
+Name-collision findings in the `claude-api` skill — five language-specific `claude-api.md` files (PHP, Java, Ruby, Go, C#) all resolve to the same canonical name. Broken references to `shared/tool-use-concepts.md` and `shared/live-sources.md` — files that don't exist. Orphaned theme files in `theme-factory` (loaded dynamically, not via static references). Legitimate structural observations, not false positives.
+
+### Against a multi-plugin production repo
+
+```
+$ claude-skill-lint lint ~/Development/work/ai-plugins/
+✖ 3 warnings in 3 files (45 files checked)
+```
+
+Three unlisted plugins (valid `plugin.json` but not declared in the root `marketplace.json`). Graph validation: clean — zero errors across 45 files. The multi-plugin format's relative path resolution (`../../context/foo.md`) works correctly.
+
+### Frontmatter lint: honest assessment
+
+The lint pass found 34 type errors across the same 139-file suite — `argument-hint` values parsed as YAML arrays instead of strings, `tools` fields as comma-separated strings instead of arrays.
+
+Claude Code tolerates all of them. Skills work fine. The linter is being opinionated about structure, enforcing that frontmatter conforms to a schema. That matters when you're sharing skills, publishing to a marketplace, or building tooling that expects consistent types. For personal skills that just work, graph validation is where the real value lives.
+
+The 4 YAML parse errors, on the other hand, are genuinely broken. The frontmatter can't be read at all.
+
+## Installation
+
+```bash
+npm install -g claude-skill-lint
+```
+
+Or directly:
+
+```bash
+npx claude-skill-lint lint .
+```
+
+Requires Node.js 20+.
+
+## Quick Start
+
+```bash
+claude-skill-lint init           # Auto-detect format, generate config
+claude-skill-lint graph .        # Cross-file references — the high-value bugs
+claude-skill-lint lint .         # Frontmatter structure
+```
+
+## What It Checks
+
+### Graph Validation
+
+Builds a dependency graph from cross-file references. Finds:
+
+- **Broken references** — skill says "read context/foo.md," file doesn't exist. Claude hallucinates the gap.
+- **Orphaned files** — context or agent files that nothing references. Tokens loaded for nothing.
+- **Name collisions** — two files resolve to the same canonical name. One overwrites the other on install.
+- **Dependency cycles** — circular references between files. Context pollution.
+
+Resolves both installed paths (`~/.claude/commands/context/foo.md`) and relative paths (`../../context/foo.md`, `./reference/guide.md`, `agents/scanner.md`), with automatic fallback between resolution strategies.
+
+### Frontmatter Validation
+
+Validates YAML frontmatter against file-type schemas:
+
+| File Type | Required Fields | Optional Fields |
+|-----------|----------------|-----------------|
+| Command | `description` | `model`, `allowed-tools`, `argument-hint`, `context`, `agent`, `effort`, `hooks`, `compatibility`, `metadata` |
+| Agent | `name`, `description` | `model`, `tools`, `context`, `agent`, `effort`, `hooks`, `compatibility`, `metadata` |
+| Skill (plugin) | `name`, `description` | `invocable`, `argument-hint`, `user-invocable`, `allowed-tools`, `context`, `agent`, `effort`, `hooks`, `compatibility`, `metadata` |
+| Context | *(none)* | — |
+
+#### Modern Frontmatter Fields
+
+These fields are supported across all file types (command, agent, skill):
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `context` | `string` | Execution context for the skill (e.g. `fork` to run in a separate process) |
+| `agent` | `string` | Agent mode or name to delegate execution to |
+| `effort` | `string` | Reasoning effort level — controls how much thinking the model applies |
+| `hooks` | `object` | Lifecycle hooks triggered before/after skill execution |
+| `compatibility` | `string` | Compatibility requirements or version constraints |
+| `metadata` | `object` | Arbitrary key-value metadata for tooling and marketplace use |
+| `allowed-tools` | `array` or `string` | Tools the skill can use. Supports glob patterns like `mcp__*` and `Bash(*)` for broad matching, or specific tool names for fine-grained control |
+
+At Level 1: model enum validation, known tool verification (including `Bash(python*)` pattern syntax), tool-to-body consistency, file size limits, `effort` value validation, skill name format.
+
+### Manifest Validation (plugin format)
+
+Validates `marketplace.json` and `plugin.json` structure, source path resolution, name consistency, and missing skill files.
+
+## Progressive Quality Levels
+
+Skills mature. The quality bar should mature with them.
+
+| Level | What It Adds | When |
+|-------|-------------|------|
+| **0** | Valid YAML, required fields, non-empty body | New skills, prototyping |
+| **1** | Model enum, known tools, tool-in-body check, file size limits | Established skills, shared suites |
+
+Declare per file:
+
+```yaml
+---
+name: my-skill
+description: Does something useful
+quality_level: 1
+---
+```
+
+Or set directory defaults in `.skill-lint.yaml`:
+
+```yaml
+default_level: 0
+levels:
+  commands/: 1
+  agents/: 1
+```
+
+Effective level: `max(file declaration, directory default, --level flag)`. The highest value wins. You can raise the floor but never lower a file's declared level.
+
+### Ratchet
+
+```bash
+claude-skill-lint lint . --ratchet --base origin/main
+```
+
+Compares each file's `quality_level` against the base branch. If any level decreased, the build fails. Quality improvements become permanent. That's the point.
+
+## Repository Formats
+
+claude-skill-lint auto-detects your repository structure. Four formats are supported:
+
+| Format | Structure | Detection Signal |
+|--------|-----------|-----------------|
+| **legacy-commands** | `commands/`, `agents/`, `context/` at repo root | No `.claude-plugin/` directory |
+| **project-skills** | `.claude/skills/{name}/SKILL.md` | `.claude/skills/` with `SKILL.md` files |
+| **plugin** | `skills/{name}/SKILL.md` with marketplace manifest | `.claude-plugin/marketplace.json` at root |
+| **multi-plugin** | `plugins/{name}/skills/{skill}/SKILL.md` | Plugin subdirectories with `.claude-plugin/plugin.json` |
+
+Detection priority: config override > multi-plugin > plugin > project-skills > legacy-commands. The first match wins.
+
+### project-skills: The `.claude/skills/` Format
+
+The `project-skills` format uses `.claude/skills/{name}/SKILL.md` — the same structure Claude Code uses for project-scoped skills. Each skill lives in its own directory under `.claude/skills/`.
+
+claude-skill-lint discovers skills in nested `.claude/skills/` directories automatically. In monorepo setups where multiple packages each have their own `.claude/skills/` directory, point the linter at the repo root and it finds them all.
+
+Hybrid repos work too. A repo with both `.claude/skills/` and legacy `commands/` directories — or a published plugin that also has project-level skills — gets everything linted in a single run. No configuration needed.
+
+### Migration Note
+
+For repos transitioning from legacy commands to modern skills, claude-skill-lint validates both locations in a single run. Set the format explicitly in `.skill-lint.yaml` if auto-detection picks the wrong one, or omit it and let detection handle the transition — legacy-commands is the fallback when no modern format signals are found.
+
+## Custom Structures
+
+Not every repo follows a standard layout. claude-skill-lint provides three configuration levers for non-standard structures:
+
+### `skills_root`
+
+If your skill files live in a subdirectory rather than the repo root:
+
+```yaml
+skills_root: "packages/my-plugin"
+```
+
+All path resolution starts from this root. Useful for monorepos where skills are nested deep.
+
+### `format` Override
+
+Auto-detection works for standard layouts. When it doesn't — or when your repo is mid-migration between formats — set the format explicitly:
+
+```yaml
+format: plugin          # Force plugin format detection
+# format: legacy-commands | plugin | multi-plugin | project-skills
+```
+
+### `ignore` Patterns
+
+Exclude paths that look like skills but aren't:
+
+```yaml
+ignore:
+  - "**/README.md"
+  - "**/CLAUDE.md"
+  - "node_modules/**"
+  - "docs/**/*.md"
+  - "archive/**"
+```
+
+Glob patterns, matched against file paths relative to `skills_root`. `node_modules/` is always excluded.
+
+## Commands
+
+### `claude-skill-lint graph [paths...]`
+
+```bash
+claude-skill-lint graph .                    # Full graph analysis
+claude-skill-lint graph . --format json      # JSON output
+claude-skill-lint graph . --format github    # GitHub annotations
+claude-skill-lint graph . --strict           # Orphan warnings become errors
+```
+
+### `claude-skill-lint lint [paths...]`
+
+```bash
+claude-skill-lint lint .                                    # Lint everything
+claude-skill-lint lint . --level 1                          # Enforce Level 1
+claude-skill-lint lint . --strict                           # Warnings become errors
+claude-skill-lint lint . --ratchet                          # Prevent quality regression
+claude-skill-lint lint . --changed-only --base origin/main  # Only changed files
+claude-skill-lint lint . --format json                      # JSON for tooling
+claude-skill-lint lint . --format github                    # GitHub Actions annotations
+```
+
+### `claude-skill-lint init`
+
+```bash
+claude-skill-lint init           # Auto-detect format, generate config
+claude-skill-lint init --force   # Overwrite existing
+```
+
+Exit codes: `0` clean, `1` errors found, `2` config error.
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--level` / `-l` | `0` | Minimum quality level (0-3) |
+| `--changed-only` | `false` | Only check files changed since base ref |
+| `--base` | `origin/main` | Git ref for `--changed-only` and `--ratchet` |
+| `--format` / `-f` | `terminal` | Output: `terminal`, `json`, `github` |
+| `--strict` | `false` | Treat warnings as errors |
+| `--ratchet` | `false` | Fail if any quality_level decreased vs base |
+
+## Configuration
+
+`claude-skill-lint init` generates this. Or create `.skill-lint.yaml` manually:
+
+```yaml
+skills_root: "."
+default_level: 0
+
+levels:
+  commands/: 1
+  agents/: 1
+
+# Auto-detected if omitted
+# format: legacy-commands | plugin | multi-plugin | project-skills
+
+models: [opus, sonnet, haiku]
+
+tools:
+  mcp_pattern: "mcp__*"
+  custom: []
+
+limits:
+  max_file_size: 15360
+
+ignore:
+  - "**/README.md"
+  - "**/CLAUDE.md"
+  - "node_modules/**"
+
+graph:
+  warn_orphans: true
+  detect_cycles: true
+  detect_duplicates: true
+```
+
+## CI Integration
+
+### GitHub Actions
+
+```yaml
+name: Skill Lint
+on:
+  pull_request:
+    paths: ['**/*.md', '.skill-lint.yaml']
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npm install -g claude-skill-lint
+
+      - name: Graph validation
+        run: claude-skill-lint graph . --format github
+
+      - name: Lint changed skills
+        run: claude-skill-lint lint . --format github --changed-only --base origin/${{ github.base_ref }}
+
+      - name: Quality ratchet
+        run: claude-skill-lint lint . --ratchet --base origin/${{ github.base_ref }} --format github
+```
+
+`--format github` produces annotations that appear inline on PR diffs.
+
+### Pre-commit Hook
+
+```bash
+#!/bin/sh
+STAGED=$(git diff --cached --name-only --diff-filter=ACM -- '*.md')
+if [ -n "$STAGED" ]; then
+  npx claude-skill-lint lint $STAGED --level 1
+fi
+```
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { basename } from 'node:path';
+
+// Deprecation notice when invoked as the old binary name
+const binName = basename(process.argv[1] || '');
+if (binName === 'skill-lint') {
+  process.stderr.write('Note: skill-lint is deprecated. Use claude-skill-lint instead.\n');
+}
+
+import '../dist/cli.js';

package/dist/changed-files.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Git-aware file filtering for --changed-only mode.
+ * Returns absolute paths to .md files changed since a given base ref.
+ */
+/** Error thrown when git operations fail (non-git dir, bad ref, etc.). */
+export declare class ChangedFilesError extends Error {
+    constructor(message: string);
+}
+/**
+ * Get the list of changed .md files between `base` and HEAD.
+ *
+ * Runs `git diff --name-only --diff-filter=ACM {base}...HEAD -- '*.md'`
+ * and resolves repo-relative paths to absolute paths.
+ *
+ * @param base - Git ref to diff against (e.g. "origin/main", "main")
+ * @returns Array of absolute file paths to changed .md files
+ * @throws ChangedFilesError if git commands fail
+ */
+export declare function getChangedFiles(base: string): string[];
+//# sourceMappingURL=changed-files.d.ts.map

package/dist/changed-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"changed-files.d.ts","sourceRoot":"","sources":["../src/changed-files.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,0EAA0E;AAC1E,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAiCtD"}

package/dist/changed-files.js

@@ -0,0 +1,49 @@
+/**
+ * Git-aware file filtering for --changed-only mode.
+ * Returns absolute paths to .md files changed since a given base ref.
+ */
+import { execFileSync } from 'node:child_process';
+import { resolve } from 'node:path';
+/** Error thrown when git operations fail (non-git dir, bad ref, etc.). */
+export class ChangedFilesError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ChangedFilesError';
+    }
+}
+/**
+ * Get the list of changed .md files between `base` and HEAD.
+ *
+ * Runs `git diff --name-only --diff-filter=ACM {base}...HEAD -- '*.md'`
+ * and resolves repo-relative paths to absolute paths.
+ *
+ * @param base - Git ref to diff against (e.g. "origin/main", "main")
+ * @returns Array of absolute file paths to changed .md files
+ * @throws ChangedFilesError if git commands fail
+ */
+export function getChangedFiles(base) {
+    let repoRoot;
+    try {
+        repoRoot = execFileSync('git', ['rev-parse', '--show-toplevel'], {
+            encoding: 'utf-8',
+        }).trim();
+    }
+    catch {
+        throw new ChangedFilesError('Not a git repository (or git is not installed)');
+    }
+    let diffOutput;
+    try {
+        diffOutput = execFileSync('git', ['diff', '--name-only', '--diff-filter=ACM', `${base}...HEAD`, '--', '*.md'], { encoding: 'utf-8', cwd: repoRoot }).trim();
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new ChangedFilesError(`Failed to get changed files (base: ${base}): ${msg}`);
+    }
+    if (diffOutput === '') {
+        return [];
+    }
+    return diffOutput
+        .split('\n')
+        .map((relativePath) => resolve(repoRoot, relativePath));
+}
+//# sourceMappingURL=changed-files.js.map

package/dist/changed-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"changed-files.js","sourceRoot":"","sources":["../src/changed-files.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,0EAA0E;AAC1E,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC1C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,IAAI,QAAgB,CAAC;IACrB,IAAI,CAAC;QACH,QAAQ,GAAG,YAAY,CAAC,KAAK,EAAE,CAAC,WAAW,EAAE,iBAAiB,CAAC,EAAE;YAC/D,QAAQ,EAAE,OAAO;SAClB,CAAC,CAAC,IAAI,EAAE,CAAC;IACZ,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,iBAAiB,CACzB,gDAAgD,CACjD,CAAC;IACJ,CAAC;IAED,IAAI,UAAkB,CAAC;IACvB,IAAI,CAAC;QACH,UAAU,GAAG,YAAY,CACvB,KAAK,EACL,CAAC,MAAM,EAAE,aAAa,EAAE,mBAAmB,EAAE,GAAG,IAAI,SAAS,EAAE,IAAI,EAAE,MAAM,CAAC,EAC5E,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,CACrC,CAAC,IAAI,EAAE,CAAC;IACX,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC7D,MAAM,IAAI,iBAAiB,CACzB,sCAAsC,IAAI,MAAM,GAAG,EAAE,CACtD,CAAC;IACJ,CAAC;IAED,IAAI,UAAU,KAAK,EAAE,EAAE,CAAC;QACtB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,OAAO,UAAU;SACd,KAAK,CAAC,IAAI,CAAC;SACX,GAAG,CAAC,CAAC,YAAY,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC;AAC5D,CAAC"}

package/dist/classify.d.ts

@@ -0,0 +1,13 @@
+import { type FileType } from './types.js';
+/**
+ * Classify a skill file by its path and frontmatter presence.
+ *
+ * Classification rules (in priority order):
+ * 1. Basename `SKILL.md` (case-sensitive) → skill
+ * 2. Basename `README.md` or `CLAUDE.md` (case-insensitive) → readme
+ * 3. Rightmost known directory segment → command | agent | context | skill
+ * 4. Agent path + hasFrontmatter false → legacy-agent
+ * 5. No match → unknown
+ */
+export declare function classifyFile(filePath: string, hasFrontmatter: boolean): FileType;
+//# sourceMappingURL=classify.d.ts.map

package/dist/classify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"classify.d.ts","sourceRoot":"","sources":["../src/classify.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AAe3C;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,MAAM,EAChB,cAAc,EAAE,OAAO,GACtB,QAAQ,CAyDV"}

package/dist/classify.js

@@ -0,0 +1,72 @@
+/** Known directory segments that map to file types. */
+const SEGMENT_TYPE_MAP = new Map([
+    ['commands', 'command'],
+    ['agents', 'agent'],
+    ['context', 'context'],
+    ['skills', 'skill'],
+    ['reference', 'context'],
+    ['shared', 'context'],
+    ['examples', 'context'],
+    ['templates', 'context'],
+    ['themes', 'context'],
+]);
+/**
+ * Classify a skill file by its path and frontmatter presence.
+ *
+ * Classification rules (in priority order):
+ * 1. Basename `SKILL.md` (case-sensitive) → skill
+ * 2. Basename `README.md` or `CLAUDE.md` (case-insensitive) → readme
+ * 3. Rightmost known directory segment → command | agent | context | skill
+ * 4. Agent path + hasFrontmatter false → legacy-agent
+ * 5. No match → unknown
+ */
+export function classifyFile(filePath, hasFrontmatter) {
+    const basename = filePath.split('/').pop() ?? '';
+    // AC-3 (story-016): SKILL.md basename (case-sensitive) → skill
+    if (basename === 'SKILL.md') {
+        return 'skill';
+    }
+    // AC-9 (story-016): CLAUDE.md (case-insensitive) → readme
+    if (basename.toLowerCase() === 'claude.md') {
+        return 'readme';
+    }
+    // AC-4: README.md basename check (case-insensitive)
+    if (basename.toLowerCase() === 'readme.md') {
+        return 'readme';
+    }
+    // Split into segments and find the rightmost known directory segment (AC-7).
+    const segments = filePath.split('/');
+    let matchedType;
+    for (const segment of segments) {
+        const type = SEGMENT_TYPE_MAP.get(segment);
+        if (type !== undefined) {
+            matchedType = type;
+            // Don't break — keep scanning so the rightmost wins.
+        }
+    }
+    if (matchedType === undefined) {
+        return 'unknown'; // AC-9
+    }
+    // AC-5 / AC-6: legacy-agent reclassification
+    if (matchedType === 'agent') {
+        return hasFrontmatter ? 'agent' : 'legacy-agent';
+    }
+    // Non-SKILL.md markdown in skills/ dirs:
+    // - Directly in skills/name/ → readme
+    // - In skills/name/subdir/ where subdir is not in SEGMENT_TYPE_MAP → unknown
+    //   (If the subdir were recognized, it would have overridden matchedType.)
+    if (matchedType === 'skill') {
+        const skillsIdx = segments.lastIndexOf('skills');
+        // afterSkills = [skillName, ...subdirs, basename]
+        const afterSkills = segments.slice(skillsIdx + 1);
+        if (afterSkills.length > 2) {
+            // File is nested in a subdirectory of the skill folder, and that
+            // subdirectory is unrecognized (otherwise matchedType would not
+            // still be 'skill'). Classify as unknown.
+            return 'unknown';
+        }
+        return 'readme';
+    }
+    return matchedType;
+}
+//# sourceMappingURL=classify.js.map

package/dist/classify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"classify.js","sourceRoot":"","sources":["../src/classify.ts"],"names":[],"mappings":"AAEA,uDAAuD;AACvD,MAAM,gBAAgB,GAAkC,IAAI,GAAG,CAAC;IAC9D,CAAC,UAAU,EAAE,SAAS,CAAC;IACvB,CAAC,QAAQ,EAAE,OAAO,CAAC;IACnB,CAAC,SAAS,EAAE,SAAS,CAAC;IACtB,CAAC,QAAQ,EAAE,OAAO,CAAC;IACnB,CAAC,WAAW,EAAE,SAAS,CAAC;IACxB,CAAC,QAAQ,EAAE,SAAS,CAAC;IACrB,CAAC,UAAU,EAAE,SAAS,CAAC;IACvB,CAAC,WAAW,EAAE,SAAS,CAAC;IACxB,CAAC,QAAQ,EAAE,SAAS,CAAC;CACtB,CAAC,CAAC;AAEH;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY,CAC1B,QAAgB,EAChB,cAAuB;IAEvB,MAAM,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC;IAEjD,+DAA+D;IAC/D,IAAI,QAAQ,KAAK,UAAU,EAAE,CAAC;QAC5B,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,0DAA0D;IAC1D,IAAI,QAAQ,CAAC,WAAW,EAAE,KAAK,WAAW,EAAE,CAAC;QAC3C,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,oDAAoD;IACpD,IAAI,QAAQ,CAAC,WAAW,EAAE,KAAK,WAAW,EAAE,CAAC;QAC3C,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,6EAA6E;IAC7E,MAAM,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACrC,IAAI,WAAiC,CAAC;IAEtC,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,MAAM,IAAI,GAAG,gBAAgB,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAC3C,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,WAAW,GAAG,IAAI,CAAC;YACnB,qDAAqD;QACvD,CAAC;IACH,CAAC;IAED,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;QAC9B,OAAO,SAAS,CAAC,CAAC,OAAO;IAC3B,CAAC;IAED,6CAA6C;IAC7C,IAAI,WAAW,KAAK,OAAO,EAAE,CAAC;QAC5B,OAAO,cAAc,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,cAAc,CAAC;IACnD,CAAC;IAED,yCAAyC;IACzC,sCAAsC;IACtC,6EAA6E;IAC7E,2EAA2E;IAC3E,IAAI,WAAW,KAAK,OAAO,EAAE,CAAC;QAC5B,MAAM,SAAS,GAAG,QAAQ,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;QACjD,kDAAkD;QAClD,MAAM,WAAW,GAAG,QAAQ,CAAC,KAAK,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC;QAClD,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC3B,iEAAiE;YACjE,gEAAgE;YAChE,0CAA0C;YAC1C,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,OAAO,WAAW,CAAC;AACrB,CAAC"}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}