pjt222/agent-almanac/annotate-source-files

Trust tier 2
  • community
Source check pending

Checking that the SKILL.md file is still in the repository.

Add PUT workflow annotations to source files using the correct language-specific comment prefix. Covers annotation syntax, skeleton generation via put_generate(), multiline annotations, .internal variables, and validation. Supports 30+ languages with automatic comment prefix detection. Use after analyzing a codebase and having an annotation plan, when adding workflow documentation to new or existing source files, or when documenting data pipelines, ETL processes, or multi-step computations.

Install

npx vskill@latest install pjt222/agent-almanac/annotate-source-files

SKILL.md

注源檔

添 PUT 工作流注於源檔，使 putior 可取結構化工作流數而生 Mermaid 圖。

用時

  • 以 analyze-codebase-workflow 析畢且有注計後乃用
  • 添工作流文於新或既源檔乃用
  • 以手標與連豐自察工作流乃用
  • 書數管、ETL、多步計算乃用

入

  • 必要：待注之源檔
  • 必要：注計或工作流諸步之知
  • 可選：風格：單行或多行（默：單行）
  • 可選：用 put_generate() 生骨乎（默：是）

法

第一步：定注之前綴

各語有特注前綴。以 get_comment_prefix() 得之。

r
library(putior)
 
# Common prefixes
get_comment_prefix("R")    # "#"
get_comment_prefix("py")   # "#"
get_comment_prefix("sql")  # "--"
get_comment_prefix("js")   # "//"
get_comment_prefix("ts")   # "//"
get_comment_prefix("go")   # "//"
get_comment_prefix("rs")   # "//"
get_comment_prefix("m")    # "%"
get_comment_prefix("lua")  # "--"

得： 一串如 "#"、"--"、"//"、或 "%"。

行注與塊注：putior 察行注（//、#、--）及 C 式塊注（/* */、/** */）中之注。JS/TS 行注與塊注皆掃。Python 三引號串（''' '''）不察——Python 注用 #。

敗則： 若擴未識，檔語或不支。以 get_supported_extensions() 察全列。不支之語用 # 為約默。

第二步：生注骨

用 put_generate() 以自察 I/O 建注樣。

r
# Print suggestions to console
put_generate("./src/etl/")
 
# Single-line style (default)
put_generate("./src/etl/", style = "single")
 
# Multiline style for complex annotations
put_generate("./src/etl/", style = "multiline")
 
# Copy to clipboard for pasting
put_generate("./src/etl/", output = "clipboard")

R 檔之例：

r
# put id:'extract_data', label:'Extract Customer Data', input:'customers.csv', output:'raw_data.internal'

SQL 之例：

sql
-- put id:'load_data', label:'Load Customer Table', output:'customers'

得： 每源檔一或多注行，預填察函名與 I/O。

敗則： 若無薦生，檔或無可識 I/O 式。依碼解手書注。

第三步：精注

編骨以添正標、連、元。

注語法參：

text
<prefix> put id:'unique_id', label:'Human Readable Label', input:'file1.csv, file2.rds', output:'result.parquet, summary.internal'

欄：

  • id（必）：獨識，連節用
  • label（必）：圖顯之人讀述
  • input：入檔或量逗列
  • output：出檔或量逗列
  • .internal 擴：標記憶量（腳本間未存）
  • node_type：控 Mermaid 節形與類：
  • "input" — 體育場形 ([...]) 為數源與設
  • "output" — 子程形 [[...]] 為生物
  • "process" — 矩 [...] 為處理步（默）
  • "decision" — 菱 {...} 為條件邏輯
  • "start" / "end" — 體育場形 ([...]) 為入/終節

附 node_type 之例：

r
# put id:'config', label:'Load Config', node_type:'input', output:'config.internal'
# put id:'transform', label:'Apply Rules', node_type:'process', input:'config.internal', output:'result.rds'
# put id:'report', label:'Generate Report', node_type:'output', input:'result.rds'

多行語法（為繁注）：

r
# put id:'complex_step', \
#   label:'Multi-line Label', \
#   input:'data.csv, config.yaml', \
#   output:'result.parquet'

塊注語法（唯 // 前綴之語：JS、TS、Go、Rust、C、C++、Java 等）：

用 // 行注之語亦支 /* */ 與 /** */ 塊注中之 PUT 注。塊內用 * put 為行前：

javascript
/* put id:'init', label:'Initialize Config', output:'config.internal' */
/**
 * put id:'process', \
 *   label:'Process Records', \
 *   input:'config.internal, records.json', \
 *   output:'results.json'
 */
function processRecords(config, records) {
  // ...
}

JSDoc 式注尤宜於書工作流步附 API 文：

typescript
/**
 * Transform raw sensor data into normalized readings.
 * put id:'normalize', label:'Normalize Sensor Data', input:'raw_readings.json', output:'normalized.parquet'
 */
export function normalizeSensorData(readings: SensorReading[]): NormalizedData {
  // ...
}
注：塊注注不支 # 前綴之語（R、Python、Shell）或 -- 前綴之語（SQL、Lua）。彼語唯用行注。塊起注不支跨行反斜續。

跨檔數流（以檔 I/O 連本）：

r
# Script 1: extract.R
# put id:'extract', label:'Extract Data', output:'raw_data.internal, raw_data.rds'
data <- read.csv("source.csv")
saveRDS(data, "raw_data.rds")
 
# Script 2: transform.R
# put id:'transform', label:'Transform Data', input:'raw_data.rds', output:'clean_data.parquet'
data <- readRDS("raw_data.rds")
arrow::write_parquet(clean, "clean_data.parquet")

