blob: c2799e4874ee741d013dfde2bb005911a6da0afb [file]
# Copyright 2026 The Fuchsia Authors. All rights reserved.
# Use of this source code is governed by a BSD-style license that can be
# found in the LICENSE file.
"""Skill and workflow linter for SKILL.md, saved workflows, and .agents JSON configs."""
import argparse
import ast
import collections.abc
import json
import logging
import os
import re
import sys
import textwrap
import types
from collections.abc import Collection, Mapping, Sequence, Set
from typing import Any, TypedDict
import yaml
# Constants for skill validation and formatting.
MAX_NAME_LENGTH = 64
MAX_DESCRIPTION_LENGTH = 1024
LINE_LENGTH = 80
_WARN_SKILL_LINES = 500
_MAX_SKILL_LINES = 800
_WARN_SKILL_BYTES = 35000
_MAX_SKILL_BYTES = 46080
_LINK_REFERENCE_RE = re.compile(r"^\s{0,3}\[[^\]]+\]:\s*")
_LIST_ITEM_RE = re.compile(r"^\s*([-*+]|\d+\.)\s+")
_ALLOWED_SKILL_FRONTMATTER_KEYS = frozenset(
{
"name",
"description",
"tools",
"license",
"allowed-tools",
"metadata",
"compatibility",
"support_tier",
"version",
"tags",
"category",
"disable-model-invocation",
"disable-slash-command",
}
)
_ALLOWED_WORKFLOW_MANIFEST_KEYS = frozenset(
{"name", "description", "entry", "args", "library"}
)
_ALLOWED_DISCOVERY_CONFIG_KEYS = frozenset(
{"entries", "inherits", "exclude", "comment"}
)
_ALLOWED_CALL_TOOLS = frozenset(
{
"edit_file",
"invoke_subagent",
"manage_task",
"read_file",
"search_web",
"send_message",
"swarm",
"write_file",
}
)
_ALLOWED_WORKFLOW_WORKSPACES = frozenset({"inherit", "branch", "share"})
_ALLOWED_WORKFLOW_MODELS = frozenset({"inherit", "flash_lite", "flash", "pro"})
_DISCOVERY_JSON_FILENAMES = frozenset(
{
"agents.json",
"plugins.json",
"rules.json",
"skills.json",
"workflows.json",
}
)
# Grandfathered skills pre-dating the 800-line / 45 KiB ceiling and .agents/ plural rule.
_LEGACY_OVERSIZED_SKILLS = frozenset(
{
"src/devices/skills/autoda-fix/SKILL.md",
"src/devices/skills/driver-lab/SKILL.md",
"zircon/skills/cpp-to-rust-rubric/SKILL.md",
"zircon/skills/kernel-review/SKILL.md",
}
)
_LEGACY_SINGULAR_DOT_AGENT_PREFIXES = (
"build/beads/.agent/",
"src/storage/.agent/",
)
_POSITIVE_TRIGGER_RE = re.compile(
r"\b(use when|use this|use for|trigger|invoke when|whenever)\b",
re.IGNORECASE,
)
_NEGATIVE_TRIGGER_RE = re.compile(
r"\b(don't use|do not use|not for|avoid using|never use)\b",
re.IGNORECASE,
)
_BINARY_IN_DESC_RE = re.compile(
r"(/google/bin/releases/|/google/data/ro/|\bblaze run //)"
)
_FILLER_NAME_RE = re.compile(
r"(?:^|-)(skill|guide|playbook|how-to|checklist|helper|utils)(?:$|-)"
)
_LOCAL_MACHINE_PATH_RE = re.compile(
r"(/usr/local/google/home/|/google/src/cloud/|/Users/[A-Za-z0-9._-]+/)"
)
_CALL_TOOL_SNIPPET_RE = re.compile(
r"""\bcall_tool\(\s*["']([A-Za-z0-9_-]+)["']"""
)
_MUTATION_CMD_RE = re.compile(
r"\b(issues\s+mutate|gerrit\s+(?:comments|vote|submit|abandon)|jiri\s+upload|git\s+push)\b"
)
_ARG_TABLE_HEADER_RE = re.compile(
r"^\|\s*(?:Argument|Parameter|Arg|Flag)\s*\|", re.IGNORECASE
)
_INLINE_CODE_OR_LINK_RE = re.compile(
r"`+[^`]*`+|\[(?:`+[^`]*`+|[^\]])*\]\(([^)]*)\)"
)
_REF_LINK_DEF_RE = re.compile(r"^\s{0,3}\[(?:`+[^`]*`+|[^\]])+\]:\s*(\S+)")
_FENCE_RE = re.compile(r"^(`{3,})(.*)$")
_NEGATIVE_MARKER_RE = re.compile(
r"#\s*(?:bad|wrong|avoid|invalid|do not|don't)\b", re.IGNORECASE
)
_SKIP_LINK_SCHEMES = (
"http://",
"https://",
"mailto:",
"go/",
"sidecar://",
"conversation://",
)
_AGENT_KW_ALLOWED = types.MappingProxyType(
{
"workspace": _ALLOWED_WORKFLOW_WORKSPACES,
"model": _ALLOWED_WORKFLOW_MODELS,
}
)
_CLI_RUNNER_MODULE_ATTRS = types.MappingProxyType(
{
"subprocess": frozenset(
{
"Popen",
"call",
"check_call",
"check_output",
"getoutput",
"getstatusoutput",
"run",
}
),
"os": frozenset(
{
"execl",
"execle",
"execlp",
"execlpe",
"execv",
"execve",
"execvp",
"execvpe",
"popen",
"spawnl",
"spawnle",
"spawnlp",
"spawnlpe",
"spawnv",
"spawnve",
"spawnvp",
"spawnvpe",
"system",
}
),
"asyncio": frozenset(
{"create_subprocess_exec", "create_subprocess_shell"}
),
}
)
_CLI_RUNNER_DIRECT_NAMES = frozenset(
{
"Popen",
"call",
"check_call",
"check_output",
"create_subprocess_exec",
"create_subprocess_shell",
"exec_cmd",
"getoutput",
"getstatusoutput",
"popen",
"run",
"run_cli",
"run_cmd",
"run_command",
"sh",
"system",
}
)
class Finding(TypedDict, total=False):
filepath: str
message: str
level: str
replacements: list[str]
line: int
class _UniqueKeyLoader(yaml.SafeLoader):
"""YAML SafeLoader that rejects duplicate mapping keys.
PyYAML silently overwrites duplicate keys, whereas Jetski's Go yaml.v3
skill loader rejects them at runtime.
"""
def construct_mapping(
self, node: yaml.MappingNode, deep: bool = False
) -> dict[Any, Any]:
"""Constructs a YAML mapping while checking for duplicate keys.
Args:
node: The YAML mapping node to construct.
deep: Whether to recursively construct nested objects.
Returns:
The constructed dictionary.
Raises:
yaml.constructor.ConstructorError: If a duplicate or unhashable key is
present.
"""
seen: set[Any] = set()
for key_node, _ in node.value:
if key_node.tag == "tag:yaml.org,2002:merge":
continue
key = self.construct_object(key_node, deep=deep)
if not isinstance(key, collections.abc.Hashable):
raise yaml.constructor.ConstructorError(
"while constructing a mapping",
node.start_mark,
"found unhashable key",
key_node.start_mark,
)
if key in seen:
raise yaml.constructor.ConstructorError(
"while constructing a mapping",
node.start_mark,
f"duplicate YAML key '{key}' in frontmatter",
key_node.start_mark,
)
seen.add(key)
return super().construct_mapping(node, deep=deep)
def _parse_skill_frontmatter(
content: str,
) -> tuple[dict[str, Any], str]:
"""Parses YAML frontmatter from SKILL.md content with duplicate-key checks.
Args:
content: Full raw SKILL.md content.
Returns:
A tuple of (metadata_dict, body_content).
Raises:
ValueError: If frontmatter delimiters are missing, YAML parsing fails,
or the parsed YAML value is not a mapping.
"""
if not content.startswith("---"):
raise ValueError(
"Could not find or parse YAML frontmatter (must start with '---')."
)
parts = content.split("---", 2)
if len(parts) < 3:
raise ValueError(
"Could not find closing '---' delimiter for YAML frontmatter."
)
frontmatter = parts[1]
try:
meta = yaml.load(frontmatter, Loader=_UniqueKeyLoader)
except yaml.YAMLError as e:
raise ValueError(f"Invalid YAML frontmatter: {e}") from e
if not isinstance(meta, dict):
raise ValueError("YAML frontmatter must be a key-value mapping.")
return meta, parts[2]
def _suggest_valid_name(name: str) -> str:
"""Suggests a valid name by replacing invalid characters.
Converts to lowercase, replaces underscores with hyphens, removes
non-alphanumeric characters (except hyphens), and truncates to
MAX_NAME_LENGTH.
Args:
name: The original name string.
Returns:
A suggested valid name string.
"""
suggested = name.lower()
suggested = suggested.replace("_", "-")
suggested = re.sub(r"[^a-z0-9-]", "", suggested)
return suggested[:MAX_NAME_LENGTH].strip("-")
def _pre_process(text: str, tab_size: int) -> str:
"""Pre-processes text to standardize list item indentation.
Fixes bullet points and numbered lists that have excessive spacing.
Standardizes child list items, code blocks, and continuation paragraphs
under numbered list items to match the 4-space list indentation.
Skips lines within code blocks.
Args:
text: The input markdown text.
tab_size: The indentation size to use for numbered lists.
Returns:
The processed text with standardized indentation.
"""
lines = text.split("\n")
processed = []
in_top_level_code_block = False
in_nested_code_block = False
nested_code_block_shifted = False
active_num_indent: int | None = None
for line in lines:
stripped = line.strip()
# Handle top level code block
if in_top_level_code_block:
if stripped.startswith("```"):
in_top_level_code_block = False
processed.append(line)
continue
# Handle nested code block
if in_nested_code_block:
if stripped.startswith("```"):
if nested_code_block_shifted and active_num_indent is not None:
target_3 = " " * (active_num_indent + 3)
if line.startswith(
target_3 + "```"
) and not line.startswith(target_3 + " ```"):
line = " " + line
in_nested_code_block = False
nested_code_block_shifted = False
else:
if nested_code_block_shifted and active_num_indent is not None:
target_3 = " " * (active_num_indent + 3)
if line.startswith(target_3):
line = " " + line
processed.append(line)
continue
if not stripped:
processed.append(line)
continue
if stripped.startswith("#") or re.match(r"^([-*_]\s*){3,}$", stripped):
active_num_indent = None
# Check for numbered list item
num_match = re.match(r"^(\s*)(\d+\.)( +)(.*)$", line)
if num_match:
indent_str = num_match.group(1)
marker_str = num_match.group(2)
rest = num_match.group(4)
repl = " " if tab_size == 2 else " "
line = f"{indent_str}{marker_str}{repl}{rest}"
if tab_size == 4:
active_num_indent = len(indent_str)
in_nested_code_block = False
nested_code_block_shifted = False
processed.append(line)
continue
# Check if non-empty line terminates active_num_indent
if active_num_indent is not None:
indent_len = len(line) - len(line.lstrip(" "))
if indent_len <= active_num_indent:
active_num_indent = None
# Code block opening
if stripped.startswith("```"):
if active_num_indent is not None and tab_size == 4:
target_3 = " " * (active_num_indent + 3)
if line.startswith(target_3 + "```") and not line.startswith(
target_3 + " ```"
):
line = " " + line
nested_code_block_shifted = True
in_nested_code_block = True
else:
in_top_level_code_block = True
processed.append(line)
continue
if active_num_indent is not None and tab_size == 4:
target_3 = " " * (active_num_indent + 3)
target_5 = " " * (active_num_indent + 5)
# 3-space bullet point
bullet_3_match = re.match(
r"^" + target_3 + r"([-*+])( +)(.*)$", line
)
if bullet_3_match:
marker = bullet_3_match.group(1)
rest = bullet_3_match.group(3)
line = " " + target_3 + marker + " " + rest
processed.append(line)
continue
# 5-space sub-bullet
bullet_5_match = re.match(
r"^" + target_5 + r"([-*+])( +)(.*)$", line
)
if bullet_5_match:
marker = bullet_5_match.group(1)
rest = bullet_5_match.group(3)
line = " " + target_5 + marker + " " + rest
processed.append(line)
continue
# 5-space continuation
if line.startswith(target_5) and not line.startswith(
target_5 + " "
):
line = " " + line
processed.append(line)
continue
# 3-space continuation or paragraph
if line.startswith(target_3) and not line.startswith(
target_3 + " "
):
line = " " + line
processed.append(line)
continue
# Match bullet points (-, *, +) at the start of the line with excessive spacing.
# Capture group 1: indentation and bullet.
# Capture group 2: extra spaces.
match = re.search(r"^(\s*[-*+])( +)(?=\S)", line)
if match:
repl = " "
line = match.group(1) + repl + line[match.end() :]
else:
# Match numbered lists (e.g., 1.) at the start of the line.
match = re.search(r"^(\s*\d+\.)( +)(?=\S)", line)
if match:
repl = " " if tab_size == 2 else " "
line = match.group(1) + repl + line[match.end() :]
processed.append(line)
return "\n".join(processed)
def _post_process(text: str) -> str:
"""Post-processes text to clean up whitespace.
Removes trailing whitespace while preserving Markdown hard line breaks
(at least two spaces at the end of a line), collapses multiple empty
lines, and ensures the file ends with a newline.
Args:
text: The input markdown text.
Returns:
The processed text with clean whitespace.
"""
# Remove trailing whitespace, but preserve Markdown hard line breaks (two spaces).
text = re.sub(
r"[ \t]+$",
lambda m: " " if m.group(0).endswith(" ") else "",
text,
flags=re.MULTILINE,
)
# Collapse triple newlines or more into double newlines.
text = re.sub(r"\n{3,}", "\n\n", text)
if not text.endswith("\n"):
text += "\n"
return text
def _format_paragraph(paragraph: list[str], width: int) -> list[str]:
"""Formats a single paragraph of markdown text.
Handles list items by indenting subsequent lines to match the marker.
Preserves hard line breaks in normal paragraphs.
Args:
paragraph: A list of lines forming a paragraph.
width: The maximum line width for wrapping.
Returns:
A list of wrapped and formatted lines.
"""
if not paragraph:
return []
first_line = paragraph[0]
# Check if this is a list item.
list_match = re.search(r"^(\s*)([-*+]|\d+\.)\s+", first_line)
if list_match:
marker = list_match.group(0)
marker_len = len(marker)
subsequent_indent = " " * marker_len
first_line_text = first_line[marker_len:].strip()
other_lines_text = " ".join([line.strip() for line in paragraph[1:]])
full_text = (first_line_text + " " + other_lines_text).strip()
wrapper = textwrap.TextWrapper(
width=width,
initial_indent=marker,
subsequent_indent=subsequent_indent,
break_long_words=False,
break_on_hyphens=False,
)
return wrapper.wrap(full_text)
else:
# Normal paragraph.
indent_match = re.search(r"^\s*", first_line)
indent = indent_match.group(0) if indent_match else ""
# Preserve Markdown hard line breaks (two spaces at end of line).
has_hard_break = paragraph[-1].endswith(" ")
content = " ".join([line.strip() for line in paragraph])
if has_hard_break:
content = content.rstrip() + " "
wrapper = textwrap.TextWrapper(
width=width,
initial_indent=indent,
subsequent_indent=indent,
break_long_words=False,
break_on_hyphens=False,
)
wrapped_lines = wrapper.wrap(content)
if has_hard_break and wrapped_lines:
wrapped_lines[-1] = wrapped_lines[-1].rstrip() + " "
return wrapped_lines
def _is_table_separator(line: str) -> bool:
"""Checks if a line is a markdown table separator (e.g., |---|).
Args:
line: The line to check.
Returns:
True if the line is a table separator, False otherwise.
"""
stripped = line.strip()
return "|" in line and bool(re.fullmatch(r"[|\-\s:]+", stripped))
def _get_table_line_indices(lines: list[str]) -> set[int]:
"""Identifies all lines that are part of a markdown table.
Args:
lines: The markdown lines to evaluate.
Returns:
A set of integer indices representing table lines.
"""
table_indices = set()
in_table = False
for idx, line in enumerate(lines):
stripped = line.strip()
if not stripped:
in_table = False
continue
if (
idx + 1 < len(lines)
and "|" in line
and _is_table_separator(lines[idx + 1])
):
table_indices.add(idx)
if _is_table_separator(line):
in_table = True
table_indices.add(idx)
continue
if in_table:
if "|" in line or stripped.startswith(":"):
table_indices.add(idx)
else:
in_table = False
return table_indices
def format_markdown_with_issues(
text: str, *, tab_size: int = 4, width: int = LINE_LENGTH
) -> tuple[str, list[str]]:
"""Formats markdown text and identifies specific linter issues.
Identifies paragraphs, lists, code blocks, and tables to apply
appropriate formatting while preserving structure. Tracks specific
issues like long lines, trailing whitespace, missing empty lines around
lists and code blocks, etc.
Args:
text: The input markdown text.
tab_size: Indentation size for lists.
width: Maximum line length (defaults to LINE_LENGTH).
Returns:
A tuple containing the formatted markdown string and a list of detected
issues.
"""
issues = []
raw_lines = text.split("\n")
in_code_block = False
has_consecutive_empty_lines = False
has_trailing_whitespace = False
consecutive_empty_count = 0
for line in raw_lines:
stripped = line.strip()
if stripped.startswith("```"):
in_code_block = not in_code_block
consecutive_empty_count = 0
continue
if in_code_block:
continue
if not stripped:
consecutive_empty_count += 1
if consecutive_empty_count >= 2:
has_consecutive_empty_lines = True
else:
consecutive_empty_count = 0
stripped_len = len(line.rstrip(" \t"))
trailing_len = len(line) - stripped_len
if trailing_len > 0 and trailing_len != 2:
has_trailing_whitespace = True
if has_consecutive_empty_lines:
issues.append("consecutive empty lines")
if has_trailing_whitespace:
issues.append("trailing whitespace")
preprocessed_text = _pre_process(text, tab_size)
if preprocessed_text != text:
issues.append("excessive list item spacing")
lines = preprocessed_text.split("\n")
formatted_lines = []
code_blocks: list[str] = []
current_code_block: list[str] = []
in_code_block = False
current_paragraph: list[str] = []
in_table = False
in_list = False
has_missing_empty_line_before_list = False
has_missing_empty_line_after_list = False
has_missing_empty_line_before_code_block = False
has_missing_empty_line_after_code_block = False
just_closed_code_block = False
# Whether the last emitted non-empty block is a list item paragraph. A
# list item may directly follow another list item (tight list), but must
# be separated by an empty line from any other preceding block.
last_block_is_list_item = False
def flush_paragraph() -> None:
nonlocal current_paragraph, last_block_is_list_item
if current_paragraph:
last_block_is_list_item = bool(
_LIST_ITEM_RE.match(current_paragraph[0])
)
formatted_lines.extend(_format_paragraph(current_paragraph, width))
current_paragraph[:] = []
def emit(line: str) -> None:
nonlocal last_block_is_list_item
if line.strip():
last_block_is_list_item = False
formatted_lines.append(line)
def needs_empty_line() -> bool:
return bool(formatted_lines) and bool(formatted_lines[-1].strip())
def end_list_with_empty_line() -> None:
# A non-indented block (heading, blockquote, table, or link reference
# definition) directly after a list must be separated by an empty line.
nonlocal in_list, has_missing_empty_line_after_list
if in_list and needs_empty_line():
formatted_lines.append("")
has_missing_empty_line_after_list = True
in_list = False
for line in lines:
stripped_line = line.strip()
is_indented = line.startswith((" ", "\t"))
if in_code_block:
if stripped_line.startswith("```"):
current_code_block.append(line)
placeholder = f"__SKILL_LINTER_CODE_BLOCK_{len(code_blocks)}__"
code_blocks.append("\n".join(current_code_block))
emit(placeholder)
current_code_block = []
in_code_block = False
if not is_indented:
in_list = False
just_closed_code_block = True
else:
current_code_block.append(line)
continue
if just_closed_code_block:
just_closed_code_block = False
if stripped_line:
formatted_lines.append("")
has_missing_empty_line_after_code_block = True
if stripped_line.startswith("```"):
flush_paragraph()
if needs_empty_line():
formatted_lines.append("")
has_missing_empty_line_before_code_block = True
current_code_block.append(line)
in_code_block = True
# Code blocks indented under a list item belong to that item.
if not is_indented:
in_list = False
continue
if not stripped_line:
flush_paragraph()
in_table = False
# A list stays active across empty lines; it only ends at the
# next non-indented block that is not a list item.
formatted_lines.append(line)
continue
if in_table:
if "|" in line or stripped_line.startswith(":"):
emit(line)
continue
else:
in_table = False
if _is_table_separator(line):
if current_paragraph:
header_line = current_paragraph.pop()
flush_paragraph()
if not header_line.startswith((" ", "\t")):
end_list_with_empty_line()
emit(header_line)
else:
flush_paragraph()
emit(line)
in_table = True
in_list = False
continue
if stripped_line.startswith("#") or stripped_line.startswith(">"):
flush_paragraph()
if not is_indented:
end_list_with_empty_line()
emit(line)
continue
if _LINK_REFERENCE_RE.match(stripped_line):
flush_paragraph()
end_list_with_empty_line()
emit(line)
continue
if _LIST_ITEM_RE.match(line):
flush_paragraph()
if needs_empty_line() and not last_block_is_list_item:
formatted_lines.append("")
has_missing_empty_line_before_list = True
in_list = True
current_paragraph.append(line)
continue
# Non-indented text directly following a list item is a lazy
# continuation of that item, so the list remains active. After an
# empty line, non-indented text starts a new paragraph that ends the
# list.
if not is_indented and not current_paragraph and not needs_empty_line():
in_list = False
current_paragraph.append(line)
if line.endswith(" "):
flush_paragraph()
flush_paragraph()
# If a file ends inside a code block, preserve it.
if in_code_block and current_code_block:
placeholder = f"__SKILL_LINTER_CODE_BLOCK_{len(code_blocks)}__"
code_blocks.append("\n".join(current_code_block))
formatted_lines.append(placeholder)
formatted_text = _post_process("\n".join(formatted_lines))
for idx, code_block in enumerate(code_blocks):
placeholder = f"__SKILL_LINTER_CODE_BLOCK_{idx}__"
formatted_text = formatted_text.replace(placeholder, code_block)
prep_table_indices = _get_table_line_indices(lines)
in_code_block = False
has_long_lines = False
for idx, line in enumerate(lines):
if idx in prep_table_indices:
continue
stripped = line.strip()
if stripped.startswith("```"):
in_code_block = not in_code_block
continue
if in_code_block:
continue
if not stripped:
continue
if _LINK_REFERENCE_RE.match(stripped):
continue
if len(line) > width:
has_long_lines = True
break
if has_long_lines:
issues.append(f"lines exceeding {width} characters")
if has_missing_empty_line_before_list:
issues.append("missing empty line before list")
if has_missing_empty_line_after_list:
issues.append("missing empty line after list")
if has_missing_empty_line_before_code_block:
issues.append("missing empty line before code block")
if has_missing_empty_line_after_code_block:
issues.append("missing empty line after code block")
if formatted_text != text and not issues:
issues.append("formatting inconsistencies")
return formatted_text, issues
def format_markdown(
text: str, *, tab_size: int = 4, width: int = LINE_LENGTH
) -> str:
"""Formats markdown text to fit within the specified width.
Args:
text: The input markdown text.
tab_size: Indentation size for lists.
width: Maximum line length (defaults to LINE_LENGTH).
Returns:
The formatted markdown string.
"""
formatted, _ = format_markdown_with_issues(
text, tab_size=tab_size, width=width
)
return formatted
def _validate_name(
meta: dict[str, Any], fixit: bool
) -> tuple[list[str], list[str]]:
"""Validates the 'name' field in the skill metadata.
Checks for presence, type, length, and valid characters. If fixit is
True, attempts to automatically fix issues.
Args:
meta: The metadata dictionary.
fixit: Whether to apply fixes.
Returns:
A tuple of (errors, fixes_applied).
"""
errors = []
fixes_applied: list[str] = []
if "name" not in meta:
errors.append('Missing required field "name" in frontmatter.')
return errors, fixes_applied
name = meta["name"]
if not isinstance(name, str) or not name.strip():
errors.append('Field "name" must be a non-empty string.')
return errors, fixes_applied
has_length_error = len(name) > MAX_NAME_LENGTH
has_char_error = (
not re.fullmatch(r"^[a-z0-9-]+$", name)
or name.startswith("-")
or name.endswith("-")
or "--" in name
)
if has_length_error and not fixit:
errors.append(f'Field "name" exceeds {MAX_NAME_LENGTH} characters.')
if has_char_error and not fixit:
errors.append(
'Field "name" must contain only lowercase letters, numbers, and'
" single hyphens."
)
if fixit and (has_length_error or has_char_error):
suggested_name = re.sub(r"-{2,}", "-", _suggest_valid_name(name))
if suggested_name != name and suggested_name:
meta["name"] = suggested_name
fixes_applied.append(f'Fix name to "{suggested_name}"')
elif not suggested_name:
if has_length_error:
errors.append(
f'Field "name" exceeds {MAX_NAME_LENGTH} characters.'
)
if has_char_error:
errors.append(
'Field "name" must contain only lowercase letters,'
" numbers, and single hyphens."
)
if "<" in name or ">" in name:
if not fixit:
errors.append('Field "name" cannot contain XML tags.')
return errors, fixes_applied
def _validate_description(
meta: dict[str, Any], fixit: bool
) -> tuple[list[str], list[str]]:
"""Validates the 'description' field in the skill metadata.
Checks for presence, emptiness, length, and XML tags. If fixit is
True, attempts to automatically fix issues by stripping tags.
Args:
meta: The metadata dictionary.
fixit: Whether to apply fixes.
Returns:
A tuple of (errors, fixes_applied).
"""
errors = []
fixes_applied: list[str] = []
if "description" not in meta:
errors.append('Missing required field "description" in frontmatter.')
return errors, fixes_applied
description = meta["description"]
if not isinstance(description, str) or not description.strip():
errors.append('Field "description" cannot be empty.')
return errors, fixes_applied
if len(description) > MAX_DESCRIPTION_LENGTH:
errors.append(
f'Field "description" exceeds {MAX_DESCRIPTION_LENGTH} characters.'
)
if "<" in description or ">" in description:
if not fixit:
errors.append('Field "description" cannot contain XML tags.')
else:
cleaned_description = re.sub(r"<[^>]+>", "", description)
cleaned_description = re.sub(
r" +", " ", cleaned_description
).strip()
if cleaned_description != description:
meta["description"] = cleaned_description
fixes_applied.append("Strip XML tags from description.")
else:
errors.append(
'Field "description" cannot contain angle brackets (< or >).'
)
return errors, fixes_applied
def _generate_frontmatter_lines(
key: str, val: Any, indent: int = 0
) -> list[str]:
"""Generates lines for the YAML frontmatter.
Handles lists, dicts, None values, and wraps long descriptions using scalar
blocks if necessary.
Args:
key: The metadata key.
val: The metadata value.
indent: Current indentation level in spaces.
Returns:
A list of lines for the frontmatter.
"""
lines = []
prefix = " " * indent
if isinstance(val, list):
lines.append(f"{prefix}{key}:")
for item in val:
if isinstance(item, dict):
first = True
for sub_k, sub_v in item.items():
sub_lines = _generate_frontmatter_lines(
str(sub_k), sub_v, indent + 4
)
if first and sub_lines:
sub_lines[0] = f"{prefix} - " + sub_lines[0].lstrip()
first = False
lines.extend(sub_lines)
else:
lines.append(f"{prefix} - {item}")
elif isinstance(val, dict):
lines.append(f"{prefix}{key}:")
for sub_k, sub_v in val.items():
lines.extend(
_generate_frontmatter_lines(str(sub_k), sub_v, indent + 2)
)
elif val is None:
lines.append(f"{prefix}{key}:")
elif (
indent == 0
and key == "description"
and isinstance(val, str)
and len(val) > LINE_LENGTH
):
lines.append(f"{key}: >")
wrapper = textwrap.TextWrapper(
width=LINE_LENGTH - 2, initial_indent=" ", subsequent_indent=" "
)
lines.extend(wrapper.wrap(val))
elif isinstance(val, str) and (
val[:1] in "@!&*{}[]|>'\"%`#,?:" or ": " in val or " #" in val
):
lines.append(f"{prefix}{key}: {json.dumps(val)}")
else:
lines.append(f"{prefix}{key}: {val}")
return lines
def _build_finding(
rel_path: str,
errors: list[str],
warnings: list[str],
fixes_applied: list[str],
new_content: str,
original_content: str,
) -> Finding | None:
"""Builds a Finding dict if there are errors, warnings, or suggested fixes.
Args:
rel_path: Relative path to the file.
errors: List of error messages.
warnings: List of warning messages.
fixes_applied: List of fixes applied.
new_content: The newly formatted content.
original_content: The original file content.
Returns:
A Finding dict or None if no findings.
"""
if not (new_content != original_content or errors or warnings):
return None
level = "error" if errors else "warning"
messages = []
if errors:
messages.append("Errors:\n" + "\n".join(f"- {e}" for e in errors))
if warnings:
messages.append("Warnings:\n" + "\n".join(f"- {w}" for w in warnings))
if fixes_applied and not messages:
messages.append(
"Suggested fixes:\n" + "\n".join(f"- {f}" for f in fixes_applied)
)
finding_message = "\n\n".join(messages) or "Skill linter findings."
if fixes_applied or (new_content != original_content):
finding_message += "\n\nYou can run fx format-code to fix these issues."
finding: Finding = {
"filepath": rel_path,
"message": finding_message,
"level": level,
}
if new_content != original_content:
finding["replacements"] = [new_content]
return finding
def lint_single_skill(
skill_file: str,
fixit: bool,
stdout_mode: bool,
suggest_fix_in_json_mode: bool = False,
) -> tuple[int, list[Finding]]:
"""Lints and formats a single SKILL.md file.
Reads the file, parses metadata (including duplicate YAML key checks),
validates fields, formats content, and writes back or outputs findings
depending on the mode.
Args:
skill_file: Path to the SKILL.md file.
fixit: Whether to apply fixes in-place.
stdout_mode: Whether to output fixed content to stdout.
suggest_fix_in_json_mode: Whether to return findings as JSON.
Returns:
A tuple of (exit_code, findings).
"""
findings = []
rel_path = os.path.relpath(skill_file)
try:
with open(skill_file, "r", encoding="utf-8") as f:
original_content = f.read()
except OSError as e:
msg = f"Error reading '{skill_file}': {e}"
if suggest_fix_in_json_mode:
findings.append(
Finding(filepath=rel_path, message=msg, level="error")
)
return 0, findings
logging.error(msg)
return 1, findings
try:
meta, content = _parse_skill_frontmatter(original_content)
except ValueError as e:
msg = f"Error in '{skill_file}': {e}"
if suggest_fix_in_json_mode:
findings.append(
Finding(filepath=rel_path, message=msg, level="error")
)
return 0, findings
logging.error(msg)
return 1, findings
content = content.lstrip("\n")
errors = []
warnings = []
fixes_applied: list[str] = []
unexpected_keys = set(meta.keys()) - _ALLOWED_SKILL_FRONTMATTER_KEYS
if unexpected_keys:
errors.append(
"Unexpected frontmatter key(s): "
+ ", ".join(sorted(str(k) for k in unexpected_keys))
+ "."
)
name_errors, name_fixes = _validate_name(
meta, fixit or suggest_fix_in_json_mode
)
errors.extend(name_errors)
fixes_applied.extend(name_fixes)
description_errors, description_fixes = _validate_description(
meta, fixit or suggest_fix_in_json_mode
)
errors.extend(description_errors)
fixes_applied.extend(description_fixes)
formatted_content, markdown_issues = format_markdown_with_issues(content)
if formatted_content != content:
issues_str = ", ".join(markdown_issues)
if not fixit and not suggest_fix_in_json_mode:
warnings.append(f"Markdown body contains {issues_str}.")
else:
fixes_applied.append(f"Address markdown body: {issues_str}.")
content = formatted_content
skill_name = os.path.basename(os.path.dirname(skill_file))
ordered_keys = ["name", "description"]
frontmatter_lines = []
for key in ordered_keys:
if key in meta:
frontmatter_lines.extend(
_generate_frontmatter_lines(key, meta[key])
)
for key in meta:
if key not in ordered_keys:
frontmatter_lines.extend(
_generate_frontmatter_lines(key, meta[key])
)
new_frontmatter = "\n".join(frontmatter_lines) + "\n"
new_content = f"---\n{new_frontmatter}---\n\n{content}"
if suggest_fix_in_json_mode:
finding = _build_finding(
rel_path,
errors,
warnings,
fixes_applied,
new_content,
original_content,
)
if finding:
findings.append(finding)
return 0, findings
if warnings:
for warn in warnings:
logging.warning(f"[{skill_name}] Warning: {warn}")
if errors:
for err in errors:
logging.error(f"[{skill_name}] Error: {err}")
has_autofixes = bool(
fixes_applied
or (formatted_content != content)
or (new_content != original_content)
)
if has_autofixes and not suggest_fix_in_json_mode:
logging.warning(
f"[{skill_name}] You can run fx format-code to fix these issues."
)
if stdout_mode:
print(new_content, end="")
elif not suggest_fix_in_json_mode:
if fixit and new_content != original_content:
try:
with open(skill_file, "w", encoding="utf-8") as f:
f.write(new_content)
logging.info(f"[{skill_name}] Fixed in-place.")
except OSError as e:
logging.error(f"Error writing to '{skill_file}': {e}")
return 1, findings
elif not errors and not warnings and new_content == original_content:
logging.info(f"PASSED: '{skill_name}' is valid.")
return (1 if errors else 0), findings
def _rel_filepath(abs_path: str, repo_root: str | None) -> str:
"""Computes a normalized repository-relative path for SHAC findings.
Args:
abs_path: Absolute or relative file path.
repo_root: Optional repository root path.
Returns:
Forward-slash relative filepath string.
"""
base = os.path.abspath(repo_root) if repo_root is not None else os.getcwd()
try:
rel = os.path.relpath(os.path.abspath(abs_path), base)
except ValueError:
rel = abs_path
return rel.replace(os.sep, "/")
def _resolve_local_target(
target: str,
source_dir: str,
repo_root: str | None,
fuchsia_root: str | None,
) -> bool:
"""Checks whether a local link or config path exists in the checkout.
Resolves root-anchored ('//' or '/') paths against both repo_root and
fuchsia_root so links from vendor/google into fuchsia.git succeed.
Args:
target: Link target or JSON config path string.
source_dir: Directory containing the referencing file.
repo_root: Optional SCM root of the current repository.
fuchsia_root: Optional Fuchsia checkout root directory.
Returns:
True if any candidate path exists on disk, False otherwise.
"""
roots = tuple(
os.path.abspath(r) for r in (repo_root, fuchsia_root) if r is not None
)
if target.startswith("/"):
rel = target[2:] if target.startswith("//") else target[1:]
return any(os.path.exists(os.path.join(r, rel)) for r in roots) or (
not roots and os.path.exists(rel)
)
candidates = (
os.path.join(source_dir, target),
*(os.path.join(r, target) for r in roots),
)
return any(os.path.exists(c) for c in candidates)
def _iter_markdown_prose_and_code(
lines: Sequence[str], start_lineno: int
) -> tuple[
Sequence[tuple[int, str, str]],
Sequence[tuple[int, str, Sequence[str]]],
]:
"""Splits Markdown lines into prose lines and fenced code blocks.
Args:
lines: Raw Markdown body lines.
start_lineno: 1-based line number of lines[0].
Returns:
A tuple (prose_lines, code_blocks), where prose_lines is a sequence of
(lineno, raw_line, stripped_inline_code_line) and code_blocks is a
sequence of (opening_lineno, fence_header, block_lines).
"""
prose_lines: list[tuple[int, str, str]] = []
code_blocks: list[tuple[int, str, tuple[str, ...]]] = []
in_code = False
fence_ticks = 0
fence_lineno = start_lineno
fence_hdr = ""
cur_block: list[str] = []
for offset, raw in enumerate(lines):
lineno = start_lineno + offset
stripped = raw.strip()
if (m_fence := _FENCE_RE.match(stripped)) is not None:
ticks = len(m_fence.group(1))
rest = m_fence.group(2).strip()
if not in_code and "`" not in rest:
in_code = True
fence_ticks = ticks
fence_lineno = lineno
fence_hdr = rest
cur_block = []
continue
if in_code and ticks >= fence_ticks and not rest:
code_blocks.append((fence_lineno, fence_hdr, tuple(cur_block)))
in_code = False
fence_ticks = 0
cur_block = []
continue
if in_code:
cur_block.append(raw)
else:
no_inline = re.sub(r"`+[^`]*`+", "", raw)
prose_lines.append((lineno, raw, no_inline))
if in_code and cur_block:
code_blocks.append((fence_lineno, fence_hdr, tuple(cur_block)))
return tuple(prose_lines), tuple(code_blocks)
def _check_markdown_links_and_snippets(
abs_file: str,
rel_path: str,
lines: Sequence[str],
start_lineno: int,
repo_root: str | None,
fuchsia_root: str | None,
) -> Sequence[Finding]:
"""Validates Markdown links, local paths, and Jetski snippet invocations.
Args:
abs_file: Absolute path to the Markdown file.
rel_path: Repository-relative path for findings.
lines: Markdown lines to inspect.
start_lineno: 1-based line number corresponding to lines[0].
repo_root: Optional SCM repository root.
fuchsia_root: Optional Fuchsia checkout root.
Returns:
A sequence of Finding dicts with line numbers.
"""
findings: list[Finding] = []
source_dir = os.path.dirname(os.path.abspath(abs_file))
prose_lines, code_blocks = _iter_markdown_prose_and_code(
lines, start_lineno
)
for lineno, raw_line, no_inline in prose_lines:
if (m_local := _LOCAL_MACHINE_PATH_RE.search(no_inline)) is not None:
findings.append(
Finding(
filepath=rel_path,
line=lineno,
level="error",
message=(
f'Machine-local path "{m_local.group(0)}" is not'
" portable; use repository-relative paths instead."
),
)
)
targets: list[str] = []
for m_link in _INLINE_CODE_OR_LINK_RE.finditer(raw_line):
if m_link.group(1) is not None:
targets.append(m_link.group(1))
if (ref_match := _REF_LINK_DEF_RE.match(raw_line)) is not None:
targets.append(ref_match.group(1))
for raw_target in targets:
parts = raw_target.strip().split()
if not parts:
continue
raw_url = parts[0]
if raw_url.startswith("<") and raw_url.endswith(">"):
target = raw_url[1:-1].strip()
else:
target = raw_url
if target.startswith("file:"):
findings.append(
Finding(
filepath=rel_path,
line=lineno,
level="error",
message=(
f'Invalid file URI link "{target}": RFC 8089 parses'
" the authority segment as a hostname. Use a"
' relative Markdown path (e.g. "references/...").'
),
)
)
continue
clean_target = target.split("#", 1)[0]
if (
not clean_target
or clean_target.startswith(_SKIP_LINK_SCHEMES)
or "{" in clean_target
or "}" in clean_target
):
continue
if (
repo_root is not None or fuchsia_root is not None
) and not _resolve_local_target(
clean_target, source_dir, repo_root, fuchsia_root
):
findings.append(
Finding(
filepath=rel_path,
line=lineno,
level="error",
message=(
f'Broken local link "{raw_target}": target file'
" does not exist in the checkout."
),
)
)
# Check fenced code blocks for invalid Jetski API / CLI examples (skipping
# blocks explicitly marked as negative examples).
for fence_lineno, _, block_lines in code_blocks:
block_text = "\n".join(block_lines)
if _NEGATIVE_MARKER_RE.search(block_text):
continue
for idx, code_line in enumerate(block_lines):
code_lineno = fence_lineno + 1 + idx
for m_tool in _CALL_TOOL_SNIPPET_RE.finditer(code_line):
tool_name = m_tool.group(1)
if tool_name not in _ALLOWED_CALL_TOOLS:
allowed_str = ", ".join(sorted(_ALLOWED_CALL_TOOLS))
findings.append(
Finding(
filepath=rel_path,
line=code_lineno,
level="error",
message=(
f'call_tool("{tool_name}", ...) is invalid and'
" raises ToolError at runtime. Allowed"
f" call_tool names: {allowed_str}."
),
)
)
if re.search(r"(?:^|\s)fx\s+workflow\b", code_line):
findings.append(
Finding(
filepath=rel_path,
line=code_lineno,
level="error",
message=(
'"fx workflow" is not a valid Fuchsia CLI command;'
" invoke saved workflows via /<workflow-name> or"
" the run_workflow tool."
),
)
)
return tuple(findings)
def _lint_skill_semantic(
skill_file: str,
repo_root: str | None,
fuchsia_root: str | None,
) -> Sequence[Finding]:
"""Runs semantic, structural, and link lint rules on a SKILL.md file.
Args:
skill_file: Path to SKILL.md.
repo_root: Optional SCM repository root.
fuchsia_root: Optional Fuchsia checkout root.
Returns:
A sequence of Finding dicts.
"""
findings: list[Finding] = []
abs_file = os.path.abspath(skill_file)
rel_path = _rel_filepath(abs_file, repo_root)
try:
with open(abs_file, "r", encoding="utf-8") as f:
raw_content = f.read()
except OSError as e:
findings.append(
Finding(
filepath=rel_path,
line=1,
level="error",
message=f"Could not read SKILL.md: {e}",
)
)
return tuple(findings)
try:
meta, body = _parse_skill_frontmatter(raw_content)
except ValueError as e:
# Already surfaced as an error by lint_single_skill; include here if
# _lint_skill_semantic is invoked standalone via --lint-json.
findings.append(
Finding(
filepath=rel_path,
line=1,
level="error",
message=str(e),
)
)
return tuple(findings)
parts = raw_content.split("---", 2)
fm_line_count = parts[1].count("\n") + 2
if body.startswith("\r\n"):
body_after_delim = body[2:]
elif body.startswith("\n"):
body_after_delim = body[1:]
else:
body_after_delim = body
body_lines = body_after_delim.split("\n")
raw_name = meta.get("name")
name = raw_name.strip() if isinstance(raw_name, str) else ""
raw_desc = meta.get("description")
description = raw_desc.strip() if isinstance(raw_desc, str) else ""
skill_dir = os.path.dirname(abs_file)
folder_name = os.path.basename(skill_dir)
# 1. Singular .agent/ directory check.
if "/.agent/" in f"/{rel_path}" and not rel_path.startswith(
_LEGACY_SINGULAR_DOT_AGENT_PREFIXES
):
findings.append(
Finding(
filepath=rel_path,
line=1,
level="error",
message=(
f'Skill path "{rel_path}" uses singular ".agent/"; use'
' plural ".agents/" so Jetski discovers it.'
),
)
)
# 2. Folder name vs YAML name & naming conventions (allowing nested
# subsystem suites under skills/<topic>/<task>[/<lang>]/SKILL.md).
rel_parts = tuple(rel_path.split("/"))
skills_indices = tuple(
i for i, seg in enumerate(rel_parts[:-1]) if seg == "skills"
)
suite_dirs = (
rel_parts[skills_indices[-1] + 1 : -1]
if skills_indices
else (folder_name,)
)
if name and folder_name and not folder_name.startswith("tmp"):
if len(suite_dirs) >= 2:
if (
underscore_dir := next(
(d for d in suite_dirs if "_" in d), None
)
) is not None:
findings.append(
Finding(
filepath=rel_path,
line=2,
level="warning",
message=(
f'Nested skill folder "{underscore_dir}" uses'
" underscores; prefer kebab-case."
),
)
)
elif folder_name.replace("_", "-") != name:
findings.append(
Finding(
filepath=rel_path,
line=2,
level="warning",
message=(
f'Enclosing folder "{folder_name}" does not match YAML'
f' skill name "{name}".'
),
)
)
elif folder_name != name:
findings.append(
Finding(
filepath=rel_path,
line=2,
level="warning",
message=(
f'Skill folder "{folder_name}" uses underscores; prefer'
f' kebab-case matching "{name}".'
),
)
)
if name and _FILLER_NAME_RE.search(name):
findings.append(
Finding(
filepath=rel_path,
line=2,
level="warning",
message=(
f'Skill name "{name}" contains filler words (skill, guide,'
" playbook, how-to, checklist, helper, utils); prefer"
" concise <domain>-<action> or <verb>-<noun> naming."
),
)
)
# 3. Progressive Disclosure & trigger contract in description.
if description:
if _BINARY_IN_DESC_RE.search(description):
findings.append(
Finding(
filepath=rel_path,
line=3,
level="error",
message=(
'Frontmatter "description" contains executable binary'
" or build paths, violating Progressive Disclosure."
" Move command invocations into the SKILL.md body."
),
)
)
if not _POSITIVE_TRIGGER_RE.search(description):
findings.append(
Finding(
filepath=rel_path,
line=3,
level="warning",
message=(
'Frontmatter "description" should include an explicit'
' positive trigger (e.g. "Use when...").'
),
)
)
if name != "review" and not _NEGATIVE_TRIGGER_RE.search(description):
findings.append(
Finding(
filepath=rel_path,
line=3,
level="warning",
message=(
'Frontmatter "description" should include an explicit'
' negative scope boundary (e.g. "Don\'t use for...") to'
" prevent co-triggering collisions."
),
)
)
# 4. Size / view_file truncation limits & auxiliary skill dir files.
line_count = len(raw_content.splitlines())
byte_count = len(raw_content.encode("utf-8"))
if line_count > _MAX_SKILL_LINES or byte_count > _MAX_SKILL_BYTES:
level = "warning" if rel_path in _LEGACY_OVERSIZED_SKILLS else "error"
findings.append(
Finding(
filepath=rel_path,
line=1,
level=level,
message=(
f"SKILL.md is {line_count} lines ({byte_count} bytes),"
f" exceeding the {_MAX_SKILL_LINES}-line /"
f" {_MAX_SKILL_BYTES}-byte view_file ceiling. Offload"
" detailed rubrics and templates to references/*.md."
),
)
)
elif line_count > _WARN_SKILL_LINES or byte_count > _WARN_SKILL_BYTES:
findings.append(
Finding(
filepath=rel_path,
line=1,
level="warning",
message=(
f"SKILL.md is {line_count} lines ({byte_count} bytes),"
f" exceeding the {_WARN_SKILL_LINES}-line /"
f" {_WARN_SKILL_BYTES}-byte soft limit. Consider moving"
" detailed material to references/*.md."
),
)
)
for extra_doc in ("README.md", "CHANGELOG.md"):
if os.path.isfile(os.path.join(skill_dir, extra_doc)):
findings.append(
Finding(
filepath=rel_path,
line=1,
level="warning",
message=(
f'Skill directory contains "{extra_doc}"; agents only'
" load SKILL.md and linked files under references/."
),
)
)
# 5. Links, machine-local paths, and Jetski API snippets.
findings.extend(
_check_markdown_links_and_snippets(
abs_file,
rel_path,
body_lines,
fm_line_count,
repo_root,
fuchsia_root,
)
)
return tuple(findings)
def _validate_args_schema(
args_schema: Any, rel_manifest: str
) -> tuple[Set[str] | None, bool, Sequence[Finding]]:
"""Validates workflow.json 'args' JSON Schema structure.
Args:
args_schema: Parsed 'args' value from workflow.json.
rel_manifest: Relative path to workflow.json for findings.
Returns:
A tuple (declared_props, has_safe_dry_run, findings), where
declared_props is the set of property names (or None if 'args' is
invalid/unspecified) and has_safe_dry_run indicates whether 'dry_run'
defaults to True.
"""
findings: list[Finding] = []
if not isinstance(args_schema, dict):
findings.append(
Finding(
filepath=rel_manifest,
line=1,
level="error",
message='"args" in workflow.json must be a JSON Schema object.',
)
)
return None, False, tuple(findings)
if args_schema.get("type") != "object":
findings.append(
Finding(
filepath=rel_manifest,
line=1,
level="error",
message=(
'"args.type" in workflow.json must be "object" so'
" run_workflow can validate structured arguments."
),
)
)
props = args_schema.get("properties", {})
if not isinstance(props, dict):
findings.append(
Finding(
filepath=rel_manifest,
line=1,
level="error",
message='"args.properties" in workflow.json must be an object.',
)
)
return None, False, tuple(findings)
for prop_name, prop_spec in props.items():
if not isinstance(prop_spec, dict):
findings.append(
Finding(
filepath=rel_manifest,
line=1,
level="error",
message=(
f'Property "{prop_name}" in workflow.json'
" args.properties must be a schema object."
),
)
)
continue
desc = prop_spec.get("description")
if not isinstance(desc, str) or not desc.strip():
findings.append(
Finding(
filepath=rel_manifest,
line=1,
level="warning",
message=(
f'Argument "{prop_name}" in workflow.json'
' args.properties is missing a "description" (agents'
" rely on manifest arg descriptions, not README.md)."
),
)
)
required = args_schema.get("required", [])
if not isinstance(required, list) or not all(
isinstance(r, str) for r in required
):
findings.append(
Finding(
filepath=rel_manifest,
line=1,
level="error",
message=(
'"args.required" in workflow.json must be an array of'
" property names."
),
)
)
else:
for req_key in required:
if req_key not in props:
findings.append(
Finding(
filepath=rel_manifest,
line=1,
level="error",
message=(
f'Required argument "{req_key}" in workflow.json is'
' not defined in "args.properties".'
),
)
)
dry_run_spec = props.get("dry_run")
has_safe_dry_run = (
isinstance(dry_run_spec, dict) and dry_run_spec.get("default") is True
)
return frozenset(props.keys()), has_safe_dry_run, tuple(findings)
def _extract_cmd_expr_text(
expr: ast.AST,
var_cmds: Mapping[str, str] | None = None,
) -> str:
"""Extracts static command text from a string, f-string, or sequence AST node.
Args:
expr: Python AST expression representing a CLI command or argument list.
var_cmds: Optional mapping of local variable names to extracted command
strings.
Returns:
Space-joined static string tokens from expr, or an empty string.
"""
if isinstance(expr, ast.Constant) and isinstance(expr.value, str):
return expr.value
if isinstance(expr, ast.JoinedStr):
return "".join(
v.value
for v in expr.values
if isinstance(v, ast.Constant) and isinstance(v.value, str)
)
if isinstance(expr, (ast.List, ast.Tuple)):
return " ".join(
tok
for elt in expr.elts
if (tok := _extract_cmd_expr_text(elt, var_cmds))
)
if isinstance(expr, ast.BinOp) and isinstance(expr.op, ast.Add):
left = _extract_cmd_expr_text(expr.left, var_cmds)
right = _extract_cmd_expr_text(expr.right, var_cmds)
return " ".join(part for part in (left, right) if part)
if (
isinstance(expr, ast.Name)
and var_cmds is not None
and expr.id in var_cmds
):
return var_cmds[expr.id]
return ""
def _is_cli_runner_call(node: ast.Call) -> bool:
"""Checks whether an AST Call node invokes a subprocess or CLI runner.
Args:
node: AST Call node to inspect.
Returns:
True if the call targets a known subprocess/OS/CLI execution function.
"""
if isinstance(node.func, ast.Attribute) and isinstance(
node.func.value, ast.Name
):
allowed = _CLI_RUNNER_MODULE_ATTRS.get(node.func.value.id)
return allowed is not None and node.func.attr in allowed
if isinstance(node.func, ast.Name):
return node.func.id in _CLI_RUNNER_DIRECT_NAMES
return False
def _lint_workflow_script(
script_path: str,
rel_script: str,
declared_args: Set[str] | None,
has_safe_dry_run: bool,
) -> Sequence[Finding]:
"""Lints a dynamic workflow Python entry script using AST inspection.
Checks syntax, call_tool() allowlist, agent(workspace=, model=) literals,
args.get() / args[...] key sync against workflow.json, and unguarded
external mutation commands.
Args:
script_path: Absolute path to workflow.py (or custom entry script).
rel_script: Repository-relative path for findings.
declared_args: Set of argument names declared in workflow.json, or None.
has_safe_dry_run: Whether workflow.json declares dry_run defaulting to
True.
Returns:
A sequence of Finding dicts.
"""
findings: list[Finding] = []
try:
with open(script_path, "r", encoding="utf-8") as f:
source = f.read()
except OSError as e:
findings.append(
Finding(
filepath=rel_script,
line=1,
level="error",
message=f"Could not read workflow entry script: {e}",
)
)
return tuple(findings)
try:
tree = ast.parse(source, filename=rel_script)
except SyntaxError as e:
findings.append(
Finding(
filepath=rel_script,
line=e.lineno if e.lineno is not None else 1,
level="error",
message=f"Python syntax error in workflow script: {e.msg}",
)
)
return tuple(findings)
var_cmds: dict[str, str] = {}
for node in ast.walk(tree):
if isinstance(node, ast.Assign) and node.value is not None:
text = _extract_cmd_expr_text(node.value, var_cmds)
if text:
for target in node.targets:
if isinstance(target, ast.Name):
prev = var_cmds.get(target.id)
var_cmds[target.id] = (
f"{prev} {text}" if prev is not None else text
)
elif (
isinstance(node, ast.AnnAssign)
and isinstance(node.target, ast.Name)
and node.value is not None
):
text = _extract_cmd_expr_text(node.value, var_cmds)
if text:
prev = var_cmds.get(node.target.id)
var_cmds[node.target.id] = (
f"{prev} {text}" if prev is not None else text
)
used_args: dict[str, int] = {}
mutation_lineno: int | None = None
for node in ast.walk(tree):
# Detect args["key"] subscript access.
if (
isinstance(node, ast.Subscript)
and isinstance(node.value, ast.Name)
and node.value.id == "args"
and isinstance(node.slice, ast.Constant)
and isinstance(node.slice.value, str)
):
used_args.setdefault(node.slice.value, node.lineno)
if not isinstance(node, ast.Call):
continue
# Detect external mutation commands passed to subprocess/CLI runners.
if mutation_lineno is None and _is_cli_runner_call(node):
arg_texts = tuple(
t
for a in node.args
if (t := _extract_cmd_expr_text(a, var_cmds))
)
candidates = list(arg_texts)
if len(arg_texts) > 1:
candidates.append(" ".join(arg_texts))
for kw in node.keywords:
if kw.arg in ("args", "cmd"):
kw_text = _extract_cmd_expr_text(kw.value, var_cmds)
if kw_text:
candidates.append(kw_text)
if any(_MUTATION_CMD_RE.search(cand) for cand in candidates):
mutation_lineno = node.lineno
# Detect args.get("key", ...).
if (
isinstance(node.func, ast.Attribute)
and isinstance(node.func.value, ast.Name)
and node.func.value.id == "args"
and node.func.attr == "get"
and node.args
and isinstance(node.args[0], ast.Constant)
and isinstance(node.args[0].value, str)
):
used_args.setdefault(node.args[0].value, node.lineno)
# Detect call_tool("<tool>", ...).
if isinstance(node.func, ast.Name) and node.func.id == "call_tool":
if (
node.args
and isinstance(node.args[0], ast.Constant)
and isinstance(node.args[0].value, str)
):
tool_name = node.args[0].value
if tool_name not in _ALLOWED_CALL_TOOLS:
allowed_str = ", ".join(sorted(_ALLOWED_CALL_TOOLS))
findings.append(
Finding(
filepath=rel_script,
line=node.lineno,
level="error",
message=(
f'call_tool("{tool_name}", ...) is disallowed'
" in run_workflow and raises ToolError."
f" Allowed tools: {allowed_str}."
),
)
)
# Detect agent(..., workspace="...", model="...").
if isinstance(node.func, ast.Name) and node.func.id == "agent":
for kw in node.keywords:
allowed = (
_AGENT_KW_ALLOWED.get(kw.arg)
if kw.arg is not None
else None
)
if (
allowed is not None
and isinstance(kw.value, ast.Constant)
and isinstance(kw.value.value, str)
and kw.value.value not in allowed
):
allowed_str = ", ".join(sorted(allowed))
findings.append(
Finding(
filepath=rel_script,
line=kw.lineno,
level="error",
message=(
f'Invalid agent {kw.arg}="{kw.value.value}".'
f" Allowed values: {allowed_str}."
),
)
)
if used_args:
if declared_args is None:
first_key, first_line = next(iter(used_args.items()))
findings.append(
Finding(
filepath=rel_script,
line=first_line,
level="warning",
message=(
f'Workflow reads args["{first_key}"], but'
' workflow.json does not define an "args" schema.'
),
)
)
else:
for key, lineno in sorted(
used_args.items(), key=lambda item: item[1]
):
if key not in declared_args:
findings.append(
Finding(
filepath=rel_script,
line=lineno,
level="warning",
message=(
f'Argument "{key}" read from args in'
" workflow.py is not declared in workflow.json"
' "args.properties".'
),
)
)
if mutation_lineno is not None and not has_safe_dry_run:
findings.append(
Finding(
filepath=rel_script,
line=mutation_lineno,
level="warning",
message=(
"Workflow invokes external mutation commands via Python"
" (which bypasses Jetski's per-tool confirmation prompt)"
' without a "dry_run" boolean property defaulting to true'
" in workflow.json."
),
)
)
return tuple(findings)
def _lint_workflow_dir(
workflow_dir: str,
repo_root: str | None,
fuchsia_root: str | None,
) -> Sequence[Finding]:
"""Lints a saved dynamic workflow directory (.agents/workflows/<name>/).
Validates workflow.json manifest schema, entry script AST rules, argument
synchronization, and optional README.md anti-patterns.
Args:
workflow_dir: Path to the workflow directory.
repo_root: Optional SCM repository root.
fuchsia_root: Optional Fuchsia checkout root.
Returns:
A sequence of Finding dicts across files in the workflow directory.
"""
findings: list[Finding] = []
abs_dir = os.path.abspath(workflow_dir)
dir_name = os.path.basename(abs_dir)
manifest_path = os.path.join(abs_dir, "workflow.json")
rel_manifest = _rel_filepath(manifest_path, repo_root)
if not os.path.isfile(manifest_path):
try:
rem_entries = tuple(os.listdir(abs_dir))
except OSError as e:
return (
Finding(
filepath=_rel_filepath(abs_dir, repo_root),
line=1,
level="error",
message=f"Could not read workflow directory: {e}",
),
)
if all(e.startswith(".") or e == "__pycache__" for e in rem_entries):
return ()
findings.append(
Finding(
filepath=_rel_filepath(abs_dir, repo_root),
line=1,
level="error",
message=(
f'Saved workflow directory "{dir_name}" is missing required'
' "workflow.json" manifest.'
),
)
)
return tuple(findings)
try:
with open(manifest_path, "r", encoding="utf-8") as f:
manifest = json.load(f)
except (OSError, json.JSONDecodeError) as e:
findings.append(
Finding(
filepath=rel_manifest,
line=1,
level="error",
message=f"Invalid JSON in workflow.json: {e}",
)
)
return tuple(findings)
if not isinstance(manifest, dict):
findings.append(
Finding(
filepath=rel_manifest,
line=1,
level="error",
message="workflow.json root must be a JSON object.",
)
)
return tuple(findings)
unknown_keys = set(manifest.keys()) - _ALLOWED_WORKFLOW_MANIFEST_KEYS
if unknown_keys:
findings.append(
Finding(
filepath=rel_manifest,
line=1,
level="error",
message=(
"Unexpected key(s) in workflow.json: "
+ ", ".join(sorted(unknown_keys))
+ ". Allowed keys: "
+ ", ".join(sorted(_ALLOWED_WORKFLOW_MANIFEST_KEYS))
+ "."
),
)
)
raw_name = manifest.get("name")
wf_name = raw_name.strip() if isinstance(raw_name, str) else ""
if not wf_name or not re.fullmatch(r"^[a-z0-9-]+$", wf_name):
findings.append(
Finding(
filepath=rel_manifest,
line=1,
level="error",
message=(
'workflow.json "name" must be a non-empty kebab-case'
" string ([a-z0-9-])."
),
)
)
elif wf_name != dir_name and not dir_name.startswith("tmp"):
findings.append(
Finding(
filepath=rel_manifest,
line=1,
level="error",
message=(
f'workflow.json name "{wf_name}" must match enclosing'
f' directory "{dir_name}".'
),
)
)
raw_library = manifest.get("library", False)
if not isinstance(raw_library, bool):
findings.append(
Finding(
filepath=rel_manifest,
line=1,
level="error",
message='workflow.json "library" must be a boolean.',
)
)
is_library = False
else:
is_library = raw_library
raw_desc = manifest.get("description")
desc = raw_desc.strip() if isinstance(raw_desc, str) else ""
if not desc:
findings.append(
Finding(
filepath=rel_manifest,
line=1,
level="error",
message=(
'workflow.json "description" cannot be empty (it is the'
" only workflow summary injected into agent context)."
),
)
)
declared_args: Set[str] | None
if "args" in manifest:
declared_args, has_safe_dry_run, arg_findings = _validate_args_schema(
manifest["args"], rel_manifest
)
findings.extend(arg_findings)
else:
declared_args = None
has_safe_dry_run = False
if not is_library:
if "entry" in manifest:
raw_entry_val = manifest["entry"]
raw_entry = (
raw_entry_val.strip() if isinstance(raw_entry_val, str) else ""
)
else:
raw_entry = "workflow.py"
norm_entry = os.path.normpath(raw_entry) if raw_entry else ""
if not raw_entry:
findings.append(
Finding(
filepath=rel_manifest,
line=1,
level="error",
message='workflow.json "entry" must be a non-empty string.',
)
)
elif (
os.path.isabs(raw_entry)
or norm_entry == ".."
or norm_entry.startswith(f"..{os.sep}")
or norm_entry.startswith("../")
):
findings.append(
Finding(
filepath=rel_manifest,
line=1,
level="error",
message=(
f'workflow.json entry "{raw_entry}" must stay inside'
" the workflow directory."
),
)
)
else:
entry_abs = os.path.join(abs_dir, norm_entry)
if not os.path.isfile(entry_abs):
findings.append(
Finding(
filepath=rel_manifest,
line=1,
level="error",
message=(
f'Workflow entry script "{raw_entry}" does not'
" exist."
),
)
)
elif entry_abs.endswith(".py"):
findings.extend(
_lint_workflow_script(
entry_abs,
_rel_filepath(entry_abs, repo_root),
declared_args,
has_safe_dry_run,
)
)
readme_path = os.path.join(abs_dir, "README.md")
if os.path.isfile(readme_path):
rel_readme = _rel_filepath(readme_path, repo_root)
try:
with open(readme_path, "r", encoding="utf-8") as f:
readme_lines = f.read().splitlines()
except OSError as e:
findings.append(
Finding(
filepath=rel_readme,
line=1,
level="error",
message=f"Could not read workflow README.md: {e}",
)
)
return tuple(findings)
for idx, line in enumerate(readme_lines, start=1):
if _ARG_TABLE_HEADER_RE.match(line.strip()):
findings.append(
Finding(
filepath=rel_readme,
line=idx,
level="warning",
message=(
"Workflow README.md duplicates the arguments schema"
" table (agents only see workflow.json, so README"
" argument tables drift). Put argument details in"
" workflow.json instead."
),
)
)
break
if wf_name:
for idx, line in enumerate(readme_lines, start=1):
if re.search(rf"/run-workflow\s+{re.escape(wf_name)}\b", line):
findings.append(
Finding(
filepath=rel_readme,
line=idx,
level="warning",
message=(
f'Saved workflow "{wf_name}" exposes the'
f' "/{wf_name}" slash command directly rather'
f' than "/run-workflow {wf_name}".'
),
)
)
break
findings.extend(
_check_markdown_links_and_snippets(
readme_path,
rel_readme,
readme_lines,
1,
repo_root,
fuchsia_root,
)
)
return tuple(findings)
def _lint_discovery_json(
json_path: str,
repo_root: str | None,
fuchsia_root: str | None,
) -> Sequence[Finding]:
"""Lints a Jetski JSON discovery config (.agents/{skills,workflows,...}.json).
Validates allowed keys, entry structure, local path existence, and dual
path registration in vendor/google/.agents/{skills,workflows}.json.
Args:
json_path: Path to the JSON configuration file.
repo_root: Optional SCM repository root.
fuchsia_root: Optional Fuchsia checkout root.
Returns:
A sequence of Finding dicts.
"""
findings: list[Finding] = []
abs_json = os.path.abspath(json_path)
rel_json = _rel_filepath(abs_json, repo_root)
# Relative paths in .agents/*.json resolve against the parent of .agents/
# first, falling back to repo_root / fuchsia_root.
dot_dir = os.path.dirname(abs_json)
config_base = (
os.path.dirname(dot_dir)
if os.path.basename(dot_dir) in (".agents", "_agents")
else dot_dir
)
try:
with open(abs_json, "r", encoding="utf-8") as f:
data = json.load(f)
except (OSError, json.JSONDecodeError) as e:
findings.append(
Finding(
filepath=rel_json,
line=1,
level="error",
message=f"Invalid JSON in discovery config: {e}",
)
)
return tuple(findings)
if not isinstance(data, dict):
findings.append(
Finding(
filepath=rel_json,
line=1,
level="error",
message="Discovery config root must be a JSON object.",
)
)
return tuple(findings)
unknown = set(data.keys()) - _ALLOWED_DISCOVERY_CONFIG_KEYS
if unknown:
findings.append(
Finding(
filepath=rel_json,
line=1,
level="error",
message=(
"Unexpected top-level key(s) in discovery config: "
+ ", ".join(sorted(unknown))
+ "."
),
)
)
entry_paths: list[str] = []
for section in ("entries", "inherits"):
if section not in data:
continue
items = data[section]
if not isinstance(items, list):
findings.append(
Finding(
filepath=rel_json,
line=1,
level="error",
message=f'"{section}" must be an array of objects.',
)
)
continue
for item in items:
if not isinstance(item, dict) or not isinstance(
item.get("path"), str
):
findings.append(
Finding(
filepath=rel_json,
line=1,
level="error",
message=(
f'Each item in "{section}" must be an object with a'
' string "path" field.'
),
)
)
continue
p = item["path"].strip()
if not p:
findings.append(
Finding(
filepath=rel_json,
line=1,
level="error",
message=f'Empty "path" in "{section}".',
)
)
continue
if section == "entries":
entry_paths.append(p)
if p.startswith(("~", "/google/", "google3/", "configs/")):
continue
norm_p = p.replace("\\", "/").lstrip("/")
if norm_p.startswith("vendor/"):
p_parts = norm_p.split("/")
vendor_rel = (
os.path.join(p_parts[0], p_parts[1])
if len(p_parts) >= 2
else p_parts[0]
)
search_roots = (
config_base,
*(
os.path.abspath(r)
for r in (repo_root, fuchsia_root)
if r is not None
),
)
if not any(
os.path.isdir(os.path.join(r, vendor_rel))
for r in search_roots
):
continue
if not _resolve_local_target(
p, config_base, repo_root, fuchsia_root
):
findings.append(
Finding(
filepath=rel_json,
line=1,
level="error",
message=(
f'Configured {section} path "{p}" does not exist in'
" the checkout."
),
)
)
# Check vendor/google dual-path convention when inherited by //.agents/.
norm_abs = abs_json.replace(os.sep, "/")
if norm_abs.endswith(
(
"/vendor/google/.agents/skills.json",
"/vendor/google/.agents/workflows.json",
)
):
entry_set = frozenset(entry_paths)
for p in entry_paths:
if p in (".", "..") or p.startswith(
(
"./",
"../",
"/",
"~",
"vendor/google/",
"google3/",
"configs/",
)
):
continue
paired = f"vendor/google/{p}"
if paired not in entry_set:
findings.append(
Finding(
filepath=rel_json,
line=1,
level="warning",
message=(
f'Entry "{p}" in vendor/google discovery config is'
f' missing paired "{paired}" entry needed when'
" inherited from the Fuchsia checkout root."
),
)
)
return tuple(findings)
def _find_enclosing_workflow_dir(path: str) -> str | None:
"""Finds the enclosing saved workflow directory for a file path, if any.
Args:
path: File or directory path.
Returns:
Absolute path to the workflow directory (<root>/.agents/workflows/<name>
or a directory containing workflow.json), or None.
"""
abs_path = os.path.abspath(path)
cur = os.path.dirname(abs_path) if os.path.isfile(abs_path) else abs_path
if os.path.isfile(os.path.join(cur, "workflow.json")):
return cur
parts = cur.split(os.sep)
for idx in range(len(parts) - 2):
if (
parts[idx] in (".agents", "_agents")
and parts[idx + 1] == "workflows"
):
return os.sep.join(parts[: idx + 3])
return None
def _lint_customization_paths(
paths: Collection[str],
repo_root: str | None,
fuchsia_root: str | None,
) -> Sequence[Finding]:
"""Runs semantic and structural lint rules across skills, workflows, and JSON configs.
Args:
paths: Collection of file or directory paths to lint.
repo_root: Optional SCM repository root for relative path reporting.
fuchsia_root: Optional Fuchsia checkout root for cross-repo path
resolution.
Returns:
A sequence of Finding dicts.
"""
findings: list[Finding] = []
seen_skills: set[str] = set()
seen_workflows: set[str] = set()
seen_jsons: set[str] = set()
for raw_path in paths:
abs_p = os.path.abspath(raw_path)
wf_dir = _find_enclosing_workflow_dir(abs_p)
if wf_dir is not None:
if wf_dir not in seen_workflows and os.path.isdir(wf_dir):
seen_workflows.add(wf_dir)
findings.extend(
_lint_workflow_dir(wf_dir, repo_root, fuchsia_root)
)
continue
if os.path.isfile(abs_p):
base = os.path.basename(abs_p)
parent_base = os.path.basename(os.path.dirname(abs_p))
if base == "SKILL.md" and abs_p not in seen_skills:
seen_skills.add(abs_p)
findings.extend(
_lint_skill_semantic(abs_p, repo_root, fuchsia_root)
)
elif (
base in _DISCOVERY_JSON_FILENAMES
and parent_base in (".agents", "_agents")
and abs_p not in seen_jsons
):
seen_jsons.add(abs_p)
findings.extend(
_lint_discovery_json(abs_p, repo_root, fuchsia_root)
)
elif os.path.isdir(abs_p):
skill_md = os.path.join(abs_p, "SKILL.md")
if os.path.isfile(skill_md):
if skill_md not in seen_skills:
seen_skills.add(skill_md)
findings.extend(
_lint_skill_semantic(skill_md, repo_root, fuchsia_root)
)
else:
try:
entries = sorted(os.listdir(abs_p))
except OSError as e:
findings.append(
Finding(
filepath=_rel_filepath(abs_p, repo_root),
line=1,
level="error",
message=f"Could not read directory '{abs_p}': {e}",
)
)
continue
for entry in entries:
subdir = os.path.join(abs_p, entry)
if not os.path.isdir(subdir):
continue
sub_wf = _find_enclosing_workflow_dir(subdir)
if sub_wf is not None:
if sub_wf not in seen_workflows and os.path.isdir(
sub_wf
):
seen_workflows.add(sub_wf)
findings.extend(
_lint_workflow_dir(
sub_wf, repo_root, fuchsia_root
)
)
continue
sub_skill = os.path.join(subdir, "SKILL.md")
if (
os.path.isfile(sub_skill)
and sub_skill not in seen_skills
):
seen_skills.add(sub_skill)
findings.extend(
_lint_skill_semantic(
sub_skill, repo_root, fuchsia_root
)
)
return tuple(findings)
def do_lint(
root_path: str,
fixit: bool,
stdout_mode: bool,
suggest_fix_in_json_mode: bool = False,
) -> tuple[int, list[Finding]]:
"""Orchestrates the formatting/metadata linting process for a file or directory.
Args:
root_path: Path to a file or directory to lint.
fixit: Whether to apply fixes in-place.
stdout_mode: Whether to output fixed content to stdout.
suggest_fix_in_json_mode: Whether to return findings as JSON.
Returns:
A tuple of (max_exit_code, all_findings).
"""
if os.path.isfile(root_path):
return lint_single_skill(
root_path, fixit, stdout_mode, suggest_fix_in_json_mode
)
elif os.path.exists(os.path.join(root_path, "SKILL.md")):
return lint_single_skill(
os.path.join(root_path, "SKILL.md"),
fixit,
stdout_mode,
suggest_fix_in_json_mode,
)
else:
all_findings: list[Finding] = []
try:
subdirs = [
os.path.join(root_path, d)
for d in os.listdir(root_path)
if os.path.isdir(os.path.join(root_path, d))
]
except OSError as e:
msg = f"Error reading directory '{root_path}': {e}"
if suggest_fix_in_json_mode:
all_findings.append(
Finding(
filepath=os.path.relpath(root_path),
message=msg,
level="error",
)
)
else:
logging.error(msg)
return 0 if suggest_fix_in_json_mode else 1, all_findings
max_code = 0
for subdir in subdirs:
if os.path.exists(os.path.join(subdir, "SKILL.md")):
code, findings = lint_single_skill(
os.path.join(subdir, "SKILL.md"),
fixit,
stdout_mode,
suggest_fix_in_json_mode,
)
all_findings.extend(findings)
max_code = max(max_code, code)
return max_code, all_findings
def main() -> None:
"""Main entry point for the skill and workflow linter.
Parses command line arguments, configures logging, and runs the
linting process on specified paths.
"""
parser = argparse.ArgumentParser(
description="Skill, dynamic workflow, and .agents config validator."
)
parser.add_argument(
"--fixit",
action="store_true",
help="Suggest and autofix validation errors.",
)
parser.add_argument(
"--suggest-fix",
action="store_true",
help="Applies fixes and outputs the result directly to stdout.",
)
parser.add_argument(
"--suggest-fix-in-json",
action="store_true",
help="Output formatting and frontmatter findings as a JSON array.",
)
parser.add_argument(
"--lint-json",
action="store_true",
help=(
"Run semantic skill, workflow, and .agents JSON lint checks and"
" output findings as a JSON array."
),
)
parser.add_argument(
"--strict",
action="store_true",
help=(
"Also run semantic skill, workflow, and .agents JSON lint checks"
" in CLI mode."
),
)
parser.add_argument(
"--repo-root",
default=None,
help="SCM repository root for relative paths and link resolution.",
)
parser.add_argument(
"--fuchsia-root",
default=None,
help="Fuchsia checkout root for cross-repository path resolution.",
)
parser.add_argument(
"paths",
nargs="+",
help="Paths to SKILL.md, workflow, or .agents config files/directories.",
)
args = parser.parse_args()
logging.basicConfig(
level=logging.INFO,
format="%(message)s",
stream=sys.stderr,
)
if args.lint_json:
lint_findings = _lint_customization_paths(
args.paths,
repo_root=args.repo_root,
fuchsia_root=args.fuchsia_root,
)
print(json.dumps(lint_findings, indent=2))
sys.exit(0)
all_findings = []
any_error = False
for path in args.paths:
if (
args.strict
and os.path.isfile(path)
and os.path.basename(path) != "SKILL.md"
):
continue
code, findings = do_lint(
path,
args.fixit or args.suggest_fix,
args.suggest_fix,
args.suggest_fix_in_json,
)
all_findings.extend(findings)
if code != 0:
any_error = True
if args.strict and not args.suggest_fix and not args.suggest_fix_in_json:
semantic_findings = _lint_customization_paths(
args.paths,
repo_root=args.repo_root,
fuchsia_root=args.fuchsia_root,
)
for fd in semantic_findings:
loc = f"{fd['filepath']}:{fd.get('line', 1)}"
if fd["level"] == "error":
logging.error(f"[{loc}] Error: {fd['message']}")
any_error = True
else:
logging.warning(f"[{loc}] Warning: {fd['message']}")
if args.suggest_fix_in_json:
print(json.dumps(all_findings, indent=2))
sys.exit(1 if any_error else 0)
if __name__ == "__main__":
main()