refactor: rename putior_skills() to putior_guide() and sync terminology

Resolve terminology clash with agent-almanac where "skills" means
machine-consumable procedures. putior's AI reference documentation is
a quick-reference guide, not an executable procedure.

- Rename R/putior_skills.R → R/putior_guide.R (function, helpers, docs)
- Rename inst/SKILLS.md → inst/GUIDE.md (add agent-almanac cross-refs,
  block comment syntax, Dockerfile/Makefile/WGSL in language table)
- Rename vignettes/skills.Rmd → vignettes/ai-integration.Rmd
- MCP tool: putior_skills → putior_guide
- ACP operation: skills → guide (keep "skills" as detection alias)
- putior_help("skills") still works as backward-compat alias
- Update _pkgdown.yml navbar, articles, reference index
- Update See Also tables in all 7 vignettes
- Update README, NEWS.md, CLAUDE.md
- Update all tests (4505 pass, 0 failures)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: pjt222

CLAUDE.md

@@ -172,7 +172,7 @@ Add to `%APPDATA%\Claude\claude_desktop_config.json`:
 | `list_supported_languages` | List supported languages |
 | `get_detection_patterns` | Get auto-detection patterns |
 | `get_diagram_themes` | List available themes |
-| `putior_skills` | AI assistant documentation |
+| `putior_guide` | AI assistant documentation |
 | `putior_help` | Quick reference help |
 | `set_putior_log_level` | Configure logging |
 
@@ -274,7 +274,7 @@ The ACP agent understands natural language requests:
 | generate | "generate annotation suggestions", "suggest annotations" |
 | merge | "merge annotations", "combine manual and auto" |
 | help | "help with syntax", "how to use putior" |
-| skills | "what are your capabilities", "what can you do" |
+| guide | "what are your capabilities", "what can you do" |
 
 ### Agent Manifest
 

NAMESPACE

@@ -18,10 +18,10 @@ export(put_merge)
 export(put_theme)
 export(putior_acp_manifest)
 export(putior_acp_server)
+export(putior_guide)
 export(putior_help)
 export(putior_mcp_server)
 export(putior_mcp_tools)
-export(putior_skills)
 export(run_sandbox)
 export(set_putior_log_level)
 export(split_file_list)

NEWS.md

@@ -2,6 +2,12 @@
 
 ## Breaking Changes
 
+* Renamed `putior_skills()` to `putior_guide()`. The function, its MCP tool
+  (`putior_guide`), and its ACP operation (`guide`) all use the new name.
+  `putior_help("skills")` still works as an alias for backward compatibility.
+  The inst file was renamed from `SKILLS.md` to `GUIDE.md`, and the vignette
+  from `skills.Rmd` to `ai-integration.Rmd`. (#41)
+
 * `put()`, `put_auto()`, `put_generate()`, and `put_merge()` now default to
   `recursive = TRUE` (previously `FALSE`). Directory scans now include
   subdirectories by default. Pass `recursive = FALSE` for the old behavior.
@@ -22,7 +28,7 @@
 * Added `putior_mcp_tools()` to get/filter tool definitions for custom MCP integrations
 * 16 tools available: `put`, `put_diagram`, `put_auto`, `put_generate`, `put_merge`,
   `get_comment_prefix`, `get_supported_extensions`, `list_supported_languages`,
-  `get_detection_patterns`, `get_diagram_themes`, `putior_skills`, `putior_help`,
+  `get_detection_patterns`, `get_diagram_themes`, `putior_guide`, `putior_help`,
   `set_putior_log_level`, `is_valid_put_annotation`, `split_file_list`, `ext_to_language`
 * Supports Claude Code, Claude Desktop, and other MCP-compatible clients
 
@@ -125,7 +131,7 @@
   API reference, showcase, troubleshooting, quick-reference, and skills reference
 * Professional cheat sheet (`inst/cheatsheet/putior-cheatsheet.qmd`)
 * 20 example files in `inst/examples/`
-* `putior_skills()` and `putior_help()` for in-session reference
+* `putior_guide()` and `putior_help()` for in-session reference
 
 ### New Helper Functions
 * `resolve_label()` internal helper to reduce code duplication in diagram generation
@@ -147,7 +153,7 @@
 * Consolidated language detection list into single authoritative registry
   (`.LANGUAGES_WITH_DETECTION` in `language_registry.R`)
 * Standardized `output` parameter across `put_diagram()`, `put_generate()`, and
-  `putior_skills()` -- all now support "raw"
+  `putior_guide()` -- all now support "raw"
 * Extracted duplicated label resolution into `resolve_label()` helper
 * Added input path sanitization to ACP server endpoints
 

R/acp.R

@@ -97,7 +97,7 @@ putior_acp_manifest <- function() {
         generate = "Generate annotation suggestions for files",
         merge = "Merge manual and auto-detected annotations",
         help = "Get help on putior usage",
-        skills = "Get AI assistant skills documentation"
+        guide = "Get AI assistant guide documentation"
       )
     )
   )
