efaimo 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -4,6 +4,51 @@ All notable changes to efaimo are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this project uses
 [Semantic Versioning](https://semver.org/).
 
+## [0.4.0] - 2026-09-03
+
+### Fixed
+
+- **`check --skill <dir>` finds skills it used to walk past**.
+  Two causes, both silent. The walk never entered a directory whose name starts
+  with a dot, so `.claude/skills/<name>/`, which is where a project keeps its
+  own skills, was invisible; and its depth bound of 3 missed layouts one level
+  deeper such as `skills/custom_skills/<name>/`. On the public corpus this
+  found 34 skills where `scripts/skills-index.mjs` found 38, and both numbers
+  were reported with confidence.
+
+  Dot directories are now entered for skill discovery and nowhere else, with
+  `.git` still excluded. The depth bound is 6 and is measured rather than
+  picked: the deepest real skill in that corpus sits 4 directories below a
+  directory of repositories and 3 below a repository root, so six leaves two
+  levels of headroom while still keeping an accidental `check --skill /` from
+  walking a disk.
+
+  **And when the bound does bite, it says so.** `SkillSet.truncatedAt` lists
+  the directories the walk refused to enter, because a bound that truncates in
+  silence is the same failure as a check that examines nothing. On the public
+  corpus it fires 16 times, all of them XML schema trees inside the `xlsx` and
+  `pptx` skills, which is the bound doing its job audibly.
+
+- **One walker instead of two**. `scripts/skills-index.mjs`
+  carried its own copy with different rules, which is why the two disagreed.
+  It now calls the CLI's discovery, so they cannot drift apart again, and it
+  passes the truncation warning through. The published July index regenerates
+  byte-identically under the shared walk, which is how this was checked.
+
+### Added
+
+- **S107: a filename one capitalisation away from a skill**.
+  Set-level and warn-level, so it moves no grade, in the same way S103 treats
+  a collision that belongs to a pair rather than to either member.
+
+  The spec names `SKILL.md` exactly and discovery matches it exactly, so
+  `skill.md` is not a skill here on any platform. It is not nothing anywhere:
+  a case-insensitive filesystem, the default on macOS and Windows, may hand it
+  to a host that opens it by name, so the same repository can carry a working
+  skill on the author's laptop and no skill at all in Linux CI. Nothing in
+  this tool would previously have mentioned such a file, which is the worst
+  property a near miss can have. Five exist in the public corpus.
+
 ## [0.3.0] - 2026-09-03
 
 ### Added
@@ -34,9 +79,17 @@ All notable changes to efaimo are documented here. Format follows
   both runs scored lower.
 
   Measured on the public skills corpus, 2026-07-17 pinned against 2026-09-03
-  HEAD, same ruleset both sides: metadata -0.8%, body +7.5%, referenced files
-  +61.4% with one skill at 96.5% of that movement; grades 0 improved and 4
-  worsened.
+  HEAD, same ruleset both sides, over the **32 skills `check --skill` pairs**:
+  metadata -0.8%, body +7.5%, referenced files +61.4% with one skill at 96.5%
+  of that movement; grades 0 improved and 4 worsened.
+
+  The population matters and is worth stating, because
+  `research/skills-delta-2026-09-03/REPORT.md` reports body **+7.0%** over
+  **36** paired skills for the same corpus on the same dates. Both are true.
+  `scripts/skills-index.mjs` finds four skills that `check --skill` does not,
+  for the walker reason in Known below, so the two are measuring slightly
+  different populations. Every other figure is identical between them; the
+  body percentage is the one the four missing skills move.
 
 - **`efaimo find` takes several servers**. Pass more than one
   and their catalogs are merged into one and measured together, each tool
@@ -355,6 +408,7 @@ First release.
   Documented rule set (`docs/RULES.md`), token methodology (`docs/METHODOLOGY.md`),
   and integration guide (`docs/INTEGRATIONS.md`).
 
+[0.4.0]: https://github.com/efaimo-ai/efaimo/releases/tag/v0.4.0
 [0.3.0]: https://github.com/efaimo-ai/efaimo/releases/tag/v0.3.0
 [0.2.0]: https://github.com/efaimo-ai/efaimo/releases/tag/v0.2.0
 [0.1.2]: https://github.com/efaimo-ai/efaimo/releases/tag/v0.1.2

package/README.md

@@ -406,3 +406,7 @@ Built by [efaimo ai](https://efaimo.ai), open tooling for the space between host
 and tools. `efaimo` is the flagship CLI; capabilities grow as subcommands under one
 name. Apache-2.0. See [CONTRIBUTING.md](./CONTRIBUTING.md) and
 [docs/RULES.md](./docs/RULES.md) to add a rule.
+
+EFAIMO AI is a registered trademark of the publisher (KR 40-2585820, class 42).
+The lowercase `efaimo ai` used throughout is the same mark; the package name and
+the commands stay lowercase.

package/SKILL.md

@@ -3,7 +3,7 @@ name: efaimo
 description: Audit MCP servers and Agent Skills for quality and context-window cost. Use when the user wants to check an MCP server's token cost, lint a skill, verify 2026-07-28 MCP spec readiness, find out whether a search can single out a server's tools under deferred tool loading, or add an efaimo badge or CI gate.
 license: Apache-2.0
 metadata:
-  version: "0.3.0"
+  version: "0.4.0"
   homepage: "https://efaimo.ai"
 ---
 

package/dist/check/check.js

@@ -85,5 +85,20 @@ export async function checkSkillSet(pathInput, label) {
         return { name, dir: skill.dir, report: buildReport("skill", name, findings, []) };
     });
     const setFindings = set.skills.flatMap((skill) => runRules(setRules, { skill, set, weigh }));
+    // S107 is emitted here rather than by a SkillRule because its subject is a
+    // file that is NOT a skill: no rule that takes a parsed skill could ever see
+    // it. Set level and warn level on purpose, so it moves no grade, matching
+    // how S103 treats a collision that belongs to a pair rather than to either
+    // member.
+    for (const file of set.miscasedSkillFiles ?? []) {
+        setFindings.push({
+            ruleId: "S107",
+            severity: "warn",
+            title: "filename is one capitalisation away from a skill",
+            message: `"${path.relative(set.root, file)}" is not loaded here, because the spec names SKILL.md exactly. A case-insensitive filesystem (the macOS and Windows default) may still hand it to a host, so this can work on a laptop and be missing entirely in Linux CI.`,
+            target: path.relative(set.root, file),
+            fixHint: "rename it to SKILL.md, or delete it if it is not a skill",
+        });
+    }
     return { label, root: set.root, perSkill, setFindings, weigh };
 }

