skillcost 0.0.3__tar.gz

skillcost-0.0.3/.editorconfig

@@ -0,0 +1,64 @@
+# Editor configuration, see http://editorconfig.org
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = tab
+indent_size = 4
+insert_final_newline = true
+trim_trailing_whitespace = true
+max_line_length = 99
+
+# Web
+[*.{html,htm}]
+indent_style = space
+indent_size = 2
+
+[*.{css,scss,sass}]
+indent_style = space
+indent_size = 2
+
+[*.{ts,tsx,js,jsx}]
+indent_style = space
+indent_size = 2
+
+# Data/config
+[*.json]
+indent_style = space
+indent_size = 2
+
+[*.{yaml,yml}]
+indent_style = space
+indent_size = 2
+
+[*.toml]
+indent_style = space
+indent_size = 2
+
+[*.{xml,svg}]
+indent_style = space
+indent_size = 2
+
+# Docs/text
+[*.md]
+indent_style = space
+indent_size = 2
+
+[*.txt]
+indent_style = space
+indent_size = 2
+
+# Scripts/build
+[Makefile]
+indent_style = tab
+
+[*.sh]
+indent_style = tab
+max_line_length = 88
+
+# Languages
+[*.py]
+# Python convention is 4 spaces per PEP 8
+indent_style = space
+max_line_length = 88

skillcost-0.0.3/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

skillcost-0.0.3/.prettierignore

