sutras 0.1.2__tar.gz

sutras-0.1.2/.gitignore

@@ -0,0 +1,143 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# PEP 582
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# uv
+# Note: uv.lock should be committed to ensure reproducible builds
+
+# User skills directory (skills created with sutras new)
+.claude/
+
+# Project
+plan.md
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db

sutras-0.1.2/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2025 Kumar Anirudha
+
+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.

sutras-0.1.2/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: sutras
+Version: 0.1.2
+Summary: Devtool for creating, testing, and distributing Anthropic Agent Skills with lifecycle management and Skill ABI
+Project-URL: Homepage, https://github.com/anistark/sutras
+Project-URL: Documentation, https://github.com/anistark/sutras#readme
+Project-URL: Repository, https://github.com/anistark/sutras
+Author-email: Kumar Anirudha <oss@anirudha.dev>
+License: MIT
+License-File: LICENSE
+Keywords: agent,ai,anthropic,cli,devtools,skills
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: click>=8.0.0
+Requires-Dist: jinja2>=3.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: eval
+Requires-Dist: ragas>=0.1.0; extra == 'eval'
+Description-Content-Type: text/markdown
+
+# Sutras
+
+**Devtool for Anthropic Agent Skills with lifecycle management.**
+
+![Sutras Architecture](./docs/static/sutras-architecture.png)
+
+Sutras is a CLI tool and library for creating, validating, and managing [Anthropic Agent Skills](https://platform.claude.com/docs/en/agent-sdk/skills). It provides scaffolding, validation, and a standardized Skill ABI for better skill organization and quality.
+
+[![PyPI - Version](https://img.shields.io/pypi/v/sutras)](https://pypi.org/project/sutras/)
+[![PyPI Downloads](https://static.pepy.tech/badge/sutras/month)](https://pypi.org/project/sutras/)
+![PyPI - Status](https://img.shields.io/pypi/status/sutras)
+[![Open Source](https://img.shields.io/badge/open-source-brightgreen)](https://github.com/anistark/sutras)
+![maintenance-status](https://img.shields.io/badge/maintenance-actively--developed-brightgreen.svg)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+## Key Features
+
+- **Scaffold**: Generate skills with proper structure and best-practice templates
+- **Validate**: Check skill format, metadata, and quality standards
+- **Discover**: List and inspect available skills in your workspace
+- **Manage**: Organize skills with versioning and metadata
+
+## Why Sutras?
+
+Creating Anthropic Skills manually requires:
+- Writing SKILL.md files with correct YAML frontmatter
+- Managing metadata and descriptions
+- Ensuring consistent structure
+- Validating format and quality
+
+Sutras automates this with simple CLI commands.
+
+## Installation
+
+```sh
+pip install sutras
+```
+
+Or with uv:
+
+```sh
+uv pip install sutras
+```
+
+## Quick Start
+
+### Create a New Skill
+
+```sh
+sutras new my-skill --description "What this skill does and when to use it"
+```
+
+This creates:
+```sh
+.claude/skills/my-skill/
+├── SKILL.md           # Skill definition with YAML frontmatter
+├── sutras.yaml        # Metadata (version, author, tests, etc.)
+└── examples.md        # Usage examples
+```
+
+### List Skills
+
+```sh
+sutras list
+```
+
+### View Skill Details
+
+```sh
+sutras info my-skill
+```
+
+### Validate a Skill
+
+```sh
+sutras validate my-skill
+
+# Strict mode (warnings become errors)
+sutras validate my-skill --strict
+```
+
+## CLI Reference
+
+```sh
+# Create a new skill
+sutras new <name> [--description TEXT] [--author TEXT] [--global]
+
+# List skills
+sutras list [--local/--no-local] [--global/--no-global]
+
+# Show skill details
+sutras info <name>
+
+# Validate skill
+sutras validate <name> [--strict]
+```
+
+### Coming Soon
+- `sutras test` - Run skill tests
+- `sutras eval` - Evaluate with metrics
+- `sutras build` - Package for distribution
+- `sutras publish` - Share to registry
+
+## Skill Structure
+
+Every skill contains:
+
+### SKILL.md (required)
+Standard Anthropic Skills format with YAML frontmatter:
+```yaml
+---
+name: my-skill
+description: What it does and when Claude should use it
+allowed-tools: Read, Write  # Optional
+---
+
+# My Skill
+
+Instructions for Claude on how to use this skill...
+```
+
+### sutras.yaml (recommended)
+Extended metadata for lifecycle management:
+```yaml
+version: "1.0.0"
+author: "Your Name"
+license: "MIT"
+
+capabilities:
+  tools: [Read, Write]
+
+distribution:
+  tags: ["automation", "pdf"]
+  category: "document-processing"
+```
+
+### Supporting Files (optional)
+- `examples.md` - Usage examples
+- Additional resources as needed
+
+## Skill Locations
+
+Skills are stored in:
+- **Project**: `.claude/skills/` (shared via git)
+- **Global**: `~/.claude/skills/` (personal only)
+
+Use `--global` flag with `sutras new` to create global skills.
+
+## Library Usage
+
+```python
+from sutras import SkillLoader
+
+loader = SkillLoader()
+skills = loader.discover()           # Find all skills
+skill = loader.load("my-skill")      # Load specific skill
+
+print(skill.name)
+print(skill.description)
+print(skill.version)
+```
+
+## Examples
+
+See [examples/skills/](./examples/skills/) for sample skills demonstrating best practices.
+
+## Contributing
+
+Contributions welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md) for:
+- Development setup
+- Code style guidelines
+- Testing requirements
+- PR process
+
+## License
+
+MIT License - see [LICENSE](./LICENSE)

sutras-0.1.2/README.md

@@ -0,0 +1,177 @@
+# Sutras
+
+**Devtool for Anthropic Agent Skills with lifecycle management.**
+
+![Sutras Architecture](./docs/static/sutras-architecture.png)
+
+Sutras is a CLI tool and library for creating, validating, and managing [Anthropic Agent Skills](https://platform.claude.com/docs/en/agent-sdk/skills). It provides scaffolding, validation, and a standardized Skill ABI for better skill organization and quality.
+
+[![PyPI - Version](https://img.shields.io/pypi/v/sutras)](https://pypi.org/project/sutras/)
+[![PyPI Downloads](https://static.pepy.tech/badge/sutras/month)](https://pypi.org/project/sutras/)
+![PyPI - Status](https://img.shields.io/pypi/status/sutras)
+[![Open Source](https://img.shields.io/badge/open-source-brightgreen)](https://github.com/anistark/sutras)
+![maintenance-status](https://img.shields.io/badge/maintenance-actively--developed-brightgreen.svg)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+## Key Features
+
+- **Scaffold**: Generate skills with proper structure and best-practice templates
+- **Validate**: Check skill format, metadata, and quality standards
+- **Discover**: List and inspect available skills in your workspace
+- **Manage**: Organize skills with versioning and metadata
+
+## Why Sutras?
+
+Creating Anthropic Skills manually requires:
+- Writing SKILL.md files with correct YAML frontmatter
+- Managing metadata and descriptions
+- Ensuring consistent structure
+- Validating format and quality
+
+Sutras automates this with simple CLI commands.
+
+## Installation
+
+```sh
+pip install sutras
+```
+
+Or with uv:
+
+```sh
+uv pip install sutras
+```
+
+## Quick Start
+
+### Create a New Skill
+
+```sh
+sutras new my-skill --description "What this skill does and when to use it"
+```
+
+This creates:
+```sh
+.claude/skills/my-skill/
+├── SKILL.md           # Skill definition with YAML frontmatter
+├── sutras.yaml        # Metadata (version, author, tests, etc.)
+└── examples.md        # Usage examples
+```
+
+### List Skills
+
+```sh
+sutras list
+```
+
+### View Skill Details
+
+```sh
+sutras info my-skill
+```
+
+### Validate a Skill
+
+```sh
+sutras validate my-skill
+
+# Strict mode (warnings become errors)
+sutras validate my-skill --strict
+```
+
+## CLI Reference
+
+```sh
+# Create a new skill
+sutras new <name> [--description TEXT] [--author TEXT] [--global]
+
+# List skills
+sutras list [--local/--no-local] [--global/--no-global]
+
+# Show skill details
+sutras info <name>
+
+# Validate skill
+sutras validate <name> [--strict]
+```
+
+### Coming Soon
+- `sutras test` - Run skill tests
+- `sutras eval` - Evaluate with metrics
+- `sutras build` - Package for distribution
+- `sutras publish` - Share to registry
+
+## Skill Structure
+
+Every skill contains:
+
+### SKILL.md (required)
+Standard Anthropic Skills format with YAML frontmatter:
+```yaml
+---
+name: my-skill
+description: What it does and when Claude should use it
+allowed-tools: Read, Write  # Optional
+---
+
+# My Skill
+
+Instructions for Claude on how to use this skill...
+```
+
+### sutras.yaml (recommended)
+Extended metadata for lifecycle management:
+```yaml
+version: "1.0.0"
+author: "Your Name"
+license: "MIT"
+
+capabilities:
+  tools: [Read, Write]
+
+distribution:
+  tags: ["automation", "pdf"]
+  category: "document-processing"
+```
+
+### Supporting Files (optional)
+- `examples.md` - Usage examples
+- Additional resources as needed
+
+## Skill Locations
+
+Skills are stored in:
+- **Project**: `.claude/skills/` (shared via git)
+- **Global**: `~/.claude/skills/` (personal only)
+
+Use `--global` flag with `sutras new` to create global skills.
+
+## Library Usage
+
+```python
+from sutras import SkillLoader
+
+loader = SkillLoader()
+skills = loader.discover()           # Find all skills
+skill = loader.load("my-skill")      # Load specific skill
+
+print(skill.name)
+print(skill.description)
+print(skill.version)
+```
+
+## Examples
+
+See [examples/skills/](./examples/skills/) for sample skills demonstrating best practices.
+
+## Contributing
+
+Contributions welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md) for:
+- Development setup
+- Code style guidelines
+- Testing requirements
+- PR process
+
+## License
+
+MIT License - see [LICENSE](./LICENSE)

sutras-0.1.2/examples/README.md

@@ -0,0 +1,106 @@
+# Example Skills
+
+This directory contains example skills demonstrating how to build Anthropic Agent Skills with Sutras.
+
+## Directory Structure
+
+```sh
+examples/
+└── skills/
+    └── hello-claude/      # Simple greeting skill
+        ├── SKILL.md       # Anthropic Skills format with YAML frontmatter
+        ├── sutras.yaml    # Sutras ABI metadata
+        └── examples.md    # Detailed usage examples
+```
+
+## Using Example Skills
+
+### View Example Skills
+
+You can inspect the example skills to understand the structure:
+
+```sh
+# View the SKILL.md
+cat examples/skills/hello-claude/SKILL.md
+
+# View the Sutras ABI
+cat examples/skills/hello-claude/sutras.yaml
+```
+
+### Try the Examples
+
+To try the example skills with Claude:
+
+```sh
+# Copy to your skills directory
+cp -r examples/skills/hello-claude .claude/skills/
+
+# View skill info
+sutras info hello-claude
+
+# Validate the skill
+sutras validate hello-claude
+
+# List all skills
+sutras list
+```
+
+## Creating Your Own Skills
+
+Use these examples as templates:
+
+```sh
+# Create a new skill
+sutras new my-skill --description "Detailed description of what this skill does and when to use it"
+
+# This creates:
+# .claude/skills/my-skill/
+# ├── SKILL.md
+# ├── sutras.yaml
+# └── examples.md
+
+# Edit the files to customize your skill
+```
+
+## Example Skill: hello-claude
+
+The `hello-claude` skill demonstrates:
+
+1. **SKILL.md Structure**: Proper YAML frontmatter with name, description, and allowed-tools
+2. **Clear Instructions**: Step-by-step guidance for Claude
+3. **When to Use**: Specific trigger scenarios
+4. **Examples**: Concrete use cases
+
+### Key Features Demonstrated
+
+- **Name**: `hello-claude` (lowercase, hyphen-separated)
+- **Description**: Detailed explanation including what it does and when Claude should use it
+- **Allowed Tools**: `Read, Write` (restricts which tools Claude can use)
+- **Instructions**: Clear, numbered steps
+- **Examples**: Multiple usage scenarios
+
+### Sutras ABI Metadata
+
+The `sutras.yaml` file shows:
+
+- **Version**: Semantic versioning (`1.0.0`)
+- **Author**: Skill author information
+- **License**: License identifier (MIT)
+- **Capabilities**: Tool declarations
+- **Distribution**: Tags, category, keywords for discovery
+
+## Best Practices
+
+When creating skills based on these examples:
+
+1. **Description is Critical**: Make it detailed with specific keywords Claude can match
+2. **Be Specific**: Include file types, actions, and trigger words
+3. **Clear Instructions**: Number steps and be explicit
+4. **Provide Examples**: Show concrete usage scenarios
+5. **Test with Validation**: Run `sutras validate` before using
+
+## Learn More
+
+- [Anthropic Skills Documentation](https://platform.claude.com/docs/en/agent-sdk/skills)
+- [Sutras README](../README.md)
+- Create your first skill: `sutras new <skill-name>`

sutras-0.1.2/examples/skills/hello-claude/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: hello-claude
+description: A simple greeting skill that demonstrates Anthropic Skills structure. Use when you want to greet users or show how skills work. Perfect for testing and examples.
+allowed-tools: Read, Write
+---
+
+# Hello Claude
+
+A demonstration skill showing the basic structure of an Anthropic Agent Skill
+managed with Sutras.
+
+## Instructions
+
+When this skill is invoked:
+
+1. Greet the user warmly
+2. Explain that this is an example skill
+3. Mention that it's built with the Sutras devtool
+4. Offer to show them other available skills
+
+## When to Use
+
+Use this skill when:
+- User asks for a greeting or hello
+- User wants to test skill functionality
+- User asks "what skills do you have?" or similar
+- You need a simple example to demonstrate
+
+## Examples
+
+**Example 1: Simple Greeting**
+```
+User: Hello!
+Claude: [invokes hello-claude skill]
+Output: Hello! I'm Claude, and I'm using the hello-claude skill...
+```
+
+**Example 2: Skill Demonstration**
+```
+User: Show me how skills work
+Claude: [invokes hello-claude skill]
+Output: Let me demonstrate with this hello-claude skill...
+```
+
+## Notes
+
+This skill is intentionally simple to serve as a template and reference
+for creating new skills with Sutras.