Agent skill

angreal-authoring

This skill should be used when the user asks to "create an angreal task", "write a task file", "add a command to angreal", "make a new task", "organize tasks with groups", "use @angreal.command", "use command_group", or needs guidance on task file structure, the @command decorator, command groups, naming conventions, or task organization within an existing angreal project.

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-authoring

SKILL.md

Authoring Angreal Tasks

Create task files within an existing angreal project. For initializing new projects, see the angreal-init skill.

Task File Location

Task files live in .angreal/ at your project root:

my-project/
├── .angreal/
│   ├── task_dev.py       # Development tasks
│   ├── task_test.py      # Testing tasks
│   ├── task_docs.py      # Documentation tasks
│   └── utils.py          # Shared utilities (optional)
├── src/
└── ...

Naming convention: Files must be named task_*.py to be discovered.

The @command Decorator

Every task needs the @command decorator:

python
import angreal

@angreal.command(
    name="build",              # Command name (kebab-case)
    about="Build the project"  # Short description for --help
)
def build():
    print("Building...")
    return 0  # Success

Name Inference

If you omit name, it derives from the function:

python
@angreal.command(about="Check dependencies")
def check_deps():  # Creates command "check-deps"
    pass

Command Groups

Organize related commands with groups:

python
import angreal

# Create reusable group decorator
test = angreal.command_group(name="test", about="Testing commands")

@test()  # Group decorator FIRST
@angreal.command(name="all", about="Run all tests")
def test_all():
    pass

@test()
@angreal.command(name="unit", about="Run unit tests")
def test_unit():
    pass

Creates: angreal test all, angreal test unit

Nested Groups

python
docker = angreal.command_group(name="docker", about="Docker commands")
compose = angreal.command_group(name="compose", about="Compose commands")

@docker()
@compose()
@angreal.command(name="up", about="Start services")
def docker_compose_up():
    pass

Creates: angreal docker compose up

Getting Project Root

Important: get_root() returns .angreal/ directory, not project root:

python
import angreal

@angreal.command(name="build", about="Build project")
def build():
    angreal_dir = angreal.get_root()        # .angreal/ directory
    project_root = angreal_dir.parent       # Actual project root
    # Use project_root for file operations

Shared Modules

Create shared utilities in .angreal/:

python
# .angreal/utils.py
import angreal

def get_project_root():
    return angreal.get_root().parent

def run_in_project(cmd):
    import subprocess
    return subprocess.run(cmd, cwd=get_project_root())
python
# .angreal/task_build.py
import angreal
from utils import run_in_project

@angreal.command(name="build", about="Build project")
def build():
    result = run_in_project(["cargo", "build"])
    return result.returncode

Best Practices

Naming Conventions

Type Convention Example
Task files task_<domain>.py task_test.py
Commands kebab-case check-deps
Functions snake_case check_deps
Groups short nouns/verbs test, dev, docs

Error Handling

python
@angreal.command(name="build", about="Build project")
def build():
    project_root = angreal.get_root().parent

    # Check prerequisites first
    if not (project_root / "Cargo.toml").exists():
        print("Error: Cargo.toml not found")
        return 1

    # Attempt operation
    try:
        do_build()
        print("Build succeeded!")
        return 0
    except Exception as e:
        print(f"Build failed: {e}")
        return 1

Return Codes

Code Meaning
0 or None Success
1 General failure
2 Invalid arguments

Organization

  • One domain per file: task_test.py, task_build.py
  • Group related commands: Use command_group for related tasks
  • Limit nesting: Two group levels maximum
  • Single responsibility: Each task does one thing well

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