Annotate Source Files

What it does

Add PUT workflow annotations to source code files so tools like putior can extract structured workflow steps and render Mermaid diagrams. This skill provides guidance on selecting the correct language-specific comment prefix, generating skeleton annotations with put_generate(), writing single-line or multiline PUT entries, and validating connections across files. It targets data pipelines, ETL processes, and multi-step computations where documenting inputs, outputs, and step IDs yields a machine-readable workflow.

When to use it

Use this skill after you have analyzed a codebase and created an annotation plan. Apply it when adding workflow documentation to new or existing source files, when documenting ETL or data-processing steps, or when you want to generate visual diagrams that reflect real code-level I/O. It is helpful for teams sharing reproducible pipelines or preparing code for automated orchestration.

What's included

• Scripts: none bundled (has_scripts=false) — guidance and examples are embedded in the SKILL.md body.
• References: none bundled (has_references=false) — the skill includes procedural examples and validation checks.
• Instructions: how to detect the correct comment prefix, use put_generate() to scaffold annotations, format single-line and multiline PUT annotations, choose node types, validate IDs and I/O connections, and generate diagrams with put_diagram(). Notes on common pitfalls (quoting issues, duplicate IDs, .internal semantics) are included.

Compatible agents

This skill is language/tool-agnostic and best used by agents that can read/write repository files and run R or putior tooling (agents with bash/read/write/edit capabilities). It is most relevant for agents integrated with developer workflows (e.g., Claude Code, Copilot-style automations, or custom CI bots).