AI Skills Reference

About This Vignette

This vignette documents putior’s capabilities for AI assistants (like Claude, ChatGPT, or GitHub Copilot). It’s designed to be read by language models to understand how to use putior effectively.

For Humans

If you’re a human reader, you probably want one of these instead:

Guide	Description
Quick Start	Create your first diagram in 2 minutes
Annotation Guide	Complete syntax reference
Quick Reference	Printable cheat sheet
API Reference	Full function documentation
Troubleshooting	Common issues and solutions

For AI Assistants

This content is automatically available via:

putior_skills() - Returns this documentation as a string
MCP server - Exposed as a tool via putior_mcp_server()
ACP server - Available via /runs endpoint from putior_acp_server()

Programmatic Access

# Get skills documentation as a string
skills_text <- putior_skills()

# Use in prompt engineering
prompt <- paste("You have access to putior:", skills_text)

# Or access via MCP tools
tools <- putior_mcp_tools()

MCP/ACP Integration

When running as an MCP or ACP server, AI assistants can:

Discover capabilities via putior_skills tool
Extract annotations via put tool
Generate diagrams via put_diagram tool
Auto-detect workflows via put_auto tool

See the MCP Server section in CLAUDE.md for setup instructions.

Skills Documentation

The content below is the same as returned by putior_skills():

putior Skills

Skills for AI coding assistants to help users document and visualize code workflows.

Direct Access (Non-R Environments)

Access these skills without running R:

Method	URL
Web Page	https://pjt222.github.io/putior/articles/skills.html
Raw Markdown	https://raw.githubusercontent.com/pjt222/putior/main/inst/SKILLS.md
GitHub View	https://github.com/pjt222/putior/blob/main/inst/SKILLS.md

For R users: putior_skills(output = "raw") returns this content as a string.

Quick Start

# 1. Extract annotations from source files
workflow <- put("./R/")

# 2. Generate Mermaid diagram
put_diagram(workflow)

# 3. Auto-detect workflow without annotations
workflow <- put_auto("./src/")

Annotation Syntax

Add # put comments to source files to define workflow nodes:

# put id:"load", label:"Load Data", output:"raw_data.csv"
data <- read.csv("input.csv")

# put id:"transform", label:"Clean Data", input:"raw_data.csv", output:"clean.rds"
clean <- transform(data)

# put id:"analyze", label:"Run Analysis", input:"clean.rds", node_type:"decision"
results <- analyze(clean)

Annotation Properties

Property	Required	Description	Example
`id`	Yes	Unique node identifier	`id:"load_data"`
`label`	No	Display text (defaults to id)	`label:"Load CSV"`
`input`	No	Input files/data (comma-separated)	`input:"a.csv, b.csv"`
`output`	No	Output files/data	`output:"result.rds"`
`node_type`	No	Shape: input, process (default), output, decision, start, end	`node_type:"decision"`

Multiline Annotations

Use backslash for continuation:

# put id:"complex_step", \
#     label:"Multi-step Process", \
#     input:"file1.csv, file2.csv", \
#     output:"combined.rds"

Multi-Language Comment Syntax

putior automatically detects comment style by file extension:

Prefix	Languages	Extensions
`# put`	R, Python, Shell, Julia, Ruby, Perl, YAML	`.R`, `.py`, `.sh`, `.jl`, `.rb`, `.pl`, `.yaml`
`-- put`	SQL, Lua, Haskell	`.sql`, `.lua`, `.hs`
`// put`	JavaScript, TypeScript, C, C++, Java, Go, Rust, Swift, Kotlin, C#, PHP	`.js`, `.ts`, `.c`, `.cpp`, `.java`, `.go`, `.rs`
`% put`	MATLAB, LaTeX	`.m`, `.tex`

Examples by Language

-- query.sql
-- put id:"fetch", label:"Fetch Customers", output:"customers"
SELECT * FROM customers;

// transform.js
// put id:"process", label:"Transform JSON", input:"data.json", output:"output.json"
const result = data.map(transform);

% analysis.m
% put id:"stats", label:"Statistical Analysis", input:"data.mat", output:"results.mat"
results = compute_statistics(data);

Core Functions

`put()` - Extract Annotations

# Scan directory for annotations
workflow <- put("./R/")

# Scan specific file
workflow <- put("./scripts/pipeline.R")

# Custom file pattern
workflow <- put("./src/", pattern = "\\.py$")

# Enable debug logging
workflow <- put("./R/", log_level = "DEBUG")

# Exclude test files
workflow <- put("./R/", exclude = "test")

`put_diagram()` - Generate Diagrams

# Basic diagram
put_diagram(workflow)

# Customize appearance
put_diagram(workflow,
  direction = "LR",           # Left-to-right (default: TB top-bottom)
  theme = "github",           # Theme: github, light, dark, auto, minimal
  show_artifacts = TRUE       # Show data files as nodes
)

# Colorblind-safe themes (viridis family)
put_diagram(workflow, theme = "viridis")  # Purple-blue-green-yellow
put_diagram(workflow, theme = "magma")    # Warm: purple-red-yellow
put_diagram(workflow, theme = "plasma")   # Vibrant: purple-pink-yellow
put_diagram(workflow, theme = "cividis")  # Blue-yellow (max accessibility)

# Interactive features
put_diagram(workflow,
  enable_clicks = TRUE,       # Make nodes clickable
  click_protocol = "vscode",  # vscode, rstudio, or file
  show_source_info = TRUE     # Show source file in nodes
)

# Output options
put_diagram(workflow, output = "clipboard")        # Copy to clipboard
put_diagram(workflow, output = "workflow.md")      # Save to file
mermaid_code <- put_diagram(workflow, output = "raw")  # Return as string