得： 注精附正 ID、標、I/O 欄映實數流。

敗則： 若 I/O 不定，用 .internal 擴於記憶中間，用明檔名於持數。

第四步：插注於檔

置注於檔首或相關塊之上。

位之例：

  1. 檔級注：置檔首（shebang 或檔頭注後）
  2. 塊級注：置所述塊之上
  3. 每檔多注：於有別工作流段之檔用

R 檔位例：

r
#!/usr/bin/env Rscript
# ETL Extract Script
#
# put id:'read_source', label:'Read Source Data', input:'raw_data.csv', output:'df.internal'
 
df <- read.csv("raw_data.csv")
 
# put id:'clean_data', label:'Clean and Validate', input:'df.internal', output:'clean.rds'
 
df_clean <- df[complete.cases(df), ]
saveRDS(df_clean, "clean.rds")

用 Edit 工具插注於既檔而不擾周圍碼。

得： 注插於每源檔之宜位。

敗則： 若注亂編之語法高亮，確注前綴合語。PUT 注為標注，當不影碼執行。

第五步：驗注

行 putior 驗以察注語法與連。

r
# Scan annotated files
workflow <- put("./src/", validate = TRUE)
 
# Check for validation issues
print(workflow)
cat(sprintf("Total nodes: %d\n", nrow(workflow)))
 
# Verify connections by checking input/output overlap
inputs <- unlist(strsplit(workflow$input, ",\\s*"))
outputs <- unlist(strsplit(workflow$output, ",\\s*"))
connected <- intersect(inputs, outputs)
cat(sprintf("Connected data flows: %d\n", length(connected)))
 
# Generate diagram to visually inspect
cat(put_diagram(workflow, theme = "github", show_source_info = TRUE))
 
# Merge with auto-detected for maximum coverage
merged <- put_merge("./src/", merge_strategy = "supplement")
cat(put_diagram(merged, theme = "github"))

得： 諸注皆析無訛。圖示連之工作流。put_merge() 補自察之隙。

敗則： 常驗患：

  • 閉引闕：id:'name → id:'name'
  • 內用雙引：id:"name" → id:'name'
  • 跨檔重 ID：每 id 於掃目內必獨
  • 反斜續於誤行：\ 必為換行前末字

驗

  • [ ] 每注檔有語法有效 PUT 注
  • [ ] put("./src/") 返期節數之數框
  • [ ] 掃目無重 id
  • [ ] put_diagram() 生連之流圖（非諸離節）
  • [ ] 多行注（若用）正析附反斜續
  • [ ] .internal 量只為出，勿為跨檔入
  • [ ] 經 exclude 排之檔不現於工作流（如 put("./src/", exclude = "test_") 跳試助）

陷

  • 引套誤：PUT 注用單引：id:'name'。雙引於串境致析患
  • 重 ID：每 id 於掃範內必全獨。用如 <script>_<step> 之命約（如 extract_read、transform_clean）
  • `.internal` 為跨檔入：.internal 量只於本執行時存。本間傳數用持檔式（.rds、.csv、.parquet）為一本之出、他本之入
  • 連闕：若圖示離節，察一注之出檔名與他注之入檔名全合（含擴）
  • 誤注前綴：SQL 檔用 # 或 Python 用 // 致注被視為碼。恆以 get_comment_prefix() 驗
  • 忘多行續：多行注每續行必以 \ 終，下行必以注前綴始
  • Python 三引號串：putior 不掃 Python 三引號串（''' '''、""" """）。Python PUT 注恆用 #
  • 元管道注：若注亦掃注之建本（如呼 put() 與 put_diagram() 之本），本自之注現於所生圖。或從掃排此檔（見 generate-workflow-diagram 常陷），或勿於建本置 PUT 注

參

  • analyze-codebase-workflow — 前置：生此技所循之注計
  • generate-workflow-diagram — 下步：自注生終圖
  • install-putior — 注前 putior 必裝
  • configure-putior-mcp — MCP 工具供互注助

Security

  • Security scanPassed, 100 of 100Pattern checks on the skill's files.
  • Model reviewPassed

See the full security report

Quality evaluation

  • Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

See evaluation results

Source

Popularity

Repository stars
12
Repository forks
1
Repository npm downloads, 7 days
28
7-day trend score
23

Stars and forks are for the whole GitHub repository, not this skill alone. Downloads are for the repository's npm package. Refreshed 26 Apr 2026, 6 months ago.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

  • Claude Code
  • Cursor
  • GitHub Copilot
  • Windsurf
  • Codex
  • Gemini CLI
  • Cline
  • Amp
  • Roo Code
  • Goose
  • Continue
  • Kilo Code
  • Junie
  • Trae
  • OpenHands
  • Qwen Code
  • AI Agent
  • Tabnine Chat
  • Sourcegraph Cody
  • Amazon Q
  • Firebase Genkit
  • Sweep
  • Devin
  • Phind
  • Mentat
  • Claude Desktop
  • Aider
  • GPT Pilot
  • Plandex
  • bolt.new
  • v0
  • Replit Agent
  • Anse
  • TypingMind
  • BetterChatGPT
  • LibreChat
  • Warp AI
  • Pieces
  • Fig AI
Embed badge
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/pjt222/agent-almanac/annotate-source-files/badge)](https://verified-skill.com/skills/pjt222/agent-almanac/annotate-source-files)

Something wrong with this skill or its page? Tell us.