@@ -154,8 +154,8 @@ detect_operation <- function(content) {
   if (grepl("\\b(help|usage|how to)\\b", content_lower)) {
     return("help")
   }
-  if (grepl("\\b(skills|capabilities|what can)\\b", content_lower)) {
-    return("skills")
+  if (grepl("\\b(guide|skills|capabilities|what can)\\b", content_lower)) {
+    return("guide")
   }
 
 
@@ -361,8 +361,8 @@ execute_acp_request <- function(input, session_id = NULL) {
         )
         paste(help_output, collapse = "\n")
       },
-      "skills" = {
-        putior_skills(output = "raw")
+      "guide" = {
+        putior_guide(output = "raw")
       },
       # Default
       {
@@ -374,7 +374,7 @@ execute_acp_request <- function(input, session_id = NULL) {
           "- generate: Generate annotation suggestions\n",
           "- merge: Merge manual and auto annotations\n",
           "- help: Get help on putior usage\n",
-          "- skills: Get AI assistant documentation"
+          "- guide: Get AI assistant documentation"
         )
       }
     )
@@ -552,7 +552,7 @@ acp_get_run_handler <- function(run_id, response) {
 #'   \item \strong{generate}: "Generate annotation suggestions for ./R/"
 #'   \item \strong{merge}: "Merge manual and auto annotations in ./R/"
 #'   \item \strong{help}: "Help with annotation syntax"
-#'   \item \strong{skills}: "What are your capabilities?"
+#'   \item \strong{guide}: "What are your capabilities?"
 #' }
 #'
 #' @section Testing:

R/mcp.R

@@ -37,7 +37,7 @@ NULL
 #'   \item \code{list_supported_languages} - List supported languages
 #'   \item \code{get_detection_patterns} - Get auto-detection patterns
 #'   \item \code{get_diagram_themes} - List available themes
-#'   \item \code{putior_skills} - AI assistant documentation
+#'   \item \code{putior_guide} - AI assistant documentation
 #'   \item \code{putior_help} - Quick reference help
 #'   \item \code{set_putior_log_level} - Configure logging
 #'   \item \code{is_valid_put_annotation} - Validate annotation syntax
@@ -183,7 +183,7 @@ putior_mcp_tools <- function(include = NULL,
     make_tool_list_supported_languages(),
     make_tool_get_detection_patterns(),
     make_tool_get_diagram_themes(),
-    make_tool_putior_skills(),
+    make_tool_putior_guide(),
     make_tool_putior_help(),
     make_tool_set_putior_log_level(),
 
@@ -620,18 +620,18 @@ make_tool_get_diagram_themes <- function() {
 }
 
 #' @noRd
-make_tool_putior_skills <- function() {
+make_tool_putior_guide <- function() {
   ellmer::tool(
-    fun = putior_skills,
+    fun = putior_guide,
     description = paste0(
-      "Access putior skills documentation for AI assistants. ",
+      "Access putior guide documentation for AI assistants. ",
       "Provides structured information about annotation syntax, supported languages, ",
       "core functions, detection patterns, and usage examples. ",
       "Use output='raw' to get markdown content."
     ),
-    name = "putior_skills",
+    name = "putior_guide",
     annotations = list(
-      title = "AI Assistant Skills Reference",
+      title = "AI Assistant Guide Reference",
       readOnlyHint = TRUE
     ),
     arguments = list(
@@ -655,7 +655,7 @@ make_tool_putior_help <- function() {
     fun = putior_help,
     description = paste0(
       "Get quick-reference help for putior tasks and syntax. ",
-      "Topics include: annotation (syntax), themes, languages, node_types, patterns, examples, skills."
+      "Topics include: annotation (syntax), themes, languages, node_types, patterns, examples, guide."
     ),
     name = "putior_help",
     annotations = list(
@@ -665,7 +665,7 @@ make_tool_putior_help <- function() {
     arguments = list(
       topic = ellmer::type_enum(
         description = "Help topic to display",
-        values = c("annotation", "themes", "languages", "node_types", "patterns", "examples", "skills"),
+        values = c("annotation", "themes", "languages", "node_types", "patterns", "examples", "guide"),
         required = FALSE
       )
     )

R/putior_skills.R R/putior_guide.RR/putior_skills.R renamed to R/putior_guide.R

@@ -1,8 +1,12 @@
-#' Access putior Skills for AI Assistants
+#' Access putior Guide for AI Assistants
 #'
-#' Provides structured skills documentation for AI coding assistants
+#' Provides structured reference documentation for AI coding assistants
 #' (Claude Code, GitHub Copilot, etc.) to help users with putior.
 #'
+#' For step-by-step procedures, see the
+#' \href{https://github.com/pjt222/agent-almanac}{agent-almanac} repository,
+#' which provides 6 skills for the complete putior workflow.
+#'
 #' @param topic Character string specifying section. NULL for full content.
 #'   Options: "quick-start", "syntax", "languages", "functions",
 #'   "patterns", "examples", or NULL (all)
@@ -15,29 +19,29 @@
 #' @export
 #'
 #' @examples
-#' # Show all skills
-#' putior_skills()
+#' # Show full guide
+#' putior_guide()
 #'
 #' # Show specific topic
-#' putior_skills("quick-start")
+#' putior_guide("quick-start")
 #'
 #' # Get raw markdown for AI consumption
-#' skills_md <- putior_skills(output = "raw")
-putior_skills <- function(topic = NULL,
-                          output = c("console", "raw", "clipboard")) {
+#' guide_md <- putior_guide(output = "raw")
+putior_guide <- function(topic = NULL,
+                         output = c("console", "raw", "clipboard")) {
   output <- match.arg(output)
 
 
-  # Read skills file
-  skills_path <- system.file("SKILLS.md", package = "putior")
-  if (skills_path == "") {
-    stop("SKILLS.md not found in package installation", call. = FALSE)
+  # Read guide file
+  guide_path <- system.file("GUIDE.md", package = "putior")
+  if (guide_path == "") {
+    stop("GUIDE.md not found in package installation", call. = FALSE)
   }
-  content <- readLines(skills_path, warn = FALSE)
+  content <- readLines(guide_path, warn = FALSE)
 
   # Filter by topic if specified
   if (!is.null(topic)) {
-    content <- extract_skills_topic(content, topic)
+    content <- extract_guide_topic(content, topic)
   }
 
   # Handle output
@@ -47,17 +51,17 @@ putior_skills <- function(topic = NULL,
     clipboard = {
       copy_to_clipboard(
         content = paste(content, collapse = "\n"),
-        success_msg = "Skills copied to clipboard"
+        success_msg = "Guide copied to clipboard"
       )
     }
   )
 
   invisible(content)
 }
 
-#' Extract a topic section from skills content
+#' Extract a topic section from guide content
 #' @noRd
-extract_skills_topic <- function(content, topic) {
+extract_guide_topic <- function(content, topic) {
   topic <- tolower(trimws(topic))
 
   # Map topic names to section headers
@@ -98,20 +102,20 @@ extract_skills_topic <- function(content, topic) {
   content[start_idx:end_idx]
 }
 
-#' Show skills summary for putior_help integration
+#' Show guide summary for putior_help integration
 #' @noRd
-show_skills_summary <- function() {
+show_guide_summary <- function() {
   cat("\n")
-  cat("=== AI Assistant Skills Reference ===\n")
+  cat("=== AI Assistant Guide Reference ===\n")
   cat("\n")
 
-  cat("putior includes comprehensive skills documentation for AI coding assistants.\n")
+  cat("putior includes comprehensive reference documentation for AI coding assistants.\n")
   cat("\n")
   cat("ACCESS METHODS:\n")
-  cat("  putior_skills()                    # Show full skills reference\n")
-  cat("  putior_skills(\"quick-start\")       # Show quick start section\n")
-  cat("  putior_skills(output = \"raw\")      # Get raw markdown\n")
-  cat("  putior_skills(output = \"clipboard\") # Copy to clipboard\n")
+  cat("  putior_guide()                    # Show full guide reference\n")
+  cat("  putior_guide(\"quick-start\")       # Show quick start section\n")
+  cat("  putior_guide(output = \"raw\")      # Get raw markdown\n")
+  cat("  putior_guide(output = \"clipboard\") # Copy to clipboard\n")
   cat("\n")
   cat("AVAILABLE TOPICS:\n")
   cat("  quick-start  - Essential 3 commands\n")
@@ -122,6 +126,10 @@ show_skills_summary <- function() {
   cat("  examples     - Common usage patterns\n")
   cat("\n")
   cat("RAW FILE ACCESS:\n")
-  cat("  system.file(\"SKILLS.md\", package = \"putior\")\n")
+  cat("  system.file(\"GUIDE.md\", package = \"putior\")\n")
+  cat("\n")
+  cat("PROCEDURAL SKILLS:\n")
+  cat("  For step-by-step procedures, see the agent-almanac repository:\n")
+  cat("  https://github.com/pjt222/agent-almanac\n")
   cat("\n")
 }

R/putior_help.R

@@ -12,7 +12,7 @@
 #'     \item "node_types" - Show available node types
 #'     \item "patterns" - Show how to use detection patterns
 #'     \item "examples" - Show quick examples
-#'     \item "skills" - Show AI assistant skills reference
+#'     \item "guide" - Show AI assistant guide reference
 #'   }
 #'
 #' @return Invisibly returns NULL. Prints help content to the console.
@@ -42,8 +42,8 @@
 #' # Show quick examples
 #' putior_help("examples")
 #'
-#' # Show AI assistant skills reference
-#' putior_help("skills")
+#' # Show AI assistant guide reference
+#' putior_help("guide")
 putior_help <- function(topic = NULL) {
   if (is.null(topic)) {
     show_help_topics()
@@ -64,8 +64,9 @@ putior_help <- function(topic = NULL) {
       "detection" = show_patterns_help(),
       "examples" = ,
       "example" = show_examples_help(),
+      "guide" = ,
       "skills" = ,
-      "skill" = show_skills_summary(),
+      "skill" = show_guide_summary(),
       {
         cat("Unknown topic: '", topic, "'\n\n", sep = "")
         show_help_topics()
@@ -90,7 +91,7 @@ show_help_topics <- function() {
   cat("  putior_help(\"node_types\")   - Available node types for styling\n")
   cat("  putior_help(\"patterns\")     - Auto-detection patterns\n")
   cat("  putior_help(\"examples\")     - Quick usage examples\n")
-  cat("  putior_help(\"skills\")       - AI assistant skills reference\n")
+  cat("  putior_help(\"guide\")        - AI assistant guide reference\n")
   cat("\n")
   cat("For full documentation, see: ?put, ?put_diagram, ?put_auto\n")
   cat("\n")

README.md

@@ -140,7 +140,7 @@ Explore the full documentation at the [pkgdown site](https://pjt222.github.io/pu
 | [API Reference](https://pjt222.github.io/putior/articles/api-reference.html) | Complete function documentation |
 | [Quick Reference](https://pjt222.github.io/putior/articles/quick-reference.html) | At-a-glance reference card |
 | [Troubleshooting](https://pjt222.github.io/putior/articles/troubleshooting.html) | Common issues and solutions |
-| [AI Skills](https://pjt222.github.io/putior/articles/skills.html) | MCP/ACP integration for AI assistants |
+| [AI Integration](https://pjt222.github.io/putior/articles/ai-integration.html) | MCP/ACP integration for AI assistants |
 
 ## How putior Compares
 

_pkgdown.yml

@@ -163,7 +163,7 @@ home:
 
 navbar:
   structure:
-    left: [intro, reference, articles, skills, cheatsheet, news]
+    left: [intro, reference, articles, ai-integration, cheatsheet, news]
     right: [search, github]
   components:
     home:
@@ -192,10 +192,10 @@ navbar:
         href: articles/quick-reference.html
       - text: Troubleshooting Guide
         href: articles/troubleshooting.html
-    skills:
-      text: AI Skills
+    ai-integration:
+      text: AI Integration
       icon: fa-robot
-      href: articles/skills.html
+      href: articles/ai-integration.html
     cheatsheet:
       text: Quick Ref
       icon: fa-file-alt
@@ -224,7 +224,7 @@ articles:
 - title: "AI Integration"
   navbar: ~
   contents:
-  - skills
+  - ai-integration
 
 reference:
 - title: "Core Functions"
@@ -260,7 +260,7 @@ reference:
   - putior_mcp_tools
   - putior_acp_server
   - putior_acp_manifest
-  - putior_skills
+  - putior_guide
   - putior_help
 
 - title: "Interactive Tools"