`put_auto()` - Auto-Detect Workflow

Analyze code to detect inputs/outputs without annotations:

# Auto-detect from R files
workflow <- put_auto("./R/")

# Control what to detect
workflow <- put_auto("./src/",
  detect_inputs = TRUE,
  detect_outputs = TRUE,
  detect_dependencies = TRUE
)

# Combine with manual annotations
workflow <- put_merge("./src/", merge_strategy = "supplement")

# Exclude vendor/test directories
workflow <- put_auto("./src/", exclude = c("vendor", "test"))

`put_generate()` - Generate Annotation Templates

# Print suggested annotations
put_generate("./R/")

# Copy to clipboard
put_generate("./R/", output = "clipboard")

# Multiline style
put_generate("./R/", style = "multiline")

Auto-Detection Patterns

Languages with pattern-based detection (902 patterns total):

Language	Patterns	Key Libraries
R	124	readr, data.table, DBI, arrow, ellmer
Python	159	pandas, numpy, sqlalchemy, transformers, langchain
JavaScript	71	Node.js fs, Express, mongoose, Prisma
TypeScript	88	All JS + NestJS, TypeORM
Java	73	NIO, JDBC, Jackson, Spring Boot
Ruby	64	File, CSV, Rails, ActiveRecord
Rust	60	std::fs, serde, sqlx, diesel
Go	44	os, bufio, database/sql, gorm
C++	44	fstream, boost, std::filesystem
MATLAB	44	readtable, imread, h5read
Julia	27	CSV.jl, DataFrames, JLD2
C	24	stdio.h, POSIX, mmap
Lua	20	io library, loadfile
WGSL	17	GPU bindings, textures, samplers, naga-oil
Dockerfile	13	FROM, COPY, ADD, EXPOSE, VOLUME, CMD, RUN
Shell	12	cat, redirects, source
Makefile	10	include, wildcard, target rules, install
SQL	8	FROM, JOIN, COPY

LLM Library Detection

Detects modern AI/ML libraries:

R: ellmer (chat(), chat_openai(), chat_claude()), tidyllm, httr2 API calls

Python: ollama, openai, anthropic, langchain, transformers, litellm, vllm, groq

Helper Functions

# Get comment prefix for extension
get_comment_prefix("sql")   # Returns "--"
get_comment_prefix("js")    # Returns "//"

# List supported extensions
get_supported_extensions()

# List supported languages
list_supported_languages()                    # All 30+ languages
list_supported_languages(detection_only = TRUE)  # 18 with auto-detection

# Get detection patterns
patterns <- get_detection_patterns("python")
patterns <- get_detection_patterns("r", type = "input")

# Available themes
get_diagram_themes()

# Interactive help
putior_help()

Common Patterns

Document Existing Codebase

# 1. Auto-generate annotation suggestions
put_generate("./R/", output = "clipboard")

# 2. Paste into source files and customize
# 3. Extract and visualize
workflow <- put("./R/")
put_diagram(workflow)

Quick Visualization Without Annotations

# Instant workflow diagram from code analysis
workflow <- put_auto("./src/")
put_diagram(workflow, show_artifacts = TRUE)

Hybrid Approach

# Manual annotations for key files, auto-detect the rest
workflow <- put_merge("./src/", merge_strategy = "supplement")
put_diagram(workflow)

Export for Documentation

# Save Mermaid diagram to markdown file
put_diagram(workflow, output = "docs/workflow.md")

# Get raw Mermaid code for embedding
mermaid_code <- put_diagram(workflow, output = "raw")

Node Types

Type	Mermaid Shape	Use For
`input`	Stadium `([...])`	Data sources, file loading, API inputs
`process`	Rectangle `[...]` (default)	Data processing, transformations
`output`	Subroutine `[[...]]`	Report generation, exports, final outputs
`decision`	Diamond `{...}`	Conditional logic, branching workflows
`start`	Stadium `([...])`	Workflow entry point (special boundary styling)
`end`	Stadium `([...])`	Workflow exit point (special boundary styling)
`artifact`	Cylinder `[(...)]`	Data files (auto-created with `show_artifacts = TRUE`)

Note: artifact nodes are automatically created by put_diagram() when show_artifacts = TRUE. They are not set manually via node_type.

Diagram Themes

Theme	Use Case
`light`	Bright colors (default)
`dark`	Dark mode environments
`auto`	GitHub-adaptive with solid colors
`minimal`	Print-friendly, grayscale
`github`	Optimized for README files
`viridis`	Colorblind-safe (purple-blue-green-yellow)
`magma`	Colorblind-safe (purple-red-yellow)
`plasma`	Colorblind-safe (purple-pink-yellow)
`cividis`	Maximum accessibility (blue-yellow)

Interactive Sandbox

Launch browser-based annotation playground:

run_sandbox()  # Requires shiny package

Quarto/RMarkdown Integration

# In R chunk
workflow <- put("./R/")
mermaid_code <- put_diagram(workflow, output = "raw")

Then use knitr::knit_child() to embed as native Mermaid chunk.

Logging

Enable debug output for troubleshooting:

# Set globally
options(putior.log_level = "DEBUG")
set_putior_log_level("DEBUG")

# Per-call override
workflow <- put("./R/", log_level = "DEBUG")

Levels: DEBUG, INFO, WARN (default), ERROR

Tips for AI Assistants

Start with put_auto() for unfamiliar codebases to quickly understand data flow
Use put_generate() to create annotation templates users can customize
Prefer put_merge() when combining manual and auto-detected workflows
Check comment syntax - use correct prefix for target language
Enable show_artifacts = TRUE to visualize data file dependencies
Use enable_clicks = TRUE for navigable documentation