package/dist/core/types.d.ts

@@ -339,6 +339,24 @@ export interface SkillInfo {
 export interface SkillSet {
     root: string;
     skills: SkillInfo[];
+    /**
+     * Directories the walk refused to enter because it hit its depth bound.
+     *
+     * Present only when the bound actually bit. A truncated search that reports
+     * a short list and no reason is the same failure as a check that examines
+     * nothing, so the caller is given the means to say what it did not look at.
+     */
+    truncatedAt?: string[];
+    /**
+     * Files one capitalisation away from being a skill, such as `skill.md`.
+     *
+     * The spec names `SKILL.md` exactly and discovery matches it exactly, so
+     * these are not skills here on any platform. They may still be skills to a
+     * host reading a case-insensitive filesystem, which is the default on macOS
+     * and Windows, so the same repository can work on a laptop and have no
+     * skills at all in Linux CI. Reported by S107.
+     */
+    miscasedSkillFiles?: string[];
 }
 export interface GradeInfo {
     score: number;

package/dist/skills/parse.d.ts

@@ -1,4 +1,10 @@
 import type { SkillInfo, SkillSet } from "../core/types.js";
 export declare function parseSkillFile(file: string): SkillInfo;
 /** Resolve a path (SKILL.md file, skill dir, or a directory of skills) into a SkillSet. */
+/**
+ * How deep skill discovery walks. See the note inside `findSkills`: measured
+ * against the public corpus, where the deepest real skill is four directories
+ * below a directory of repositories.
+ */
+export declare const SKILL_WALK_MAX_DEPTH = 6;
 export declare function findSkills(input: string): SkillSet;

package/dist/skills/parse.js

@@ -129,6 +129,12 @@ export function parseSkillFile(file) {
     return base;
 }
 /** Resolve a path (SKILL.md file, skill dir, or a directory of skills) into a SkillSet. */
+/**
+ * How deep skill discovery walks. See the note inside `findSkills`: measured
+ * against the public corpus, where the deepest real skill is four directories
+ * below a directory of repositories.
+ */
+export const SKILL_WALK_MAX_DEPTH = 6;
 export function findSkills(input) {
     const abs = path.resolve(input);
     const stat = fs.statSync(abs);
@@ -139,11 +145,49 @@ export function findSkills(input) {
     if (fs.existsSync(direct)) {
         return { root: abs, skills: [parseSkillFile(direct)] };
     }
+    // Discovery is deliberate rather than incidental, because two walkers with
+    // different rules is what produced the 2026-09-03 defect: this found 34
+    // skills in a corpus where `scripts/skills-index.mjs` found 38, and both
+    // reported their own number with confidence.
+    //
+    // maxDepth 6 is measured, not picked. In the public corpus the deepest real
+    // skill sits 4 directories below a directory-of-repositories
+    // (`<corpus>/<repo>/skills/custom_skills/<name>/SKILL.md`) and 3 below a
+    // repository root. Six leaves two levels of headroom and keeps an accidental
+    // `check --skill /` from walking a disk. When the bound does bite it is
+    // reported rather than swallowed, in `truncatedAt`.
+    //
+    // Dot directories are entered here and nowhere else in this codebase:
+    // `.claude/skills/<name>/` is where a project keeps its own skills, so
+    // skipping them made this blind to the most common real layout. `.git` is
+    // still excluded by DEFAULT_SKIP_DIRS.
     const skills = [];
-    for (const f of walkFiles(abs, { maxDepth: 3 })) {
-        if (path.basename(f) === "SKILL.md")
+    const truncatedAt = [];
+    const miscased = [];
+    for (const f of walkFiles(abs, {
+        maxDepth: SKILL_WALK_MAX_DEPTH,
+        includeDotDirs: true,
+        onDepthLimit: (d) => truncatedAt.push(d),
+    })) {
+        const base = path.basename(f);
+        if (base === "SKILL.md")
             skills.push(parseSkillFile(f));
+        // A file that is only a capitalisation away from being a skill. The spec
+        // names SKILL.md exactly, and this comparison is exact, so `skill.md` is
+        // invisible here on every platform. It is not invisible everywhere: a
+        // case-insensitive filesystem, which is the default on macOS and Windows,
+        // may hand it to a host that opens it by name, so the same repository has
+        // a working skill on the author's laptop and no skill at all in Linux CI.
+        // Nothing else in this tool would ever mention it, which is the worst
+        // property a near miss can have.
+        else if (base.toLowerCase() === "skill.md")
+            miscased.push(f);
     }
     skills.sort((a, b) => a.file.localeCompare(b.file));
-    return { root: abs, skills };
+    return {
+        root: abs,
+        skills,
+        ...(truncatedAt.length ? { truncatedAt } : {}),
+        ...(miscased.length ? { miscasedSkillFiles: miscased.sort() } : {}),
+    };
 }

package/dist/util/misc.d.ts

@@ -3,10 +3,28 @@ export declare function parseCommandString(input: string): {
     command: string;
     args: string[];
 };
-export declare function walkFiles(root: string, opts?: {
+export interface WalkOptions {
     maxDepth?: number;
     skipDirs?: Set<string>;
-}): Generator<string>;
+    /**
+     * Descend into directories whose name starts with a dot.
+     *
+     * Off by default, because most of them are caches and metadata. On for skill
+     * discovery, because `.claude/skills/<name>/` is where a project keeps its
+     * own skills and a tool that cannot see the most common real layout is not
+     * auditing anything. `DEFAULT_SKIP_DIRS` still excludes `.git`.
+     */
+    includeDotDirs?: boolean;
+    /**
+     * Called once for each directory not entered because `maxDepth` was reached.
+     *
+     * A bound that truncates in silence is the same failure as a check that
+     * examines nothing: the caller sees a short list and no reason for it. This
+     * lets the caller say so.
+     */
+    onDepthLimit?: (dir: string) => void;
+}
+export declare function walkFiles(root: string, opts?: WalkOptions): Generator<string>;
 export declare function readTextSafe(file: string, maxBytes?: number): string | undefined;
 export declare function isBinaryPath(file: string): boolean;
 export declare function extractVersion(s: string): number[] | undefined;

package/dist/util/misc.js

@@ -59,9 +59,15 @@ export function* walkFiles(root, opts = {}) {
         for (const e of entries) {
             const full = path.join(dir, e.name);
             if (e.isDirectory()) {
-                if (depth < maxDepth && !skip.has(e.name) && !e.name.startsWith(".")) {
-                    stack.push({ dir: full, depth: depth + 1 });
+                if (skip.has(e.name))
+                    continue;
+                if (!opts.includeDotDirs && e.name.startsWith("."))
+                    continue;
+                if (depth >= maxDepth) {
+                    opts.onDepthLimit?.(full);
+                    continue;
                 }
+                stack.push({ dir: full, depth: depth + 1 });
             }
             else if (e.isFile()) {
                 yield full;

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** Kept in sync with package.json by test/meta.test.ts. */
-export declare const VERSION = "0.3.0";
+export declare const VERSION = "0.4.0";

package/dist/version.js

@@ -1,2 +1,2 @@
 /** Kept in sync with package.json by test/meta.test.ts. */
-export const VERSION = "0.3.0";
+export const VERSION = "0.4.0";

package/docs/RULES.md

@@ -65,7 +65,7 @@ never reused, so a gap is permanent and is better stated than smoothed over.
 | E128 | warn | total tool-definition tax over ~10k / ~25k tokens, estimated (needs `weigh` data); hard CI failure is left to the `--max-tokens`/`--diff` gate |
 | E130 | info | instruction-injection patterns in a tool description or server instructions (shallow heuristic, never a security verdict; use a dedicated scanner for depth). **Reported but never scored** |
 
-## Skills (S101-S106)
+## Skills (S101-S107)
 
 | id | sev | what it catches | spec |
 |---|---|---|---|
@@ -75,6 +75,7 @@ never reused, so a gap is permanent and is better stated than smoothed over.
 | S104 | warn/info | metadata over ~100 tokens, body over ~5k tokens or 500 lines, or long body with no progressive disclosure | agentskills.io |
 | S105 | info | instruction-injection patterns in the skill body or description (shallow heuristic, never a security verdict). **Reported but never scored** | internal |
 | S106 | error/warn/info | referenced file missing, escaping the skill dir (`..`), or nested more than one level deep | agentskills.io |
+| S107 | warn | a file one capitalisation away from a skill, such as `skill.md`. Set-level and never scored: the spec names `SKILL.md` exactly, so it is not a skill here on any platform, but a case-insensitive filesystem (the macOS and Windows default) may hand it to a host, which makes a repository work on a laptop and have no skill at all in Linux CI | internal |
 
 ## Findability (E141-E145)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "efaimo",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Audit what your agent loads: quality and context cost for MCP servers and Agent Skills",
   "keywords": [
     "mcp",