@@ -0,0 +1,6 @@
+# Python files are formatted by ruff, not prettier
+*.py
+*.pyi
+
+# Example markdown files
+examples/*.md

skillcost-0.0.3/.prettierrc

@@ -0,0 +1,3 @@
+{
+	"proseWrap": "always"
+}

skillcost-0.0.3/.vscode/settings.json

@@ -0,0 +1,22 @@
+{
+  "[json]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode",
+    "editor.formatOnSave": true,
+    "editor.formatOnSaveMode": "file"
+  },
+  "[markdown]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode",
+    "editor.formatOnSave": true,
+    "editor.formatOnSaveMode": "file"
+  },
+  "[yaml]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode",
+    "editor.formatOnSave": true,
+    "editor.formatOnSaveMode": "file"
+  },
+  "[python]": {
+    "editor.defaultFormatter": "charliermarsh.ruff",
+    "editor.formatOnSave": true,
+    "editor.formatOnSaveMode": "file"
+  }
+}

skillcost-0.0.3/CLAUDE.md

@@ -0,0 +1 @@
+This project uses `uv` for `venv` and package management.

skillcost-0.0.3/CONTRIBUTING.md

@@ -0,0 +1,49 @@
+# Contributing
+
+## Install Dependencies
+
+Requires Python 3.12+ and uses `task`:
+
+```sh
+# https://taskfile.dev/docs/installation
+brew install go-task
+task check:dependencies
+```
+
+The project uses `uv` for dependency management:
+
+```sh
+uv sync
+```
+
+## Run Tests
+
+```sh
+task test
+```
+
+## Format
+
+```sh
+task format
+```
+
+## Release gate
+
+```sh
+task gate
+```
+
+---
+
+## Submitting Changes
+
+Bug fixes and new features are welcome via pull request.
+
+1. Fork the repository and create a branch from `main`.
+2. Make your changes — include tests for any new behavior.
+3. Run `task gate` to confirm all checks pass.
+4. Open a pull request with a clear description of what changed and why.
+
+For significant changes, open an issue first to discuss the approach before investing time in an
+implementation.

skillcost-0.0.3/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: skillcost
+Version: 0.0.3
+Summary: Estimates the token cost of agent skills and their linked resources
+Requires-Python: >=3.12
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: tiktoken>=0.12.0
+Description-Content-Type: text/markdown
+
+# skillcost
+
+Estimates the token cost of agent skills and their linked resources.
+
+Given a target file (typically a `SKILL.md`), `skillcost` counts tokens and crawls all linked files
+and URLs to produce three cost figures:
+
+| Metric       | Description                                                                     |
+| ------------ | ------------------------------------------------------------------------------- |
+| **Resident** | Tokens loaded on every prompt, just because the skill is installed.             |
+| **Baseline** | Tokens loaded when the skill is invoked — the skill file plus any `@`-includes. |
+| **Maximum**  | Tokens loaded if the agent follows every link in the skill file.                |
+
+This also works on `CLAUDE.md` or any other plain-text UTF-8 file.
+
+## Installation
+
+Requires Python 3.12+ and [uv](https://github.com/astral-sh/uv).
+
+```sh
+uv sync
+```
+
+## Usage
+
+```sh
+uv run python -m main <path/to/file>
+```
+
+Output defaults to human-readable text. Pass `--json` or `--yaml` for machine-readable output.
+
+```sh
+uv run python -m main SKILL.md
+uv run python -m main SKILL.md --json
+uv run python -m main SKILL.md --yaml
+```
+
+### Example output
+
+```
+Token Cost Report
+=================
+  Resident : 97
+  Baseline : 1,940
+  Maximum  : 18,390
+
+Files (24)
+  /path/to/reference/conventions.md                                       926
+  /path/to/reference/utilities.md                                       1,751
+  ...
+
+Links
+  @-directives : 0
+  Local links  : 17
+  HTTP links   : 0
+```
+
+## How links are counted
+
+`skillcost` recognizes two link syntaxes in Markdown files:
+
+- **`@{relative/path}`** — an include directive; the file is always fetched when the skill is
+  invoked, so it counts toward the **baseline** cost.
+- **`[text](relative/path)`** — a standard Markdown link; followed recursively and counted toward
+  the **maximum** cost only.
+
+HTTP links (`https://...`) are fetched and counted toward the maximum cost only.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).

skillcost-0.0.3/README.md

@@ -0,0 +1,71 @@
+# skillcost
+
+Estimates the token cost of agent skills and their linked resources.
+
+Given a target file (typically a `SKILL.md`), `skillcost` counts tokens and crawls all linked files
+and URLs to produce three cost figures:
+
+| Metric       | Description                                                                     |
+| ------------ | ------------------------------------------------------------------------------- |
+| **Resident** | Tokens loaded on every prompt, just because the skill is installed.             |
+| **Baseline** | Tokens loaded when the skill is invoked — the skill file plus any `@`-includes. |
+| **Maximum**  | Tokens loaded if the agent follows every link in the skill file.                |
+
+This also works on `CLAUDE.md` or any other plain-text UTF-8 file.
+
+## Installation
+
+Requires Python 3.12+ and [uv](https://github.com/astral-sh/uv).
+
+```sh
+uv sync
+```
+
+## Usage
+
+```sh
+uv run python -m main <path/to/file>
+```
+
+Output defaults to human-readable text. Pass `--json` or `--yaml` for machine-readable output.
+
+```sh
+uv run python -m main SKILL.md
+uv run python -m main SKILL.md --json
+uv run python -m main SKILL.md --yaml
+```
+
+### Example output
+
+```
+Token Cost Report
+=================
+  Resident : 97
+  Baseline : 1,940
+  Maximum  : 18,390
+
+Files (24)
+  /path/to/reference/conventions.md                                       926
+  /path/to/reference/utilities.md                                       1,751
+  ...
+
+Links
+  @-directives : 0
+  Local links  : 17
+  HTTP links   : 0
+```
+
+## How links are counted
+
+`skillcost` recognizes two link syntaxes in Markdown files:
+
+- **`@{relative/path}`** — an include directive; the file is always fetched when the skill is
+  invoked, so it counts toward the **baseline** cost.
+- **`[text](relative/path)`** — a standard Markdown link; followed recursively and counted toward
+  the **maximum** cost only.
+
+HTTP links (`https://...`) are fetched and counted toward the maximum cost only.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).

skillcost-0.0.3/Taskfile.yml

@@ -0,0 +1,183 @@
+version: "3"
+
+tasks:
+  default:
+    desc: List all available tasks
+    silent: true
+    cmds:
+      - task --list
+
+  # ---------------------------------------------------------------------------
+  # Dependencies
+  # ---------------------------------------------------------------------------
+
+  dependencies:
+    internal: true
+    desc: Check all required dependencies are installed
+    deps:
+      - dependencies:git
+      - dependencies:uv
+      - dependencies:ruff
+      - dependencies:prettier
+
+  dependencies:git:
+    internal: true
+    preconditions:
+      - sh: command -v git
+        msg: |
+          'git' is not installed. Install it via:
+            brew install git
+                -or-
+            https://git-scm.com/downloads
+
+  dependencies:uv:
+    internal: true
+    preconditions:
+      - sh: command -v uv
+        msg: |
+          'uv' is not installed. Install it via:
+            curl -LsSf https://astral.sh/uv/install.sh | sh
+
+  dependencies:ruff:
+    internal: true
+    preconditions:
+      - sh: command -v ruff
+        msg: |
+          'ruff' is not installed. Install it via:
+            uv tool install ruff
+
+  dependencies:prettier:
+    internal: true
+    preconditions:
+      - sh: command -v prettier
+        msg: |
+          'prettier' is not installed. Install it via:
+            npm install -g prettier
+                -or-
+            deno install -g -f --allow-env --allow-sys --allow-read --allow-write npm:prettier
+
+  # ---------------------------------------------------------------------------
+  # Checks
+  # ---------------------------------------------------------------------------
+
+  check:dependencies:
+    desc: Check all required dependencies are installed
+    silent: true
+    deps: [dependencies]
+    cmds:
+      - printf '✅ All dependencies satisfied\n'
+
+  check:git:
+    desc: Check git repo is clean and in sync
+    deps: [dependencies:git]
+    cmds:
+      - vendor/git-clean-check
+
+  check:test:
+    desc: Run tests with a simple non-redrawing reporter
+    deps: [dependencies:uv]
+    cmds:
+      - uv run python -m pytest tests/ -qq --tb=line
+
+  check:lint:
+    desc: Fail if any lint errors are found
+    deps: [dependencies:ruff]
+    cmds:
+      - ruff check .
+
+  check:format:
+    desc: Fail if any files have unformatted code
+    deps: [dependencies:ruff, dependencies:prettier]
+    cmds:
+      - ruff format --check .
+      - prettier --check .
+
+  # ---------------------------------------------------------------------------
+  # Testing
+  # ---------------------------------------------------------------------------
+
+  test:
+    desc: Run all tests
+    deps: [dependencies:uv]
+    cmds:
+      - uv run python -m pytest tests/
+
+  test:watch:
+    desc: Run tests in watch mode
+    deps: [dependencies:uv]
+    cmds:
+      - uv run pytest-watch tests/
+
+  # ---------------------------------------------------------------------------
+  # Formatting
+  # ---------------------------------------------------------------------------
+
+  format:
+    desc: Format all source files
+    deps: [dependencies:ruff, dependencies:prettier]
+    cmds:
+      - ruff format .
+      - prettier --write .
+
+  # ---------------------------------------------------------------------------
+  # Release
+  # ---------------------------------------------------------------------------
+
+  gate:
+    desc: Run all release gate checks
+    deps:
+      - check:lint
+      - check:format
+      - check:git
+      - check:test
+
+  release-patch:
+    desc: Release a patch version
+    silent: true
+    vars:
+      VERSION:
+        sh: tr -d '[:space:]' < VERSION
+      VERSION_TMP:
+        sh: mktemp
+    cmds:
+      - vendor/semver bump patch "{{.VERSION}}" > "{{.VERSION_TMP}}"
+      - mv "{{.VERSION_TMP}}" VERSION
+      - printf '🚀 bumped to v%s\n' "$(tr -d '[:space:]' < VERSION)"
+      - vendor/pyproject-version-sync VERSION
+      - vendor/pyproject-version-commit
+      - git push origin main
+      - vendor/version-tag VERSION
+
+  release-minor:
+    desc: Release a minor version
+    silent: true
+    vars:
+      VERSION:
+        sh: tr -d '[:space:]' < VERSION
+      VERSION_TMP:
+        sh: mktemp
+    cmds:
+      - vendor/semver bump minor "{{.VERSION}}" > "{{.VERSION_TMP}}"
+      - mv "{{.VERSION_TMP}}" VERSION
+      - printf '🚀 bumped to v%s\n' "$(tr -d '[:space:]' < VERSION)"
+      - vendor/pyproject-version-sync VERSION
+      - vendor/pyproject-version-commit
+      - git push origin main
+      - vendor/version-tag VERSION
+
+  release-major:
+    desc: Release a major version
+    silent: true
+    vars:
+      VERSION:
+        sh: tr -d '[:space:]' < VERSION
+      VERSION_TMP:
+        sh: mktemp
+    cmds:
+      - vendor/semver bump major "{{.VERSION}}" > "{{.VERSION_TMP}}"
+      - mv "{{.VERSION_TMP}}" VERSION
+      - printf '🚀 bumped to v%s\n' "$(tr -d '[:space:]' < VERSION)"
+      - vendor/pyproject-version-sync VERSION
+      - vendor/pyproject-version-commit
+      - git push origin main
+      - vendor/version-tag VERSION

skillcost-0.0.3/VERSION

@@ -0,0 +1 @@
+0.0.3

skillcost-0.0.3/examples/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: data-transformer
+description:
+  Transforms raw JSON payloads into a normalized schema, applies field mappings, and validates
+  against a JSON Schema definition before emitting the result.
+---
+
+# Data Transformer Skill
+
+This skill normalises incoming JSON data and validates it against a schema.
+
+## Usage
+
+Pass a JSON payload and a schema file path. The skill returns the transformed, validated output or
+raises a structured error.
+
+## Implementation notes
+
+See [helpers](sub/helpers.md) for shared utility functions used by this skill.
+
+Also references the shared [config](sub/config.md) module.

skillcost-0.0.3/examples/simple.md

@@ -0,0 +1,16 @@
+# Simple Example
+
+A standalone markdown file with no links or directives.
+
+This file is used as a baseline to verify that the token counter works correctly on a plain
+document with no external references.
+
+## Section A
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore
+et dolore magna aliqua.
+
+## Section B
+
+Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
+consequat.

skillcost-0.0.3/examples/sub/config.md

@@ -0,0 +1,15 @@
+# Configuration
+
+Environment and runtime configuration for skills.
+
+## Variables
+
+| Variable       | Default | Description            |
+| -------------- | ------- | ---------------------- |
+| `LOG_LEVEL`    | `INFO`  | Logging verbosity      |
+| `TIMEOUT_SECS` | `30`    | HTTP request timeout   |
+| `MAX_RETRIES`  | `3`     | Maximum retry attempts |
+
+## Loading
+
+Configuration is loaded from environment variables at startup.

skillcost-0.0.3/examples/sub/helpers.md

@@ -0,0 +1,13 @@
+# Helper Utilities
+
+Shared utility functions referenced by skills and other markdown files.
+
+## parse_json
+
+Parses a UTF-8 encoded JSON string and returns a Python dict. Raises `ValueError` on malformed
+input.
+
+## validate_schema
+
+Validates a dict against a JSON Schema definition. Returns `True` on success, raises `SchemaError`
+on failure.

skillcost-0.0.3/examples/with_refs.md

@@ -0,0 +1,18 @@
+# With References
+
+This file demonstrates all three link types supported by skillcost.
+
+## @-directives (always-included references)
+
+@{simple.md}
+
+The file above is always included in the baseline token count.
+
+## Local links (included in maximum only)
+
+See [helper utilities](sub/helpers.md) for shared functions. See [configuration](sub/config.md) for
+environment settings.
+
+## Remote links (included in maximum only)
+
+Documentation: [Python pathlib](https://docs.python.org/3/library/pathlib.html)

skillcost-0.0.3/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "skillcost"
+version = "0.0.3"
+description = "Estimates the token cost of agent skills and their linked resources"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "pyyaml>=6.0.3",
+    "tiktoken>=0.12.0",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+]
+
+[project.scripts]
+skillcost = "skillcost:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/skillcost"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]