Teach your AI agent how to build toolkit apps (ADN article)

Pipeline Integrations
, , , ,
1

Written by @sergio.leon

Table of contents

Introduction

Building a new app for Flow Production Tracking (Flow PTR) touches a lot of ground before a single line of business logic gets written: locating the right pipeline configuration, checking on a centralized or distributed setup, setting up a sandbox so you do not develop against production, cloning a starter template with the right naming convention, wiring hooks, filling in the app manifest, developing the logic, building the UI, testing, and eventually tagging a release. It is all documented, but it is spread across several help pages, and it takes time to have the workflow, possibilities, and decisions clear.

Now, with AI-powered coding, we could ask an agent to “add a Flow PTR app that snapshots the viewport and adds a note in Flow PTR”. Because AI models are trained in general development practices, they probably have no clear way to know all the peculiar aspects that come with developing an app in Flow PTR, or how to better plan for it.

That is exactly the gap agent skills are meant to close, and it is why we just added a new skill called flow-ptr-appto our skill repository from Autodesk Platform Services and cloud industries. It is an open-source collection of skills already introduced in Supercharge your APS development: agent skills. If you build pipeline tools for Flow Production Tracking, or you are evaluating what an AI agent can responsibly automate in your studio pipeline, this one is for you.

What is a skill?

A skill is a self-contained instruction set, typically a folder of Markdown files, that teaches an AI agent how to carry out a specific, well-defined task. In our case, that task is building a Flow PTR app. Once a skill is installed, you can trigger it explicitly by using it as a command, such as /flow-ptr-app in your LLM CLI, or an agent can load it and apply its instructions automatically when your prompts call for it. Within the scope of an AI agent, the skill turns the agent into a domain expert with the knowledge to guide you and resolve tasks efficiently in that domain.

Think of it as portable domain expertise: instead of re-explaining your team conventions to the agent in every session, you write them down once, and the skill loads automatically whenever the conversation matches its trigger phrases.

Three properties make skills worth adopting over a pile of ad-hoc prompts:

  • Composable, progressive loading — a skill can point into other reference files, and an agent only pulls in the details it needs for the step it is performing, instead of front-loading everything.

  • Shareable — drop the folder into any teammate’s skills directory, or the equivalent location for your agent, and they get the same know-how with no tribal knowledge required.

For a fuller picture of the concept itself, agentskills.io is a good next stop.

What does our flow-ptr-app skill actually do?

The skill turns the agent into a guide following a spec-driven lifecycle for building a Flow PTR Toolkit app. Before starting to code, it helps capture intent, check for reuse, plan, write, and validate a specification. Then it guides the implementation, helps verify the work, supports the release process, and assists with testing while keeping the specification up to date.

This skill follows a spec-driven development process by default, where detailed natural-language specifications act as the primary source of truth for the development process. It helps define clear intent, establish the architecture, support development, and make validation easier.

The spec-driven skill lifecycle

This spec-driven skill is organized into nine phases. At every phase, the agent is instructed to tell you which phase it is in so you can track progress and step in between them rather than getting a wall of unexplained changes.

  1. Requirements/Intent capture — define what the app should do, where it runs, whether it needs a UI or hooks, and whether any implemented app already covers this need.

  2. Specification — document the name, dependencies, target context, entities touched, settings in the schema, hooks to expose, any possible acceptance criteria, and then validate for gaps before code is planned.

  3. Plan/Design — locate the pipeline configuration, find or create a development sandbox, decide where the app source will live and how it gets installed, and separate core logic from UI.

  4. Scaffold — clone tk-multi-starterapp, or a better-fit existing app, under the correct name.

  5. Implement against spec — fill in info.yml, write app.py and dialog.py, and declare hooks.

  6. Verify against spec — use Reload and Restart, test in tk-shell first, then verify in Desktop, DCC, or web UI against acceptance criteria rather than only checking whether it runs.

  7. Change management — commit to the sandbox configuration only; future asks go back through the specification, not straight into the code.

  8. Release to production — flag side effects, tag a release, and push the sandbox configuration forward.

  9. Maintenance — route bug reports and new asks back through the specification rather than applying silent patches.

‘How-to’ reference guides

Under the hood, each phase links to a focused reference file — thirteen in total now — so the skill itself stays short, and the agent only reads the ‘how-to’ guide it needs for the step it is on. If you already have your own process and just want the ‘how-to’ guide for one step, this table shows a list of the standalone references, because every file is self-contained.

