feat: allow --lenient to scan skills without SKILL.md (#63)

* feat: allow --lenient to scan skills without SKILL.md and fix jq pipe false positive

When --lenient is set and SKILL.md is absent, the loader now falls back to
scanning .md files in the directory as instruction bodies. This enables
scanning non-Codex/Cursor skill formats (Claude Code commands, flat markdown
repos) without requiring a shim.

Also adds --skill-file flag for specifying a custom metadata filename, updates
scan-all discovery to find .md-containing directories in lenient mode, and
fixes the pipeline taint analyzer splitting pipes inside quoted strings (e.g.
jq '.events[] | {source}' was incorrectly flagged as a bash source invocation).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: update documentation for --lenient fallback, --skill-file, and jq fix

Update README, quick-start, CLI usage, CLI reference, scanning pipeline,
Python SDK, and FEATURE.md to document:
- --lenient now falls back to .md files when SKILL.md is absent
- New --skill-file flag for custom metadata filenames
- Quote-aware pipe splitting in the pipeline analyzer

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Vineeth Sai Narajala <vnarajal@cisco.com>

Author: 3 people

FEATURE.md

@@ -75,6 +75,7 @@ Post-processing includes:
 ### 3. Pipeline Analyzer
 
 - Parses shell command pipelines and classifies risk
+- Quote-aware pipe splitting (avoids false positives on `jq` expressions and other quoted `|` characters)
 - Detects fetch-and-execute and sensitive source-to-sink chains
 - Uses `command_safety`, `pipeline`, and `sensitive_files` policy knobs
 
@@ -165,6 +166,7 @@ Implemented in `skill_scanner/core/scan_policy.py` with built-ins in `skill_scan
 - VirusTotal/AI Defense keys: `--vt-api-key`, `--aidefense-api-key`, `--aidefense-api-url`
 - Output: `--format`, `--output`, `--detailed`, `--compact`, `--fail-on-findings`, `--fail-on-severity`
 - Multi-skill: `--recursive`, `--check-overlap`
+- Flexibility: `--lenient` (scan without `SKILL.md`), `--skill-file` (custom metadata filename)
 
 ## API Server Features
 

README.md

@@ -13,7 +13,7 @@ A best-effort security scanner for AI Agent Skills that detects prompt injection
 
 > **Important:** This scanner provides best-effort detection, not comprehensive or complete coverage. A scan that returns no findings does not guarantee that a skill is free of all threats. See [Scope and Limitations](#scope-and-limitations) below.
 
-Supports [OpenAI Codex Skills](https://openai.github.io/codex/) and [Cursor Agent Skills](https://docs.cursor.com/context/rules) formats following the [Agent Skills specification](https://agentskills.io).
+Supports [OpenAI Codex Skills](https://openai.github.io/codex/) and [Cursor Agent Skills](https://docs.cursor.com/context/rules) formats following the [Agent Skills specification](https://agentskills.io). With `--lenient`, also scans non-standard formats such as Claude Code `.claude/commands/*.md` and flat markdown skill repos.
 
 ---
 
@@ -154,6 +154,13 @@ skill-scanner scan-all /path/to/skills --recursive --check-overlap
 skill-scanner scan /path/to/skill --lenient
 skill-scanner scan-all /path/to/skills --recursive --lenient
 
+# Lenient mode with non-standard skill formats (no SKILL.md required)
+skill-scanner scan .claude/commands/deploy --lenient
+skill-scanner scan-all .claude/commands --recursive --lenient
+
+# Use a custom metadata filename instead of SKILL.md
+skill-scanner scan /path/to/skill --skill-file README.md
+
 # CI/CD: Fail build if threats found
 skill-scanner scan-all ./skills --fail-on-severity high --format sarif --output results.sarif
 
@@ -252,7 +259,8 @@ if not result.is_safe:
 | `--custom-rules PATH` | Use custom YARA rules from directory |
 | `--taxonomy PATH` | Load custom taxonomy profile (JSON/YAML) for this run |
 | `--threat-mapping PATH` | Load custom scanner threat mapping profile (JSON) for this run |
-| `--lenient` | Tolerate malformed skills (coerce bad fields, fill defaults) instead of failing |
+| `--lenient` | Tolerate malformed skills (coerce bad fields, fill defaults) instead of failing. When `SKILL.md` is absent, falls back to scanning `.md` files in the directory |
+| `--skill-file FILENAME` | Custom metadata filename to use instead of `SKILL.md` (e.g. `README.md`) |
 | `--check-overlap` | (`scan-all`) Enable cross-skill description overlap checks |
 
 | Command | Description |

docs/architecture/scanning-pipeline.md

@@ -58,7 +58,8 @@ flowchart TD
 ## Stage 1: Load and Pre-process
 
 1. **Load skill package** via `SkillLoader`:
-   - Validate skill directory and `SKILL.md`
+   - Validate skill directory and locate metadata file (`SKILL.md` by default, or `--skill-file`)
+   - When `--lenient` is set and no `SKILL.md` exists, fall back to scanning `.md` files in the directory as instruction bodies (supports non-Codex/Cursor formats such as Claude Code commands)
    - Parse frontmatter (name, description, metadata)
    - Discover files recursively (excluding `.git` internals)
    - Classify file types (python, bash, markdown, binary, other)

docs/getting-started/quick-start.md

@@ -200,11 +200,17 @@ skill-scanner scan-all /path/to/skills --check-overlap
 
 ### Lenient Mode
 
-Tolerate malformed skills (missing fields, non-string descriptions) instead of failing:
+Tolerate malformed skills (missing fields, non-string descriptions) instead of failing. When `SKILL.md` is absent, lenient mode falls back to scanning `.md` files in the directory as instruction bodies — enabling support for non-Codex/Cursor formats such as Claude Code `.claude/commands/*.md`:
 
 ```bash
 skill-scanner scan /path/to/skill --lenient
 skill-scanner scan-all /path/to/skills --recursive --lenient
+
+# Scan a Claude Code commands directory (no SKILL.md)
+skill-scanner scan .claude/commands/deploy --lenient
+
+# Use a custom metadata filename instead of SKILL.md
+skill-scanner scan /path/to/skill --skill-file README.md
 ```
 
 ### Pre-commit Hook

docs/reference/cli-command-reference.md

@@ -35,7 +35,8 @@ Flags shared by `scan` and `scan-all`:
 | `--enable-meta` | off | Enable the meta (cross-correlation) analyzer |
 | `--fail-on-findings` | off | Exit non-zero if critical or high findings are reported; equivalent to `--fail-on-severity high` (CI gate) |
 | `--fail-on-severity LEVEL` | off | Exit non-zero if findings at or above LEVEL exist (critical, high, medium, low, info) |
-| `--lenient` | off | Tolerate malformed skills: coerce bad fields, fill defaults, and continue instead of failing |
+| `--lenient` | off | Tolerate malformed skills: coerce bad fields, fill defaults, and continue instead of failing. When `SKILL.md` is absent, falls back to scanning `.md` files in the directory |
+| `--skill-file FILENAME` | `SKILL.md` | Custom metadata filename to use instead of `SKILL.md` |
 | `--detailed` | off | Include full evidence in output |
 | `--compact` | off | Minimize output (JSON: no pretty-print) |
 | `--verbose` | off | Verbose logging |

docs/user-guide/cli-usage.md

@@ -59,6 +59,21 @@ skill-scanner scan ./my-skill --policy strict
 skill-scanner scan ./my-skill --policy ./my-org-policy.yaml
 ```
 
+### Scanning non-standard skill formats
+
+Use `--lenient` to scan skills that don't follow the Codex/Cursor `SKILL.md` convention (e.g. Claude Code `.claude/commands/*.md`):
+
+```bash
+# Scan a directory with .md files but no SKILL.md
+skill-scanner scan .claude/commands/deploy --lenient
+
+# Discover all .md-containing directories under a path
+skill-scanner scan-all .claude/commands --recursive --lenient
+
+# Use a custom metadata file instead of SKILL.md
+skill-scanner scan ./my-skill --skill-file README.md
+```
+
 ## Choosing Analyzers
 
 Not sure which flags to use? Pick the row that matches your situation:

docs/user-guide/python-sdk.md

@@ -32,22 +32,31 @@ When `analyzers` is `None`, the scanner builds the default core analyzer set (st
 
 ## Instance Methods
 
-### `scan_skill(skill_directory, *, lenient=False) → ScanResult`
+### `scan_skill(skill_directory, *, lenient=False, skill_file=None) → ScanResult`
 
-Scan a single skill package directory. Pass `lenient=True` to coerce malformed manifests instead of raising an error.
+Scan a single skill package directory. Pass `lenient=True` to coerce malformed manifests instead of raising an error. When `lenient=True` and no `SKILL.md` exists, the loader falls back to scanning `.md` files in the directory. Pass `skill_file` to use a custom metadata filename (e.g. `"README.md"`).
 
 ```python
 result = scanner.scan_skill("/path/to/skill")
+
+# Scan a directory without SKILL.md (e.g. Claude Code commands)
+result = scanner.scan_skill(".claude/commands/deploy", lenient=True)
+
+# Use a custom metadata file
+result = scanner.scan_skill("/path/to/skill", skill_file="README.md")
 ```
 
-### `scan_directory(skills_directory, recursive=False, check_overlap=False, *, lenient=False) → Report`
+### `scan_directory(skills_directory, recursive=False, check_overlap=False, *, lenient=False, skill_file=None) → Report`
 
-Scan all skill packages in a directory.
+Scan all skill packages in a directory. When `lenient=True`, directories containing `.md` files (but no `SKILL.md`) are also discovered as candidate skills.
 
 ```python
 report = scanner.scan_directory("/path/to/skills", recursive=True)
 print(report.total_skills_scanned)
 print(report.total_findings)
+
+# Discover and scan non-standard skill formats
+report = scanner.scan_directory(".claude/commands", recursive=True, lenient=True)
 ```
 
 ### `add_analyzer(analyzer)`

skill_scanner/cli/cli.py

@@ -350,9 +350,10 @@ def scan_command(args: argparse.Namespace) -> int:
 
     scanner = SkillScanner(analyzers=analyzers, policy=policy)
     lenient = getattr(args, "lenient", False)
+    skill_file = getattr(args, "skill_file", None)
 
     try:
-        result = scanner.scan_skill(skill_dir, lenient=lenient)
+        result = scanner.scan_skill(skill_dir, lenient=lenient, skill_file=skill_file)
 
         # Meta-analysis
         if meta_analyzer and result.findings and apply_meta_analysis_to_results is not None:
@@ -437,11 +438,16 @@ def scan_all_command(args: argparse.Namespace) -> int:
     scanner = SkillScanner(analyzers=analyzers, policy=policy)
 
     lenient = getattr(args, "lenient", False)
+    skill_file = getattr(args, "skill_file", None)
 
     try:
         check_overlap = getattr(args, "check_overlap", False)
         report = scanner.scan_directory(
-            skills_dir, recursive=args.recursive, check_overlap=check_overlap, lenient=lenient
+            skills_dir,
+            recursive=args.recursive,
+            check_overlap=check_overlap,
+            lenient=lenient,
+            skill_file=skill_file,
         )
 
         if report.total_skills_scanned == 0:
@@ -769,7 +775,16 @@ def _add_common_scan_flags(parser: argparse.ArgumentParser) -> None:
     parser.add_argument(
         "--lenient",
         action="store_true",
-        help="Tolerate malformed skills: coerce bad fields, fill defaults, and continue instead of failing",
+        help=(
+            "Tolerate malformed skills: coerce bad fields, fill defaults, and continue instead of failing. "
+            "When SKILL.md is absent, falls back to scanning .md files in the directory as instruction bodies "
+            "(supports non-Codex/Cursor formats such as Claude Code commands)."
+        ),
+    )
+    parser.add_argument(
+        "--skill-file",
+        metavar="FILENAME",
+        help="Custom metadata filename to use instead of SKILL.md (e.g. README.md)",
     )
     parser.add_argument(
         "--custom-rules",

skill_scanner/core/analyzers/pipeline_analyzer.py

@@ -249,10 +249,51 @@ def _extract_pipelines(self, content: str, source_file: str) -> list[PipelineCha
 
         return pipelines
 
+    @staticmethod
+    def _split_pipeline(raw: str) -> list[str]:
+        """Split a pipeline string by ``|`` while respecting quotes.
+
+        Pipes inside single- or double-quoted strings (e.g. inside ``jq``
+        expressions) are **not** treated as shell pipe operators.
+        """
+        parts: list[str] = []
+        current: list[str] = []
+        in_single = False
+        in_double = False
+        i = 0
+        length = len(raw)
+        while i < length:
+            ch = raw[i]
+            if ch == "'" and not in_double:
+                in_single = not in_single
+                current.append(ch)
+            elif ch == '"' and not in_single:
+                in_double = not in_double
+                current.append(ch)
+            elif ch == "\\" and i + 1 < length:
+                current.append(ch)
+                current.append(raw[i + 1])
+                i += 1
+            elif ch == "|" and not in_single and not in_double:
+                # Ignore || (logical OR)
+                if i + 1 < length and raw[i + 1] == "|":
+                    current.append("||")
+                    i += 1
+                else:
+                    parts.append("".join(current).strip())
+                    current = []
+            else:
+                current.append(ch)
+            i += 1
+        remainder = "".join(current).strip()
+        if remainder:
+            parts.append(remainder)
+        return parts
+
     def _parse_pipeline(self, raw: str, source_file: str, line_number: int) -> PipelineChain | None:
         """Parse a pipeline string into a chain of CommandNodes."""
-        # Split by pipe, but not by ||
-        parts = re.split(r"\s*\|\s*(?!\|)", raw)
+        # Split by pipe, respecting quotes (fixes jq expression false positives)
+        parts = self._split_pipeline(raw)
         if len(parts) < 2:
             return None
 

skill_scanner/core/loader.py

@@ -56,14 +56,26 @@ def __init__(self, max_file_size_mb: int = 10, *, max_file_size_bytes: int | Non
         else:
             self.max_file_size_bytes = max_file_size_mb * 1024 * 1024
 
-    def load_skill(self, skill_directory: str | Path, *, lenient: bool = False) -> Skill:
+    def load_skill(
+        self,
+        skill_directory: str | Path,
+        *,
+        lenient: bool = False,
+        skill_file: str | None = None,
+    ) -> Skill:
         """
         Load a skill package from a directory.
 
         Args:
             skill_directory: Path to the skill directory
             lenient: When True, tolerate missing/malformed fields and return
                 a best-effort Skill instead of raising ``SkillLoadError``.
+                When ``SKILL.md`` is absent and *lenient* is True, the loader
+                falls back to scanning ``.md`` files in the directory as
+                instruction bodies (supports non-Codex/Cursor formats such as
+                Claude Code ``.claude/commands/*.md``).
+            skill_file: Optional custom metadata filename to use instead of
+                ``SKILL.md`` (e.g. ``"README.md"``).
 
         Returns:
             Parsed Skill object
@@ -80,14 +92,25 @@ def load_skill(self, skill_directory: str | Path, *, lenient: bool = False) -> S
         if not skill_directory.is_dir():
             raise SkillLoadError(f"Path is not a directory: {skill_directory}")
 
-        # Find SKILL.md
-        skill_md_path = skill_directory / "SKILL.md"
-        if not skill_md_path.exists():
+        # Find the skill metadata file
+        if skill_file:
+            skill_md_path = skill_directory / skill_file
+            if not skill_md_path.exists():
+                raise SkillLoadError(f"{skill_file} not found in {skill_directory}")
+        else:
+            skill_md_path = skill_directory / "SKILL.md"
+
+        if skill_md_path.exists():
+            # Standard path: parse the metadata file
+            manifest, instruction_body = self._parse_skill_md(skill_md_path, lenient=lenient)
+        elif lenient:
+            # Lenient fallback: no SKILL.md, synthesize from .md files in the directory
+            skill_md_path, manifest, instruction_body = self._synthesize_from_md_files(
+                skill_directory
+            )
+        else:
             raise SkillLoadError(f"SKILL.md not found in {skill_directory}")
 
-        # Parse SKILL.md
-        manifest, instruction_body = self._parse_skill_md(skill_md_path, lenient=lenient)
-
         # Discover all files in the skill package
         files = self._discover_files(skill_directory)
 
@@ -103,6 +126,60 @@ def load_skill(self, skill_directory: str | Path, *, lenient: bool = False) -> S
             referenced_files=referenced_files,
         )
 
+    def _synthesize_from_md_files(self, skill_directory: Path) -> tuple[Path, SkillManifest, str]:
+        """Synthesize a Skill from ``.md`` files when ``SKILL.md`` is absent.
+
+        Scans the directory for markdown files, concatenates their content as the
+        instruction body, and builds a best-effort manifest from the directory name.
+
+        Returns:
+            Tuple of (primary_md_path, SkillManifest, instruction_body)
+
+        Raises:
+            SkillLoadError: If no ``.md`` files are found in the directory.
+        """
+        md_files = sorted(skill_directory.glob("*.md"))
+        if not md_files:
+            raise SkillLoadError(
+                f"No SKILL.md and no .md files found in {skill_directory} "
+                f"(lenient mode requires at least one markdown file)"
+            )
+
+        logger.warning(
+            "SKILL.md not found in %s; falling back to %d .md file(s) (lenient mode)",
+            skill_directory,
+            len(md_files),
+        )
+
+        # Use the first .md file as the primary path
+        primary_md = md_files[0]
+
+        # Try to parse frontmatter from the primary file
+        try:
+            manifest, body = self._parse_skill_md(primary_md, lenient=True)
+        except SkillLoadError:
+            # If even lenient parsing fails, use raw content
+            try:
+                body = primary_md.read_text(encoding="utf-8")
+            except (OSError, UnicodeDecodeError):
+                body = ""
+            manifest = SkillManifest(
+                name=skill_directory.name,
+                description="(no description)",
+            )
+
+        # Append content from remaining .md files
+        extra_bodies: list[str] = []
+        for md_file in md_files[1:]:
+            try:
+                extra_bodies.append(md_file.read_text(encoding="utf-8"))
+            except (OSError, UnicodeDecodeError):
+                continue
+        if extra_bodies:
+            body = body + "\n\n" + "\n\n".join(extra_bodies)
+
+        return primary_md, manifest, body
+
     def _parse_skill_md(self, skill_md_path: Path, *, lenient: bool = False) -> tuple[SkillManifest, str]:
         """
         Parse SKILL.md file with YAML frontmatter.