Project Structure

Overview of the Sutras codebase organization.

Directory Layout

sutras/
├── src/sutras/             # Main package (src layout)
│   ├── __init__.py
│   ├── core/
│   │   ├── __init__.py
│   │   ├── skill.py        # Skill model (SKILL.md + sutras.yaml)
│   │   ├── abi.py          # Skill ABI definitions
│   │   ├── loader.py       # Skill discovery and loading
│   │   ├── builder.py      # Skill packaging
│   │   ├── test_runner.py  # Test framework
│   │   ├── evaluator.py    # Evaluation system
│   │   ├── config.py       # Global configuration
│   │   ├── naming.py       # Skill naming system
│   │   ├── registry.py     # Registry management
│   │   ├── installer.py    # Skill installation
│   │   ├── publisher.py    # Skill publishing
│   │   ├── semver.py       # Semantic versioning and constraints
│   │   ├── lockfile.py     # Lock file management
│   │   └── resolver.py     # Dependency resolution
│   ├── cli/
│   │   ├── __init__.py
│   │   └── main.py         # CLI commands
│   └── data/
│       └── skills/sutras/
│           └── SKILL.md    # Bundled skill (deployed by `sutras setup`)
├── pi/                     # Pi integration (published to npm as `sutras`)
│   ├── package.json        # npm package manifest
│   ├── extensions/
│   │   └── sutras.ts       # Pi extension (/sutras command)
│   └── skills/
│       └── sutras/
│           └── SKILL.md    # Agent skill for LLM context
├── scripts/
│   └── sync_pi.py          # Auto-generates pi files from CLI introspection
├── examples/
│   └── skills/
│       └── hello-claude/
│           ├── SKILL.md
│           ├── sutras.yaml
│           └── examples.md
├── tests/
├── pyproject.toml          # Project config (hatchling + uv)
├── uv.lock
├── LICENSE
└── README.md

Core Modules

Module	Responsibility
skill.py	Skill model representing SKILL.md + sutras.yaml
abi.py	Skill ABI (Application Binary Interface) definitions
loader.py	Discovering and loading skills from disk
builder.py	Building distributable packages
test_runner.py	Running skill tests
evaluator.py	Evaluating skill quality
registry.py	Managing skill registries
installer.py	Installing skills from various sources
publisher.py	Publishing skills to registries
resolver.py	Resolving skill dependencies

Pi Integration (pi/)

The pi/ directory is published to npm as the sutras package. It contains:

File	Purpose
extensions/sutras.ts	Pi extension with /sutras command
skills/sutras/SKILL.md	Agent skill for LLM context
package.json	npm package manifest

Both SKILL.md files (in pi/ and src/sutras/data/) are auto-generated by scripts/sync_pi.py from the Click CLI. Run just sync-pi after adding CLI commands and just check-sync to verify sync in CI.

User Skills Directory

When you create skills with sutras new, they’re placed in:

Location	Purpose
.claude/skills/	Project skills (shared via git)
~/.claude/skills/	Global skills (personal, not committed)

These follow the Anthropic Skills directory convention.