How-to referenced guide What it covers
existing-functionality Toolkit’s customization ladder, GitHub org search for reuse, and reference apps to study for architecture patterns
locating-config Finding the project’s PipelineConfiguration and detecting centralized vs. distributed setup
sandbox-dev-configuration Finding or creating a dev sandbox instead of developing against production
cloning-template Naming convention and where/how to clone the starter template, or another existing app
install-app Wiring the app into an engine/environment via a dev descriptor or install_app / switch_app
app-manifest info.yml manifest fields — engines, settings schema, frameworks, version requirements
app-hooks When and how to add a hook, and how studios override it per project
implement-app app.py / dialog.py structure, UI vs. no-UI paths, web menu actions, custom events
test-app Reload-and-Restart loop, tk-shell-first testing, granting testers sandbox access
release Versioning, tagging a release, and pushing config changes to production
centralized-config Access checks and on-disk layout for centralized/classic pipeline configurations
distributed-config Descriptor types and what to do for each, for distributed pipeline configurations
python-api-best-practices Performance, API-key hygiene, and design guidance for sg.find / sg.create calls

Flow PTR app dev best practices

The reference files are not a rewrite of the Toolkit documentation. They operationalize how to develop an application for integration and automation in Flow PTR with good practices.

  • Action ladder. Toolkit gives you five escalating levels before you touch anything drastic: project settings, app settings, hooks, forking the app code, and finally building a new app from scratch. Phase 1 walks the agent through checking the first four before recommending the fifth.

  • Centralized vs. distributed configurations. Whether a project pipeline configuration lives on disk or is resolved through descriptors changes what “install this app” means. The skill teaches the agent to detect which configuration model it is dealing with before touching app_locations.yml.

  • Sandbox-first development. Cloning the primary pipeline configuration into a sandbox before touching anything is Phase 3 here, not an afterthought.

  • The app manifest and hooks. info.yml defines settings, supported engines, and the list of hooks an app exposes. The skill covers the two-step “copy the default, then repoint the YAML” pattern.

  • UI vs. headless first. The implementation phase keeps logic in a UI-agnostic module and lets the dialog call into it, so the tool can be exercised from tk-shell if possible before anyone opens a DCC.

  • Menu Action Items and web-triggered execution. For apps meant to run from the Flow PTR web UI, the skill flags the desktop-process execution model so the agent does not assume browser-side execution.

  • Python API hygiene. The skill covers details such as scoping sg.find field lists, handling script keys, and designing sg.create and sg.update calls that avoid unnecessary round trips following development best practices.

Installing the skill

The installation concept is similar across Claude, Claude Code, ChatGPT, Gemini CLI, and other agentic LLM systems, although the installation location and metadata format are not universally standardized. But they are very similar, if not the same.

Every skill, like in the repository, lives in a folder with a SKILL.md file. This is the file the LLM will read first and should contain the main entry information. It has at least the skill name and description. Its reference documents could be next to it or in subfolders. The installation is just a copy operation. Or you can install it automatically with the skills CLI utility:

# Install just this skill, scoped to the current project
npx skills add autodesk-platform-services/skills --project --skill flow-ptr-app

# Or install it globally if you build Flow PTR apps across multiple repositories
npx skills add autodesk-platform-services/skills --global --skill flow-ptr-app

Once it is in place, you do not need to invoke it explicitly. The description in SKILL.md carries the trigger phrases — such as “create a new Flow PTR app,” “new Toolkit app,” “tk-multi-starterapp,” “tank install_app,” and “dev sandbox pipeline configuration” — so an agent picks it up the moment the request looks like Toolkit app development.

Example prompts

  • Create a new Flow PTR app that captures a viewport snapshot and attaches it as a Note on the current Task, running from Maya and Nuke.
    The agent should open with “Phase 1 — Requirements/Intent capture,” ask the questions in that phase, and check whether tk-multi-screenshot-style functionality already exists before scaffolding anything new.

  • Build a reference checker for Maya that scans scene refs vs. latest published versions, flagging the stale ones.

  • Create a new Flow PTR app to submits selections to a render queue, resolving the output path from a template in my favorite 3d tool, ie, 3ds Max.

  • Please, let’s develop a Flow production tracking app that versions up a Nuke script and creates an event in Flow PTR on completion.

  • I want to launch an external review tool for a Version from the Flow PTR web UI.

  • Adds one custom naming-validation hook to the Flow workfiles app.

  • I want an app that allows me to create a project-level health summary (open tasks, pending publishes,…), like a Dashboard. I will launch it from Flow PTR Desktop.

  • Develop an app for Flow PTR that exports an editorial cut/EDL from Hiero and logs it as a Version.

  • Supervisor asks: “Can the Loader show Sequences, not just Shots and Assets, in the shot_step environment?”

Try it, and tell us

The skill is new, and Toolkit pipelines vary a lot from studio to studio. If a phase does not match how your team actually ships apps, or a reference is missing a case you hit in production, we are happy to get this kind of feedback. Drop us a note on the Flow PTR forum or contacting our ADN team.

Where to find more API articles

We are tagging our articles with adn-articles so they are easy to filter in the community forum. These posts cover API-related topics designed to help you apply Autodesk Platform Services and Flow Production Tracking APIs more effectively in real production workflows with common workflow implementations, troubleshooting guides and research insights.

We hope these resources become valuable to you. Stay tuned!

3 Likes