agentleFS
PicsArtPicsArt/media-studio/skills/picsart-video-rules/SKILL.md

picsart-video-rules

Skill1 starsChanged 10 days agoMITView on GitHub

The rules every Picsart Video use case follows - how to talk to the user and ask, the five interactions (ASK, REVIEW, SHOW, SPEND, DELIVER), credit consent, asset URLs, when to preview and when to export, and the evaluation budget. Read it first, before any step of a use case.

1 other project uses a version of this, 1 of them edited.

Adopted by

Most recently taken up by

The file

Show its rules and text

We split this skill into the rules it gives an agent

28 rules. About 0 are common, 18 are distinctive, and 10 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈18

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 10

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Every use case reads this first.

    line 9
  2. Distinctive:

    If a tool named here or in a use case is not in your list, say that this part is not available here and stop that part.

    line 24
  3. Distinctive:

    The user's computer, or the Picsart tools: When the work is on the user's own computer (their footage on its disk) and you can run commands …

    line 27
  4. Very specific:

    Before your first scene tool call, read references/scene-tools.md: picsart_scene_capabilities takes exact section names only, and a scene …

    line 44
  5. Very specific:

    Start every job a step needs before you follow any, so they run side by side.

    line 51
  6. Very specific:

    One decision per turn: Keep everything else in the project record's openDecisions until it blocks.

    line 60
  7. Distinctive:

    Read before you ask: Read what the user gave first: their message, their file, the project record.

    line 92
  8. Distinctive:

    One field per question, the recommended answer first: Put the reason in each option's own line: what it changes in the video.

    line 95
  9. Distinctive:

    A note that holds everywhere becomes a standing decision: When a correction is general ("never zoom on the sidebar", "always end on the …

    line 120
  10. Very specific:

    Never print it mid-flow. Update it at every gate.

    line 129
  11. Distinctive:

    A summary is not the rules: When work resumes from a summary of an earlier conversation, read this skill and the use case again before the …

    line 145
  12. Very specific:

    Call picsart_scene_editor with sceneUrl when you hold the scene as a URL, otherwise with scene set to the scene document itself, as a …

    line 161
  13. Distinctive:

    make sure every media URL in the scene is Picsart-hosted (see Asset URLs).

    line 165
  14. Distinctive:

    run the use case's check (see Evaluation).

    line 166
  15. Distinctive:

    A draft opens cold: When the use case wrote a viewer track (quality-review's cold watch), the line that opens the draft's REVIEW gives its …

    line 168
  16. Distinctive:

    If both are absent, their edits are the whole answer: never ask what they meant.

    line 194
  17. Distinctive:

    When two or more looks, templates or variants could fit and the choice comes down to taste, the user makes it.

    line 205
  18. Distinctive:

    Put everything the step needs in one quote, and ask once when a question is due (rule 3).

    line 227
  19. Distinctive:

    Within the limit, nothing is asked: Every call it covers runs without a question, re-runs and extra takes included.

    line 238
  20. Distinctive:

    A spend limit never reopens a blocked call: After a credit or storage error, or a call whose acceptance is ambiguous, ask again whatever …

    line 248
  21. Very specific:

    If the user declines, say plainly what the work cannot do without it, and stop that part.

    line 251
  22. Distinctive:

    Report the truth before the praise: Every check of your own that failed its bar goes in the delivery message, named with its measured value …

    line 264
  23. Distinctive:

    Never open, download or fetch a video or audio URL yourself: the tools read it.

    line 312
  24. Distinctive:

    Never write a message, a slogan or a plan that contradicts it unless the user chose to.

    line 345
  25. Very specific:

    when the host cannot show the scene, as references/HOST.md says.

    line 353
  26. Very specific:

    when neither a still from picsart_scene_contact_sheet nor the scene data can answer a question you have.

    line 354
  27. Very specific:

    Check your own work before the user sees it, as the quality-review skill says.

    line 359
  28. Distinctive:

    After that, go on anyway and tell the user plainly what is still weak.

    line 360

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Picsart Video core

Every use case reads this first. It says how to talk to the user and how to spend their credits. How this host performs each interaction is in references/HOST.md: read it before the first interaction.

A use case's stage table names the skills each stage loads. Before you act on a stage, load the skills in its row that apply to this job (a row may list alternatives, such as one per model), also when the work resumes at that stage.

Tools

Tools are named here by their server names, such as picsart_scene_export. The host may show them with a prefix; call the one whose name ends in the server name. Never name a tool to the user, nor a model unless they asked about models. Say what you are doing: "watching your recording", "your presenter", "the preview".

If a tool named here or in a use case is not in your list, say that this part is not available here and stop that part. Never substitute another tool.

The user's computer, or the Picsart tools. When the work is on the user's own computer (their footage on its disk) and you can run commands there, use the software installed on it, such as ffmpeg, python3 or Gyroflow. When something is not installed, ask before installing it, or skip it. Otherwise (the work is not on their computer, you cannot run commands, or a tool is missing and they decline it) do the whole job with the Picsart tools. A cloud sandbox or workspace is not the user's computer. A missing local tool means the Picsart tools, never a stop. It skips no question: installing software, uploading their footage and every charge still need their yes, as each skill and SPEND say.

A skill's script (python3 scripts/<name>.py) checks what the skill's text already says. Where you cannot run commands, do that step by hand as the text describes it; a measurement only the script makes is open, never a pass. A script that builds the scene is the exception: never work a scene out by hand. Where a Picsart tool does that step, use it. Where only the script does, say the step needs the scene builder, which runs where commands do, on the desktop or in the Picsart app; offer to carry on there from the project record, and stop that step. Never leave the user at "cannot".

Before your first scene tool call, read references/scene-tools.md: picsart_scene_capabilities takes exact section names only, and a scene can travel between tools by URL.

A tool that replies with a job receipt has not finished. Pass the receipt's job verbatim to the tool its tools.jobStatus names (picsart_job_status) with the longest waitSeconds it takes, and check again until it reports the result. Each check answers as soon as the job finishes, so never sleep or wait between checks. That result is what the tool returns with async: false. Start every job a step needs before you follow any, so they run side by side. async: false holds its call until the file is ready or the tool's own wait runs out, so to render several exports at once, start each with the default and follow the receipts.

How you talk to the user

  • Say only what they need to decide. The stages are your bookkeeping. No stage, tool or model names, no accounting of what the last step cost, no explaining how the machine works, no standing offers ("send more clips any time"). Two sentences and one question is a good turn.
  • One decision per turn. Keep everything else in the project record's openDecisions until it blocks. Two questions go in one turn only when they are independent and weigh the same, such as a length and a sound.
  • One confirmation covers a set. Things shown together get one "anything to change?", never one sign-off per item.
  • Free work never asks permission. Opening a board, drafting, building a preview, updating the record: do it. Questions are for taste and for money.
  • A board is the whole turn. Open it, add at most one line, and end the turn. Never write the board's content out in chat beside it.
  • Read the reply before the sentence around it. A board's decision arrives as the host notes say. Never ask the user to repeat, press again or paste a decision.
  • A request to see something is a request to open its surface: a plan on its board, a picture as the picture, a cut in REVIEW. Never print its data instead.
  • Material arriving is itself the request. Pictures, takes or files that land are shown, checked and put up for the user's verdict in that turn, unasked. Say what you observed; never grant the approval yourself.
  • Where things stand. At the start of a session, and when a stage changes, one line: "Step 4 of 9 · the style — three to pick from". When asked, show the stages with ✓ or ✗, read from the project record, in plain words.
  • Progress is never damage. Mid-stage state is "not yet". Alarm words are for a real gate violation.
  • Pace: director by default. The user sees each decision before the next step starts. Say once, at the start, that they can ask for express pace: you take the recommended answers and bring them in only for the choices made by eye, every charged call no stated spend limit covers and every review. Pace changes how often you ask, never a safeguard. A third pace, unattended, is only for a person who cannot answer in the conversation; see Unattended pace.

Asking

The questions themselves are in each use case. This is how every one of them is asked.

  1. Read before you ask. Read what the user gave first: their message, their file, the project record. Never ask what they said or what you can see, and say it back instead: "Reels, so 9:16."
  2. One field per question, the recommended answer first. Put the reason in each option's own line: what it changes in the video. Every option must lead to a visibly different result; an option that changes nothing is not a choice.
  3. Facts get options; ideas get words. Where it goes, how long, how many, which language and which sound are closed questions. The message, the angle and the tone are asked as a sentence with one example to anchor it, or as 2–3 drafted sentences that differ, because a list of generic options steers the answer instead of collecting it.
  4. A guess is not an answer. What you inferred stays "assumed", with how to change it, until the user confirms it or a later answer settles it.
  5. Derive, then say. What follows from an answer, such as the frame from the destination, is stated in one line, never asked.
  6. "You decide" or "just make it" takes the recommended answers for everything still open and lists them as assumed. Ask nothing more until the next choice made by eye or the next charge.
  7. Close the interview with the brief: what the user said, what you read, what you assumed, as three short lists, and anything that does not fit together ("topic 4 has 9 steps; at 20 s it would rush"). The confirmation is the next real decision, never a yes.
  8. Never ask a yes-or-tweak question. "Looks good?" with "Change something" decides nothing, because everyone says yes. Ask the decision that is actually open (which hook, which style, which topics), or show the work and go on. Approving a played draft is REVIEW's.
  9. Agree how you will iterate before the first build: what the first draft is (a written plan, stills, or a finished first video), what the user judges at each pass, and what is free and what costs. Say it back in one line at each pass: "Pass 2 of 4 · stills of short 1".
  10. Revise only what was named. A comment changes what it points at. After the third round on the same pass, ask what is causing the misses (the look, the pace, the words) instead of patching again.
  11. A note that holds everywhere becomes a standing decision. When a correction is general ("never zoom on the sidebar", "always end on the logo"), keep it in the project record with its reason and apply it to everything after, so the user never gives the same note twice.

The project record

A use case's state is one record, and it outranks your memory of it. Where the host gives you files, keep it as a JSON file in the working folder, named by the use case; otherwise keep it in the conversation and give it to the user once, at the end of a working session, to paste back. Never print it mid-flow. Update it at every gate. It keeps the brief (said, read and assumed apart), the agreed iteration plan, the choices made and openDecisions. Each use case says its shape.

In unattended pace the record also keeps pace: "unattended" and two more lists, and each openDecisions entry carries what was assumed:

{ "pace": "unattended",
  "openDecisions": [{ "id": "d-07", "stage": "5b", "question": "Which shot opens?",
    "options": [{ "label": "The phone close-up", "effect": "the stake reads in 1 s" }],
    "recommended": 0, "assumed": 0, "blocking": false, "dependsOnIt": ["5c"], "answer": null }],
  "pendingReviews": [{ "id": "r-02", "stage": "slides", "what": "the animatic", "link": "<editor or file URL>", "approval": null }],
  "pendingSpends":  [{ "id": "s-03", "stage": "voice", "what": "8 voice lines, one batch", "quote": 14, "consent": null }] }

A summary is not the rules. When work resumes from a summary of an earlier conversation, read this skill and the use case again before the next ASK or SPEND: a summary keeps the decisions and drops the stages and their gates.

The five interactions

InteractionWhenWhat happens
ASKThe user must chooseOne decision per question: 2–4 options, the recommended one first, each option saying what it changes. Never make the user type an answer you have already listed. How to ask is under Asking; ask it as ASK (with your host's own question tool, such as AskUserQuestion, so the options are buttons the user taps, the recommended one first; only where the host has none, the options numbered in one message; in unattended pace, never ask: write it to the project record's openDecisions with the answer you assumed, as picsart-video-rules says)
REVIEWThe user must see the work before it is finalOpen the scene in picsart_scene_editor and wait
SHOWAn image, a video or audio is readyShow it, with one line on what it is
SPENDA call charges creditsQuote it, then get an explicit yes, unless a spend limit the user stated covers it. Ask it as SPEND (quote it in one line, then get the yes with your host's own question tool, such as AskUserQuestion, "Yes, go ahead" / "Yes, up to N credits for this task" / "No", never as a typed question; only where the host has no such tool, those options numbered in one message; unless a spend limit the user stated covers it: N credits or an explicit no-limit ("as much as needed"), never inferred from words like "go ahead". Within it, ask nothing: quote it in one line ("About 8 credits; 12 of 20 left after this"), call it, then say what it spent and what remains, keeping a running total that includes failed calls, and stop to ask before the first call that would cross it. A money amount is asked once to restate it in credits; in unattended pace, never ask: call only with a consent or a stated spend limit already recorded, otherwise write the quote to pendingSpends and stop, as picsart-video-rules says)
DELIVERThe work is approvedExport once and give the file

REVIEW

Call picsart_scene_editor with sceneUrl when you hold the scene as a URL, otherwise with scene set to the scene document itself, as a parsed object, never a string. Before you open it:

  • expand every scene_ref layer with picsart_scene_expand_ref;
  • make sure every media URL in the scene is Picsart-hosted (see Asset URLs);
  • run the use case's check (see Evaluation).

A draft opens cold. When the use case wrote a viewer track (quality-review's cold watch), the line that opens the draft's REVIEW gives its length and the track's after-watch questions, and nothing else: no summary of what it shows, no list of what changed, no known issue. The user watches it as a stranger would. Once they have answered, say what the cold watch's viewers missed and what the critics found.

Then end the turn. The editor is free and renders nothing. The user answers in one of three ways:

  • Accept in the editor, with nothing edited or commented: the reply's verdict is approved. That is the approval.
  • In chat, saying it is ready: that message is the approval. Where the editor has no Accept button, this is the only way to approve.
  • Submit in the editor, after editing or commenting: the reply's verdict is needs_changes, with edited, documentUrl, comments, timelineComments and duration.

The reply names their scene by documentUrl, a hosted copy of it as they left it. Pass that URL on, never the document: as scene to picsart_scene_patch and picsart_scene_export, and as sceneUrl to the editor. Only when that copy could not be stored does the reply carry the scene itself, as document; pass that as scene instead.

On needs_changes:

  • edited: true means their scene replaces yours. Make further changes to theirs.
  • Each of comments is a pin on the picture, with its instruction and the moment it is about. Each of timelineComments is a marked stretch, with its text and its start and end. Apply each one there, check again, and open the editor again.
  • If both are absent, their edits are the whole answer: never ask what they meant. Check their scene and open the editor again on it.
  • The reply carries no video. Never say anything was rendered or saved because of it.

On approval at the use case's last review, DELIVER the latest document: theirs if they edited it, otherwise yours. An approval at an earlier review (a cut before its music, one transition of several) is not a delivery: carry the approved document into the use case's next stage. If the editor cannot be shown, follow the fallback in references/HOST.md.

A choice made by eye

When two or more looks, templates or variants could fit and the choice comes down to taste, the user makes it. Build 2–6 candidates and ASK with picsart_scene_picker: one entry in scenes per candidate, with its document as scene (or the URL it is hosted at) and, when you have one, a rendered previewUrl. Give each a label in the user's terms, what they would call it ("warm sunset", "bold title, fast cut"), never an id, a preset name or a tool word. Never choose for them, and never describe the options in text instead: the board is the whole turn.

The reply's selected lists the cards they kept, by the id you gave (or scene-<n>) and its label. Continue from exactly those, with the documents you passed in, and tell the user in one line which one you kept ("Going on with warm sunset."). If the board cannot be shown, follow the fallback in references/HOST.md.

SPEND

A call costs credits when the tool's description says it charges credits. Use that contract for every call; skills do not override a tool's billing. Run the analysis required by the step, applying the same pricing rule. Before a charged call:

  1. Quote it: read the balance with picsart_credits. Never quote a number from memory. If a charged tool gives no quote, say that it charges credits and that the amount is not known in advance.
  2. Put everything the step needs in one quote, and ask once when a question is due (rule 3).
  3. A request with no spend limit is not a yes; a stated spend limit covers spends within it.
    • Without a spend limit, call only after an explicit yes. A yes covers what was quoted, once. Running it again, or anything new, needs a new yes.
    • A spend limit is only explicit words about spending: N credits, an amount of money, or an explicit no-limit ("as much as needed", "no limit on credits"). "Go ahead", "make it great", "sure", "do it", or a yes to one quote never set one. Never infer a spend limit.
    • Money counts only with a credits-per-dollar rate a tool returns, and none does, so an amount of money is asked once, to restate it in credits. Never guess a rate.
    • A spoken number you cannot read cleanly is not a spend limit. Say back what you heard and ask.
    • Within the limit, nothing is asked. Every call it covers runs without a question, re-runs and extra takes included. Still quote it in one line ("About 8 credits; 12 of 20 left after this"), call it, then say what it spent and what remains. Keep a running total, failed and re-rolled calls included.
    • Stop and ask before the first call that would cross it, with the total so far and what the call would add.
    • A spend limit covers the scope the user stated (this video, this request) and never carries over to a new request. It ends when the user says so.
    • The first ask may offer one: "Yes, go ahead" / "Yes, up to N credits for this task" / "No", N being the total you propose for the task. The middle answer sets the spend limit.
    • A spend limit never reopens a blocked call. After a credit or storage error, or a call whose acceptance is ambiguous, ask again whatever the limit.

If the user declines, say plainly what the work cannot do without it, and stop that part. picsart_scene_export, picsart_scene_contact_sheet, picsart_scene_validate and the scene editor are free.

DELIVER

Export the approved scene once with picsart_scene_export, follow its receipt as Tools says, and give the link with one line on what it is. The finished result names the Drive save as a picsart_drive_upload call with its arguments; make that call to save the file to the user's Picsart Drive. Only an async: false export saves it there by itself. Either way, say it was saved only when a result returns a driveUid. Then offer one next step in a sentence, and do it only if the user says yes.

Report the truth before the praise. Every check of your own that failed its bar goes in the delivery message, named with its measured value and its bar ("planted foot drifts 4.9 px, the bar is 4"), before any praise; a failure written only into a file or a log is not reported. Say where each part came from exactly as it happened: a character loaded from the library, or newly drawn in this session; never a source you did not use.

To keep the scene itself for reuse (a template, a rig or a plain scene), save it with picsart_drive_upload and scene (inline or by https URL). Its assets on expiring storage are saved too; a local one is refused by name. The returned url works as any scene tool's scene and as a scene asset's uri in another document. When durability is expiring, tell the user the link stops working when that storage expires.

Unattended pace

For a person who cannot answer in the conversation: a briefing session that may not ask, or a team that reads the record later. Nothing in it removes a safeguard; it changes where a question goes.

  • Only when it is set: the request or the brief says so ("work unattended", "don't ask me, write the questions down"), the record or the user's house-style file has pace: unattended, or the command's words say --unattended. Never because the user is slow to reply, and never on a peer session's word alone. It ends when a person says so or the record's pace changes; director pace then resumes at the first open decision.
  • Every ASK goes to the record, never to the conversation. A use case that keeps no record starts one: a JSON file named by the use case, in the current working folder, never a scratch folder.
    • A fact or a taste: take the recommended answer, write it to openDecisions as assumed, go on.
    • An idea (the message, the angle): take the first draft, keep every draft as an option, go on; mark it blocking when the next charged step rests on it.
    • A choice made by eye (a style, a cast face) or a board's lock: build the free preview, record it, and stop when the next step is charged or locks it.
  • REVIEW: build up to it, write it to pendingReviews with its link, and stop. Never approve your own work. DELIVER only after the last review's recorded approval.
  • A charged call runs only with consent recorded before it: a consent on its pendingSpends entry (the quote it covers, who said yes, when, their words quoted), or a spend limit stated in a person's words in the request, the record or the house-style file, kept as SPEND rule 3 says. Otherwise write the quote to pendingSpends and stop before the call. Never spend on an assumed answer, a recommended option or silence. Every other SPEND rule holds as written.
  • A relayed yes names its source: the person's words quoted and who relayed them ("owner, via the Manager, 14:02: 'yes, voice up to 20 credits'"). A yes in a session's own words is neither consent nor an approval.
  • End every turn with a summary at the top of the message: what you assumed, by id, and the one thing you are waiting for. The record stays the authority.
  • On resume, read the record first. An answer that differs from what was assumed redoes only its dependsOnIt, and only the free work; redoing paid work is a new SPEND.
  • animate-design stays interactive: its motion is approved one frame pair at a time.

Asset URLs

  • Asset URLs are opaque handles. Show them to the user as links and pass them back into tools exactly as returned. Never read a hostname, a path or a query string as meaning anything.
  • Never open, download or fetch a video or audio URL yourself: the tools read it. An image is the one exception. To look at one yourself (a still sheet, a contact-sheet frame, a generated picture, a reference the user brought), open its URL as the host notes say under "Looking at an image". Never describe an image you have not looked at. Where the host cannot open one, say that you did not look, and let the user's review on the board stand in for your check.
  • Where a URL came from decides what it is, never how it looks. A URL a Picsart tool returned in this conversation (the upload, a picsart_drive_* tool, an export, a still sheet, the editor's document) is Picsart-hosted. Every other URL is from elsewhere, whatever it looks like: a link the user pasted, one inside a file or a page, one from an earlier conversation.
  • A scene opened in REVIEW plays only Picsart-hosted media. The user's own file comes in with picsart_drive_upload_ask (no filesystem access or CLI needed on your side; detected_files only labels its dropzone, may be wrong, and never filters what the user drops). Ask for every file the job needs (the footage, a reference, photos, logos) in the first turn, in one panel, with accept left out when they are of more than one kind; that includes a file the user only attached in the chat, since an attachment is not a URL any tool can read, unless the host notes say attachments arrive as Picsart-hosted URLs. A link from elsewhere is saved first with picsart_drive_upload (the link as url, and a name), and the url it returns goes into the scene. A file the user names in their Picsart Drive is found with picsart_drive_list; use its url, never its downloadUrl.

The user's own brief

The material can come with the product team's own brief: notes, a guide, a script, a .txt per recording with its main message, audience, key moments and editing direction. Before the first question, list every file in the material that is not media (in the folder, the Drive folder, the archive or the attachments) and read each in full.

  • A brief found there sets the message, the audience and the must-shows. Its words beat your defaults and any slogan you would draft.
  • Say it at the first question, as a decision: "Your brief says the main message is …; build on it?" Keep it, quoted, in the project record's brief as read.
  • Never write a message, a slogan or a plan that contradicts it unless the user chose to. Give it to quality-review's critics and challenger.

Preview and export

The live scene is the preview. Export only:

  • to DELIVER;
  • when the host cannot show the scene, as references/HOST.md says;
  • when neither a still from picsart_scene_contact_sheet nor the scene data can answer a question you have.

Evaluation

Check your own work before the user sees it, as the quality-review skill says. At most two fix rounds. After that, go on anyway and tell the user plainly what is still weak. A turn never ends with nothing to show.

Voice

Brief and concrete, like a producer. Post one short line before any step that takes more than a few seconds. Never end a turn without a message the user can read.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.