efaimo 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+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/).
+
+## [Unreleased]
+
+## [0.1.0]
+
+First release.
+
+### Added
+
+- `efaimo weigh`: context-window cost of MCP tool definitions (stdio, remote, or a
+  whole client config) and of Agent Skills, in three serializations, with an
+  optional `--anthropic` exact Claude count. Per-tool numbers plus an explicit
+  block-framing line reconcile exactly with the total. In a multi-server run a
+  broken or auth-gated server is skipped with a reason, not fatal.
+  `--out`/`--diff`/`--max-tokens`/`--allow-increase` for CI budget gates,
+  `--badge` for a shields endpoint.
+- `efaimo check --mcp`: a quality grade (E121-E130: descriptions, schemas,
+  annotations, cost) plus a separate, ungraded 2026-07-28 migration diff
+  (E101-E118: what the stateless spec breaks and how to fix it, each item naming
+  its SEP). Speaks both the legacy handshake and bare stateless requests, so
+  2026-07-28 servers audit fine. Optional `--repo` source scan and
+  `--conformance` passthrough to the official suite.
+- `efaimo check --skill`: Agent Skills linter against the agentskills.io spec
+  (S101-S106): frontmatter and trigger quality, trigger collisions, context budget,
+  reference integrity, injection heuristics. Per-skill grading over a directory, and
+  a reproducible Skills Quality Index (`scripts/skills-corpus.mjs` pins the corpus
+  to exact commits; `scripts/skills-index.mjs` grades it).
+- `efaimo test` (experimental): an A/B outcome harness that measures whether a skill
+  actually improves task completion. Dry-run by default (validates the scenario, no
+  API calls); `--live` runs against the Anthropic or OpenAI API, and it fails clearly
+  on an unsupported model provider.
+- `efaimo mcp`: a small, read-only MCP server exposing `efaimo_check_skill` and
+  `efaimo_weigh_skill`, so an agent can lint or weigh a skill mid-session. Reads
+  files only; `test` is not exposed; tools are annotated read-only.
+- `.env` loading for the commands that need a key (`test --live`,
+  `weigh --anthropic`); a real shell variable always wins. See `.env.example`.
+- Reporters: pretty, JSON, Markdown, SVG badge. GitHub Action (`action.yml`).
+  Documented rule set (`docs/RULES.md`), token methodology (`docs/METHODOLOGY.md`),
+  and integration guide (`docs/INTEGRATIONS.md`).
+
+[Unreleased]: https://github.com/efaimo-ai/efaimo/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/efaimo-ai/efaimo/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,6 @@
+efaimo
+Copyright 2026 efaimo ai
+
+This product includes software developed at efaimo ai (https://efaimo.ai).
+
+Licensed under the Apache License, Version 2.0. See the LICENSE file.

package/README.md

@@ -0,0 +1,281 @@
+<p align="center">
+  <img src="assets/banner.png" alt="efaimo. The audit CLI for Agent Skills and MCP servers." width="820">
+</p>
+
+<p align="center">
+  <a href="https://github.com/efaimo-ai/efaimo/actions/workflows/ci.yml"><img src="https://github.com/efaimo-ai/efaimo/actions/workflows/ci.yml/badge.svg" alt="ci"></a>
+  <a href="https://www.npmjs.com/package/efaimo"><img src="https://img.shields.io/npm/v/efaimo.svg?color=57E7D6&label=npm" alt="npm"></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue.svg" alt="license"></a>
+  <img src="https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg" alt="node >= 22">
+</p>
+
+<p align="center">
+  <b>efaimo</b> audits everything your agent loads: <b>MCP servers</b> and <b>Agent Skills</b>.<br>
+  One CLI lints them, weighs their context cost, diffs servers against the 2026-07-28 spec,<br>
+  and A/B-tests whether a skill actually helps.
+</p>
+
+Everything you plug into an agent spends two budgets before any work happens:
+context-window tokens, and the trigger quality that decides whether the right tool
+fires at all. Good tools exist for single slices of that problem; efaimo's job is
+the whole audit in one command, for both halves of what an agent loads. Lint a
+skill, weigh a server's tool definitions, get a migration diff for the 2026-07-28
+stateless MCP spec, and measure whether a skill actually improves task completion
+([SkillsBench](https://www.skillsbench.ai) found 16 of 84 curated skills making
+agents worse; linting alone cannot catch that).
+
+## Agent Skills
+
+```bash
+npx efaimo check --skill ./skills/
+```
+
+Point it at one skill or a whole folder. It validates each skill against the
+[agentskills.io](https://agentskills.io) spec and grades it:
+
+```text
+check skill  claude-api
+grade C (71)   1 error  2 warnings  4 info
+
+  x S101  description is 1068 chars (spec max 1024)
+  ! S104  instructions are ~18.4k tokens (spec recommends staying under 5k)
+          fix: move detail into references/ files loaded on demand
+  ! S104  SKILL.md is 570 lines (spec recommends under 500)
+  i S104  metadata level is ~294 tokens; the spec targets ~100 and this loads at
+          startup for every installed skill
+```
+
+*(That is Anthropic's own `claude-api` skill.)* efaimo checks frontmatter and
+trigger quality, collisions across an installed set, the context budget (metadata
+loaded every session, body loaded on trigger), reference integrity, and injection
+hygiene. Run it on a folder and every skill gets its own grade, not one aggregate.
+
+**We graded 36 public Agent Skills**: every skill in `anthropics/skills`,
+`anthropics/claude-cookbooks`, and `obra/superpowers`, at pinned commits. 97%
+score an A, but even this curated set has real issues: Anthropic's own
+`claude-api` scores a C with an over-limit description and ~18k-token
+instructions, and the median skill's instructions run ~1,700 tokens loaded on
+every trigger. Full report, the corpus manifest, and the two commands that
+reproduce it: [the Skills Quality Index](./research/skills-index/REPORT.md).
+
+### Does the skill actually help? (experimental)
+
+Linting tells you a skill is well-formed. It does not tell you the skill makes the
+agent *better*, and research shows some skills make it worse. `efaimo test` measures
+that directly: it runs a task with and without the skill, N trials each, and an LLM
+judge scores every attempt.
+
+```bash
+npx efaimo test scenario.yaml                 # dry run: validate + show the plan, no API calls
+npx efaimo test scenario.yaml --live          # run it for real (Claude or GPT)
+npx efaimo test scenario.yaml --live --model gpt-4o-mini
+```
+
+Works with Claude (`ANTHROPIC_API_KEY`) or GPT (`OPENAI_API_KEY`) models; the
+provider is picked from the model name. Put the key in your shell or a local
+`.env` file (copy `.env.example`); a real shell variable always wins.
+
+Two real runs (claude-sonnet-5, 8 trials each) show why this matters: a generic
+csv-cleanup skill that a capable model does not need, and a skill that encodes a
+convention the model cannot guess.
+
+<p align="center">
+  <img src="assets/test-ab.png" alt="efaimo test A/B results: csv-cleanup measures +0 points (no measurable effect) while contoso-crm-import measures +100 points (helps); both skills lint clean at grade A" width="880">
+</p>
+
+<details>
+<summary>The two runs as copyable text</summary>
+
+```text
+test  csv-cleanup helps on a messy CSV
+  with skill     8/8 pass  (100%)
+  without skill  8/8 pass  (100%)
+  delta          +0 points   no measurable effect
+```
+
+```text
+test  contoso-crm-import helps on an unknowable format
+  with skill     8/8 pass  (100%)
+  without skill  0/8 pass  (0%)
+  delta          +100 points   helps
+```
+
+</details>
+
+The first is pure context overhead, the second earns its tokens, and only the
+trial data tells them apart. Experimental and probabilistic: raise the trial
+count for confidence, and treat small deltas as noise. It is opt-in because a
+live run spends tokens on your key. See
+[examples/scenario.example.yaml](./examples/scenario.example.yaml) and
+[examples/scenario.crm.yaml](./examples/scenario.crm.yaml).
+
+## MCP servers
+
+```bash
+npx efaimo weigh "npx -y my-mcp-server"      # what does it cost my context window?
+npx efaimo check --mcp "npx -y my-server"    # quality grade + 2026-07-28 migration diff
+```
+
+`weigh` reports the token cost of tool definitions in three real serializations,
+per tool, with an optional `--anthropic` exact Claude count.
+
+<p align="center">
+  <img src="assets/demo.png" alt="efaimo weigh example output" width="720">
+</p>
+
+`check --mcp` connects live (it speaks both the legacy handshake and the new
+stateless protocol, so a 2026-07-28 server audits fine) and reports two things,
+separately. First, a **quality grade** for what models actually experience:
+descriptions, schemas, annotations, tool count, token cost. Second, an ungraded
+**migration diff** for the 2026-07-28 stateless spec (which removes
+`initialize`, sessions, Sampling, Roots, and Logging, and requires
+`server/discover`, `resultType`, and cache fields): exactly what will break and
+how to fix it, each rule naming the SEP it came from. Readiness never drags the
+grade; not having migrated to a spec that is not final until 2026-07-28 is a
+to-do list, not a defect. Full list: [docs/RULES.md](./docs/RULES.md).
+
+<p align="center">
+  <img src="assets/check.png" alt="efaimo check example output: quality grade A (95) plus a four-item 2026-07-28 migration diff for the reference server" width="800">
+</p>
+
+*(That is the official reference server: solid quality, four things to migrate
+before the 28th.)*
+
+<details>
+<summary>The same output as copyable text</summary>
+
+```text
+check mcp  npx -y @modelcontextprotocol/server-everything
+grade A (95)   quality: 0 errors  1 warning  0 info
+
+  ! E122  tool "echo": description misses 3/4 quality axes (length 40..600;
+          says when to use it; mentions the result)
+
+2026-07-28 readiness  4 items to migrate (a migration diff, not graded: the
+spec finalizes 2026-07-28)
+  ! E104  server declares the logging capability; MCP Logging is deprecated in
+          2026-07-28 (SEP-2577) and logging/setLevel is removed
+  ! E106  server/discover is not implemented (-32601 Method not found)
+  ! E118  tools/list result omits ttlMs and/or cacheScope, which 2026-07-28
+          requires on list and resource-read results (SEP-2549, CacheableResult)
+  i E107  results do not carry the resultType field required in 2026-07-28
+          ("complete" | "input_required")
+```
+
+</details>
+
+## From an agent
+
+`efaimo mcp` runs efaimo as a small, read-only MCP server, so an agent can lint or
+weigh a skill mid-session, before it commits it to context:
+
+```bash
+npx efaimo mcp      # stdio server exposing efaimo_check_skill and efaimo_weigh_skill
+```
+
+It reads files only (it spawns no process and opens no socket), and the
+token-spending `test` is not exposed. Client config and recipes are in
+[docs/INTEGRATIONS.md](./docs/INTEGRATIONS.md).
+
+## How it works
+
+efaimo sits between your agent and everything it loads, measures the cost the way
+your host actually serializes it, and grades the quality, before any of it reaches
+your context window.
+
+<p align="center">
+  <img src="assets/architecture.png" alt="efaimo weighs, checks, and tests what your agent loads" width="880">
+</p>
+
+## How it compares
+
+Focused tools already own single slices of this space, and some are very good.
+efaimo is the one tool that covers the whole audit surface. As of mid-2026:
+
+| | efaimo | [skill-validator](https://github.com/agent-ecosystem/skill-validator) | [upskill](https://github.com/huggingface/upskill) | [mcp-spec-check](https://github.com/Roee-Tsur/mcp-spec-check) | [conformance](https://github.com/modelcontextprotocol/conformance) (official) |
+|---|---|---|---|---|---|
+| Agent Skills linting | yes | yes | no | no | no |
+| Skill token cost | yes (3-level split) | yes | no | no | no |
+| Skill outcome testing | with/without A/B trials (experimental) | static LLM scoring | yes (generate + eval, code agents) | no | no |
+| MCP tool-definition cost | yes (3 serializations, `--anthropic` exact) | no | no | no | no |
+| MCP quality rules | yes | no | no | no | no |
+| 2026-07-28 readiness | migration diff: what breaks and how to fix | no | no | yes/no verdict | official test suite |
+| CI budget gate + badge | yes | no | no | no | no |
+
+efaimo runs the official conformance suite for you (`check --conformance` on
+http targets) and complements security scanners such as Snyk agent-scan and the
+skills installer (`npx skills`) rather than replacing them.
+
+## Install
+
+Nothing to install. Use `npx`:
+
+```bash
+npx efaimo check --skill ./skills/
+```
+
+Or add it to a project with `npm i -D efaimo`, or the GitHub Action:
+
+```yaml
+- uses: efaimo-ai/efaimo@v0
+  with:
+    command: check --skill ./skills --strict
+```
+
+Gate a pull request on context-window growth, too:
+
+```bash
+npx efaimo weigh "npx -y my-server" --out base.json          # record a baseline
+npx efaimo weigh "npx -y my-server" --diff base.json --allow-increase 10
+```
+
+`--badge badge.svg` writes an SVG plus a shields.io endpoint JSON for your
+README. These two are real efaimo output for the reference server:
+
+<img src="assets/badge-weigh.svg" alt="context cost: 1120 tok (o200k)"> <img src="assets/badge-grade.svg" alt="efaimo: A (95)">
+
+More recipes (pre-commit, GitLab, editor audit, programmatic use):
+[docs/INTEGRATIONS.md](./docs/INTEGRATIONS.md).
+
+## Rules at a glance
+
+| family | covers |
+|---|---|
+| **S101 to S106** | skills: frontmatter and trigger quality, trigger collisions, context budget, reference integrity, injection hygiene |
+| **E101 to E118** | MCP 2026-07-28 readiness: deprecated primitives, statelessness, `server/discover`, `resultType`, cache fields, transport |
+| **E121 to E130** | MCP quality: description quality, annotations, schema hygiene, tool-count and token-cost budgets |
+
+Quality (E12x-E13x) and skill (S) findings set the letter grade; readiness
+findings (E101-E118) are reported as an ungraded migration diff until the spec
+ratifies. Every finding carries a stable id you can suppress or link. See
+[docs/RULES.md](./docs/RULES.md).
+
+## Roadmap
+
+- Harden `efaimo test`: a separately chosen judge model, confidence intervals on
+  the delta, multi-turn tool-use trials, and judge calibration, so the
+  experimental harness earns unqualified trust.
+- Track the 2026-07-28 spec to ratification, then start grading readiness (today
+  it is an ungraded migration diff on purpose).
+- A public, continuously updated Agent Skills Quality Index over a broad corpus.
+
+## Stability
+
+efaimo is 0.x. The commands are stable, but the rule set, grades, and exact output
+may change between minor versions until 1.0; pin a version in CI if you need
+reproducible thresholds. Every finding keeps a stable id.
+
+## Honest scope
+
+efaimo is a linter and cost profiler, not a security scanner. Its injection checks
+are info-level heuristics that an attacker evades trivially; a clean report is not a
+security pass. For supply-chain safety use a dedicated scanner such as Snyk
+agent-scan. Token figures are estimates unless you opt into `--anthropic`; the
+method and its known bias are in [docs/METHODOLOGY.md](./docs/METHODOLOGY.md).
+
+## About
+
+Built by [efaimo ai](https://efaimo.ai), open tooling for the space between hosts
+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.

package/SKILL.md

@@ -0,0 +1,57 @@
+---
+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, or add an efaimo badge or CI gate.
+license: Apache-2.0
+metadata:
+  version: "0.1.0"
+  homepage: "https://efaimo.ai"
+---
+
+# efaimo
+
+efaimo audits what an agent loads: the quality and context-window cost of MCP
+servers and Agent Skills. Reach for it when someone asks "how many tokens does
+this MCP server cost", "is my server ready for the 2026-07-28 MCP spec", "is this
+skill well-formed", or "add a CI gate / badge for context cost".
+
+## Commands
+
+Run via `npx efaimo` (no install needed).
+
+- **Weigh context cost of an MCP server**
+  `npx efaimo weigh "npx -y <server-package>"` for a stdio server, or
+  `npx efaimo weigh https://host/mcp` for a remote one. Add `--json` for machine
+  output, `--badge badge.svg` for a shields badge, `--anthropic` for Claude-exact
+  token counts.
+- **Weigh a skill or skill set**
+  `npx efaimo weigh ./path/to/skill` reports the metadata / body / referenced-file
+  token split.
+- **Weigh everything a client loads**
+  `npx efaimo weigh --client claude-code` (also `claude-desktop`, `cursor`,
+  `vscode`) sums every configured server.
+- **Audit an MCP server**
+  `npx efaimo check --mcp "npx -y <server>"` prints a quality grade plus a
+  separate 2026-07-28 migration diff (what breaks under the stateless spec and
+  how to fix it). Add `--repo ./src` to also scan source for deprecated
+  primitives, `--strict` to fail on warnings.
+- **Lint a skill**
+  `npx efaimo check --skill ./skills/` validates frontmatter, trigger quality,
+  context budget, file references, and injection patterns.
+- **Gate a pull request on context cost**
+  Save a baseline with `npx efaimo weigh "<server>" --out base.json`, then in CI
+  run `npx efaimo weigh "<server>" --diff base.json --allow-increase 10` to fail
+  when the tool-definition budget grows more than 10 percent.
+
+## Reading the output
+
+Findings carry a stable rule id (E1xx MCP readiness, E12x-E13x MCP quality, S1xx
+skills) and a severity. The letter grade covers quality and skill findings only;
+2026-07-28 readiness items appear separately as an ungraded migration diff. Token
+numbers are o200k estimates unless `--anthropic` is used; see the methodology doc
+for the full method.
+
+## Notes
+
+efaimo is a linter and cost profiler, not a security scanner: its injection checks
+are surface heuristics. For supply-chain security use a dedicated scanner. Full
+rule reference: https://github.com/efaimo-ai/efaimo/blob/main/docs/RULES.md

package/dist/check/check.d.ts

@@ -0,0 +1,31 @@
+import type { CheckReport, Finding, ProbeResults, ServerIntrospection, ServerWeighResult, SkillSetWeighResult } from "../core/types.js";
+import type { ResolvedTarget } from "../targets/resolve.js";
+export interface CheckMcpResult {
+    report: CheckReport;
+    intro: ServerIntrospection;
+    weigh: ServerWeighResult;
+    probes?: ProbeResults;
+}
+export declare function checkMcpTarget(target: Extract<ResolvedTarget, {
+    kind: "stdio" | "http";
+}>, opts?: {
+    timeoutMs?: number;
+    probe?: boolean;
+    repoPath?: string;
+    anthropicApiKey?: string;
+}): Promise<CheckMcpResult>;
+export declare function checkMcpRepoOnly(repoPath: string, label: string): CheckReport;
+export interface SkillReport {
+    name: string;
+    dir: string;
+    report: CheckReport;
+}
+export interface CheckSkillResult {
+    label: string;
+    root: string;
+    perSkill: SkillReport[];
+    /** Set-level findings (e.g. trigger collisions across skills). */
+    setFindings: Finding[];
+    weigh: SkillSetWeighResult;
+}
+export declare function checkSkillSet(pathInput: string, label: string): Promise<CheckSkillResult>;