Agent skill

angreal-usage

This skill should be used when the user asks to "run an angreal task", "execute angreal command", "discover angreal tasks", "list angreal commands", "use angreal tree", "find available tasks", "what tasks are available", or needs guidance on running tasks, interpreting task output, task workflows, or choosing the right task for a job.

View SKILL.md on GitHub Repository
Stars 11
Forks 5

Install this agent skill to your Project

npx add-skill https://github.com/angreal/angreal/tree/main/plugin/skills/angreal-usage

SKILL.md

Using Angreal Tasks

Learn to discover, run, and chain angreal tasks effectively.

Prerequisites

  • Working within an angreal project (has .angreal/ directory)
  • angreal CLI installed and available

Discovering Tasks

Quick Discovery

bash
angreal tree

Shows all commands with arguments and short descriptions:

dev: development utilities
  check-deps - Verify required development tools are installed
test: commands for testing the application
  all - Run complete test suite
  rust [--unit-only] - Run Rust tests
docs: commands for documentation
  build [--draft] - Build documentation site

Detailed Discovery (AI Guidance)

bash
angreal tree --long

Includes full ToolDescription prose for each command:

  • When to use - Appropriate scenarios
  • When NOT to use - Situations to avoid
  • Examples - Concrete invocations
  • Risk level - safe, read_only, or destructive

Traditional Help

bash
angreal --help              # List all commands
angreal test rust --help    # Help for specific command

Running Tasks

Basic Invocation

bash
angreal <group> <command> [arguments]

# Examples
angreal test all
angreal test rust --unit-only
angreal build --release
angreal docs serve --prod

Arguments

Flags (boolean switches):

bash
angreal build --release
angreal test rust --unit-only

Value arguments:

bash
angreal deploy --version v1.2.3
angreal test completion --shell=bash

Output and Exit Codes

  • Exit code 0 = success
  • Non-zero exit code = failure
bash
angreal test all && angreal deploy  # Chain with &&

Common Workflows

Before Committing

bash
angreal test unit      # Fast unit tests first
angreal test all       # Full suite if units pass
angreal lint check     # Check code style

Release Process

bash
angreal test all           # Ensure tests pass
angreal build --release    # Create release build
angreal docs build         # Update documentation
angreal deploy staging     # Deploy to staging

Debugging

bash
angreal test <specific-test> --verbose  # Verbose output
# Check stdout/stderr for error details
# Fix issue, re-run specific test
angreal test all                        # Verify no regressions

Task Groups

Tasks are organized by function:

Group Purpose
dev Development utilities
test Testing commands
docs Documentation
build Build and compilation
deploy Deployment and release

Groups can nest: angreal docker compose up

Choosing the Right Task

  1. Run angreal tree to see available commands
  2. Use angreal tree --long for detailed guidance
  3. Start with read-only tasks to explore safely
  4. Trust ToolDescriptions - they're written to guide you

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

angreal/angreal

angreal-arguments

This skill should be used when the user asks to "add arguments to a task", "use @angreal.argument", "add flags to command", "make argument required", "add optional parameter", "use python_type", "handle multiple values", or needs guidance on the @argument decorator, argument types, flags, default values, or CLI argument handling in angreal tasks.

11 5
Explore
angreal/angreal

angreal-templates

This skill should be used when the user asks to "create an angreal template", "make a project template", "build a reusable template", "share a template", "write angreal.toml", "use Tera templating", "template variables", "conditional templates", or needs guidance on creating templates that others can consume via `angreal init`, template configuration, Tera syntax, or publishing templates.

11 5
Explore
angreal/angreal

angreal-patterns

This skill should be used when the user asks to "test angreal tasks", "mock angreal", "document tasks", "angreal best practices", "error handling in tasks", "subprocess patterns", "dry run mode", "verbose mode", or needs guidance on testing patterns, development workflows, documentation strategies, or common implementation patterns for angreal tasks.

11 5
Explore
angreal/angreal

angreal-integrations

This skill should be used when the user asks to "use Git in a task", "manage virtual environments", "use Docker Compose", "clone a repository", "create a venv", "run docker-compose", "use angreal.integrations", "render a template", "scaffold files", "generate files from template", "use render_template", "use render_directory", "use Flox", "flox environment", "cross-language environment", "flox services", "@flox_required", or needs guidance on the built-in Git, VirtualEnv, Docker, Flox, or Tera templating integrations available in angreal tasks.

11 5
Explore
angreal/angreal

angreal-tool-descriptions

This skill should be used when the user asks to "write a ToolDescription", "add AI guidance to task", "document task for AI", "set risk level", "write tool description prose", "guide AI agents", or needs guidance on angreal.ToolDescription, risk_level, writing effective descriptions for AI agent consumption, or making tasks AI-friendly.

11 5
Explore
angreal/angreal

angreal-init

This skill should be used when the user asks to "create an angreal project", "initialize angreal", "set up angreal", "add angreal to project", "start new angreal project", "create .angreal directory", or needs guidance on setting up angreal in a new or existing project, project templates, or initial task file structure.

11 5
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results