sdd-full 4.6.2 → 4.8.0

package/skills/flutter-skills/tool/dart_skills_lint/documentation/feature_design_docs/completion_migration_plan.md

@@ -0,0 +1,99 @@
+# Migration Plan: Adding Zsh Command Autocompletion (Approach A)
+
+This document outlines the migration steps to add Zsh tab-autocompletion support to the `dart_skills_lint` CLI tool using Dart packages.
+
+There are two main sub-approaches depending on whether we want to keep the current flat `ArgParser` structure or migrate to a more structured `CommandRunner` architecture.
+
+---
+
+## 🧭 Option A.1: Migrate to `CommandRunner` with `cli_completion` (Recommended)
+
+If we plan to expand this CLI with subcommands in the future (e.g., `dart_skills_lint validate`, `dart_skills_lint init`, `dart_skills_lint check-ignore`), migrating to standard Dart `CommandRunner` is highly recommended.
+
+### 📜 Step-by-step
+1. **Add Dependency:**
+   ```bash
+   dart pub add cli_completion
+   ```
+2. **Refactor `entry_point.dart` to use `CompletionCommandRunner`:**
+   Create a custom runner and commands.
+   ```dart
+   import 'package:cli_completion/cli_completion.dart';
+
+   class SkillsLintRunner extends CompletionCommandRunner<int> {
+     SkillsLintRunner() : super('dart_skills_lint', 'Linter for Agent Skills');
+
+     @override
+     Future<int?> runCommand(ArgResults topLevelResults) async {
+       // Fast-track completions
+       if (topLevelResults.command?.name == 'completion') {
+         super.runCommand(topLevelResults);
+         return 0;
+       }
+       return super.runCommand(topLevelResults);
+     }
+   }
+   ```
+3. **Move existing flags into a `ValidateCommand`:**
+   Instead of top-level `ArgParser`, we encapsulate the validation logic inside a reusable Command class.
+   ```dart
+   class ValidateCommand extends Command<int> {
+     @override
+     String get name => 'validate';
+     @override
+     String get description => 'Validates agent skill directories.';
+
+     ValidateCommand() {
+       argParser..addFlag('quiet', negatable: false); // etc...
+     }
+
+     @override
+     Future<int> run() async {
+       // Run validation logic here
+       return 0;
+     }
+   }
+   ```
+4. **Update `bin/cli.dart`:**
+   Change `runApp(args)` to instantiate the new runner instead.
+
+---
+
+## ⚖️ Option A.2: Keep `ArgParser` and use `package:completion` (Simpler)
+
+If we want to keep the tool's monolithic, single-command design without introducing sub-commands, we can use the lightweight `package:completion`.
+
+### 📜 Step-by-step
+1. **Add Dependency:**
+   ```bash
+   dart pub add completion
+   ```
+2. **Update `lib/src/entry_point.dart` parser runner:**
+   Instead of `parser.parse(args)`, intercept the call to let the completion package proposal take precedence.
+   ```dart
+   import 'package:completion/completion.dart' as completion;
+
+   Future<void> runApp(List<String> args) async {
+     final parser = ArgParser();
+     // ... add your flags ...
+
+     // Intercept for completions
+     completion.tryArgsCompletion(args, parser); 
+
+     final results = parser.parse(args);
+     // ... rest of validation logic ...
+   }
+   ```
+
+---
+
+## 🧪 Verification Plan
+
+Regardless of the option chosen:
+
+### Automated Tests
+1. **Completion proposal test:** Verify that running `dart_skills_lint completion zsh` exits success code 0 and outputs setup instructions.
+2. **Regression tests:** Run standard suite checks (`test/cli_integration_test.dart`) to ensure normal runs are not disrupted by interjections.
+
+### Manual Verification
+1. Install completion script locally using standard terminal evaluation and tap tab on `-d` to ensure directories are displayed.

package/skills/flutter-skills/tool/dart_skills_lint/documentation/feature_design_docs/legacy_patterns_report.md

@@ -0,0 +1,110 @@
+# Feature Design Doc: Resolving Legacy Inconsistencies in Rule Resolution
+
+This document analyzes patterns of code where legacy implementations create inconsistencies, specifically around rule resolution, configuration overrides, and global state management.
+
+## Identified Inconsistencies
+
+### 1. Mutable Global State in `CheckType`
+
+The `CheckType` objects defined in `lib/src/rules.dart` behave as global singletons. While they are declared `final` as variables, their `severity` field itself is mutable.
+
+-   **Impact**: When `config_parser.dart` or `entry_point.dart` updates rule severities from a configuration file or CLI flags, they directly mutate these global objects.
+-   **Inconsistency**: This conflicts with the new Dependency Injection pattern in `Validator`, which is designed to receive an isolated set of rule configurations for a specific validation run. If we mutate global state, two independent `Validator` instances created in the same process would share the same rule severities.
+
+### 2. Side-Effects in Configuration Parsing
+
+The `loadConfig` function in `lib/src/config_parser.dart` takes a `Set<CheckType> checkTypes` and mutates it as a side effect while parsing global rules.
+
+-   **Impact**: Code calling `loadConfig` gets its input modified without an explicit return value indicating the change.
+-   **Inconsistency**: It mixes "reading configuration" with "updating application state".
+
+### 3. Fragmentation in Directory Overrides
+
+In `lib/src/entry_point.dart`, overrides for specific directories are resolved manually using hardcoded string keys (e.g., `'check-relative-paths'`), rather than leveraging the typed `CheckType` objects or a dynamic loop.
+
+-   **Impact**: When we added the explicit rule injection to `Validator`, we had to introduce local shadowing variables to bridge the gap between hardcoded config overrides and the `Validator` constructor.
+-   **Inconsistency**: Rule lookup logic is split across multiple styles (string-based maps vs typed `CheckType` instances).
+
+---
+
+## Proposed Solutions
+
+### Solution 1: Immutable `CheckType` with `copyWith`
+
+Make `CheckType` fully immutable by marking all fields as `final`. Introduce a `copyWith` method to create modified instances safely.
+
+```dart
+class CheckType {
+  final String name;
+  final AnalysisSeverity defaultSeverity;
+  final AnalysisSeverity severity; // Changed to final
+
+  CheckType({
+    required this.name,
+    required this.defaultSeverity,
+    AnalysisSeverity? severity,
+  }) : severity = severity ?? defaultSeverity;
+
+  CheckType copyWith({
+    String? name,
+    AnalysisSeverity? defaultSeverity,
+    AnalysisSeverity? severity,
+  }) {
+    return CheckType(
+      name: name ?? this.name,
+      defaultSeverity: defaultSeverity ?? this.defaultSeverity,
+      severity: severity ?? this.severity,
+    );
+  }
+}
+```
+
+This was also suggested in `FEATURE_REQUESTS.md`. By using immutable data types, we can pass configuration around without risking unintended side leaks.
+
+### Solution 2: Functional `loadConfig`
+
+Refactor `loadConfig` to return a `Configuration` object that encapsulates *all* resolved rule overrides, rather than mutating its inputs.
+
+```dart
+// Suggested loadConfig signature
+Future<Configuration> loadConfig() async { ... }
+
+class Configuration {
+  final Map<String, AnalysisSeverity> globalRuleOverrides;
+  final List<DirectoryConfig> directoryConfigs;
+  // ...
+}
+```
+
+### Solution 3: Dynamic Rule Resolution in Entry Point
+
+Instead of hardcoding rules in the directory loop, we can map directory config rules directly to creating a `Validator` instance.
+
+```dart
+// Pre-resolve directory rules by name in entry_point.dart
+final Map<String, AnalysisSeverity> resolvedLocalRules = {};
+
+// Fallback to global rules
+for (final rule in globalRules) {
+   resolvedLocalRules[rule.name] = rule.severity;
+}
+
+// Override with specific directory rules
+for (final key in dirConfig.rules.keys) {
+   resolvedLocalRules[key] = dirConfig.rules[key]!;
+}
+
+// Create Validator with these local overrides
+final localValidator = Validator(
+  rules: resolvedLocalRules.entries.map((e) => CheckType(name: e.key, defaultSeverity: e.value)).toSet(),
+);
+```
+
+This unifies rule resolution into a single dynamic pattern.
+
+---
+## Verification Plan
+
+### Automated Tests
+1. Add tests verify rule overriding works correctly without leak when `copyWith` is used in parallel validation runs.
+2. Verify that `loadConfig` works when called multiple times without affecting previous parsed states.

package/skills/flutter-skills/tool/dart_skills_lint/documentation/feature_design_docs/pub_vs_skill_report.md

@@ -0,0 +1,56 @@
+# Report: Conflict Analysis for Dual-Publishing as Pub Package and Agent Skill
+
+This report investigates the compatibility of the `dart_skills_lint` codebase with two different distribution specifications: the [pub.dev package specification](https://dart.dev/tools/pub/pubspec) and the [Agent Skills specification](../knowledge/SPECIFICATION.md).
+
+## 1. Executive Summary
+
+While it is technically possible to host both specifications in a single codebase, there are several **hard conflicts** regarding naming conventions and directory requirements. Most notably, a single identifier cannot satisfy both naming standards simultaneously if it contains separators.
+
+## 2. Identified Conflicts
+
+### 2.1 Naming Convention (Hard Conflict)
+The most significant conflict lies in the allowed characters for project identifiers:
+
+*   **Pub Package Specification:** Package names must be valid Dart identifiers. They **must use underscores** (`_`) for separators and **cannot contain hyphens** (`-`).
+*   **Agent Skills Specification:** Skill names must be lowercase alphanumeric and **must use hyphens** (`-`) for separators. They **cannot contain underscores** (`_`).
+
+**Result:** A project named `dart_skills_lint` (valid for pub) is invalid for Agent Skills. A project named `dart-skills-lint` (valid for skills) is invalid for pub. To publish as both, the project must use two different names (e.g., `dart_skills_lint` on pub and `dart-skills-lint` as a skill).
+
+### 2.2 Directory Name Match Rule (Structural Conflict)
+*   **Agent Skills Specification:** The `name` field in `SKILL.md` **must exactly match** the name of its parent directory.
+*   **Pub Package Specification:** While not strictly enforced for publishing, Dart conventions strongly prefer the directory name to match the package name in `pubspec.yaml`.
+
+**Result:** To satisfy the Agent Skills specification, the project directory **must** be named `dart-skills-lint`. This forces a discrepancy between the directory name and the internal Dart package name (`dart_skills_lint`), which may cause minor confusion for Dart developers but does not prevent functionality.
+
+### 2.3 Directory Structure and "Clutter"
+*   **Agent Skills Specification:** Recommends a "flat and predictable structure" consisting of `SKILL.md`, `scripts/`, `references/`, and `assets/`.
+*   **Pub Package Specification:** Requires a specific structure with `pubspec.yaml`, `lib/`, `bin/`, and `test/`, along with ephemeral directories like `.dart_tool/`.
+
+**Result:** While these can coexist, a Dart project is significantly more complex than the "flat" structure envisioned for Agent Skills. An AI agent scanning the skill directory will encounter numerous files (like `pubspec.lock`, `analysis_options.yaml`) that are irrelevant to its operation, potentially wasting context if not explicitly ignored.
+
+### 2.4 Executable Location
+*   **Agent Skills Specification:** Expects executable logic to reside in the `scripts/` directory.
+*   **Pub Package Specification:** Places CLI entry points in the `bin/` directory.
+
+**Result:** To align with the Agent Skills specification, the `SKILL.md` instructions must either:
+1.  Explicitly point the agent to `bin/cli.dart`.
+2.  Provide a wrapper script in a `scripts/` directory (e.g., `scripts/run-linter.sh`) that executes the Dart code.
+
+### 2.5 Metadata Redundancy
+Both specifications require overlapping metadata (description, license, version).
+*   **Pub:** Stored in `pubspec.yaml`.
+*   **Skills:** Stored in `SKILL.md` YAML frontmatter.
+
+**Result:** There is no native mechanism to synchronize these. Developers must manually ensure that the description and version remain consistent across both files, increasing the risk of "metadata drift."
+
+## 3. Recommended Strategy for `dart_skills_lint`
+
+To achieve dual-compatibility, the following configuration is recommended:
+
+1.  **Directory Name:** Keep the directory named `dart-skills-lint`.
+2.  **SKILL.md:**
+    -   Set `name: dart-skills-lint`.
+    -   Provide clear instructions to run `dart bin/cli.dart` or `dart run`.
+3.  **pubspec.yaml:**
+    -   Set `name: dart_skills_lint`.
+4.  **Scripts Wrapper:** Consider adding a `scripts/lint.sh` that calls the Dart linter to satisfy the standard skill directory structure.

package/skills/flutter-skills/tool/dart_skills_lint/documentation/knowledge/SPECIFICATION.md

@@ -0,0 +1,79 @@
+# Agent Skills Specification
+
+This document defines the technical requirements and architectural priorities for implementing Agent Skills. It serves as a self-contained reference for engineers building or integrating skills into AI agent environments.
+
+## 1. Overview
+An **Agent Skill** is a portable, self-contained directory that extends an AI agent's capabilities. It provides the agent with specific instructions, tools, and domain-specific knowledge required to perform a specialized task.
+
+## 2. Directory Structure
+A skill directory must follow a flat and predictable structure. The only mandatory file is `SKILL.md` at the root.
+
+```text
+skill-name/
+├── SKILL.md       # Required: Metadata + Instructions
+├── scripts/       # Optional: Executable code (Python, Bash, JS, etc.)
+├── references/    # Optional: Deep-dive documentation and templates
+└── assets/        # Optional: Static resources (images, schemas, etc.)
+```
+
+## 3. The `SKILL.md` File
+The `SKILL.md` file uses YAML frontmatter for machine-readable metadata, followed by Markdown-formatted instructions for the agent.
+
+### 3.1 Metadata (YAML Frontmatter)
+| Field | Required | Constraints |
+| :--- | :--- | :--- |
+| `name` | Yes | 1-64 chars; lowercase alphanumeric and hyphens (`-`) only; no leading/trailing/consecutive hyphens. **Must match the parent directory name.** |
+| `description` | Yes | 1-1024 chars. A concise summary used by agents to determine when to activate the skill. |
+| `license` | No | Short name (e.g., MIT, Apache-2.0) or reference to a bundled license file. |
+| `compatibility` | No | 1-500 chars; specifies environment requirements (e.g., `Requires Python 3.10+`, `Node.js 18`). |
+| `metadata` | No | Arbitrary key-value mapping for client-specific properties (e.g., `version`, `author`). |
+| `allowed-tools` | No | (Experimental) Space-delimited list of pre-approved tools (e.g., `Bash(git:*)`). |
+
+### 3.2 Instructions (Markdown Body)
+The body should contain the "expert knowledge" for the agent.
+- **Referencing:** Use relative paths to files within the skill directory (e.g., `[See technical details](references/DETAILS.md)`).
+
+
+## 4. Implementation Requirements
+
+### 4.1 Validation
+Validation ensures that a skill directory and its `SKILL.md` file adhere to the specification. A linter or validator must check the following rules:
+
+#### 4.1.1 Directory and File Structure
+- **Existence**: The target path must exist and be a directory.
+- **Mandatory File**: The root directory must contain a `SKILL.md` file.
+
+#### 4.1.2 Metadata (YAML Frontmatter)
+- **YAML Integrity**: The frontmatter must be valid YAML.
+- **Allowed Fields**: Only the following fields are allowed: `name`, `description`, `license`, `allowed-tools`, `metadata`, `compatibility`.
+- **Required Fields**: `name` and `description` are mandatory.
+
+#### 4.1.3 Field Specific Constraints
+- **Skill Name (`name`)**:
+  - Must be lowercase.
+  - Length: Maximum 64 characters.
+  - Characters: Only lowercase letters, digits, and hyphens (`-`).
+  - No leading or trailing hyphens.
+  - No consecutive hyphens (`--`).
+  - **Directory Name Match**: The skill `name` must exactly match the name of its parent directory.
+- **Description (`description`)**:
+  - Length: Maximum 1024 characters.
+- **Compatibility (`compatibility`)**:
+  - Length: Maximum 500 characters.
+
+#### 4.1.4 Content Constraints
+- **Trailing Whitespace**: Lines in `SKILL.md` should not have trailing whitespace. Exactly 2 spaces at the end of a line are allowed to support Markdown hard line breaks, per the [CommonMark Spec](https://spec.commonmark.org/0.31.2/#hard-line-breaks).
+- **Path Constraints**: **Inline** Markdown links must not use absolute paths to enforce portability. Can optionally be configured to check that relative paths point to valid, existing files (disabled by default). *Note: Validation only applies to inline Markdown links; HTML and reference-style links are not supported.*
+
+### 5.2 Scripts & Tools
+- Scripts in the `scripts/` directory should be self-documenting and provide clear error messages.
+
+### 5.3 Versioning
+- Use the `metadata` field in `SKILL.md` to track versions:
+  ```yaml
+  metadata:
+    version: "1.0.0"
+  ```
+
+## 6. Best Practices
+- **Avoid Deep Nesting:** Keep the directory structure as flat as possible. References should ideally be only one level deep from the root.

package/skills/flutter-skills/tool/dart_skills_lint/documentation/knowledge/architecture_overview.md

@@ -0,0 +1,64 @@
+# Architecture Overview: Agent Skills Linter (`dart_skills_lint`)
+
+This document provides a high-level architectural overview of the `dart_skills_lint` codebase. It outlines the project's components, execution flow, and design patterns used to validate Agent Skill specifications.
+
+## 🧱 Key Components
+
+The codebase is organized into standard Dart package layers, separating CLI handling, validation logic, and data models.
+
+### 🚗 1. CLI Entry Point (`lib/src/entry_point.dart`)
+The `entry_point.dart` file serves as the command-line interface. 
+- **Argument Parsing:** Uses standard `package:args` to parse input flags (`--skills-directory`, `--generate-baseline`, rules toggles, etc.).
+- **Workspace Discovery:** Resolves target folders by searching standard locations (e.g., `.agents/skills`, `.claude/skills`) or parsing user arguments.
+- **Ignore System Integration:** Handlers for `dart_skills_lint_ignore.json` (baseline files) to filter out known failures without failing the build.
+- **Log Management:** Consumes validation reports and standardizes format for terminal display (stouts vs stderr).
+
+### ⚙️ 2. Configuration Parser (`lib/src/config_parser.dart`)
+- Loads user-defined custom settings from `dart_skills_lint.yaml` if it exists.
+- Maps directory-specific rules overrides and toggles severity defaults.
+
+### 🛡️ 3. Validation Engine (`lib/src/validator.dart`)
+The core motor of the package.
+- Scans `SKILL.md` using regular expressions (`dotAll: true`) to extract Frontmatter.
+- Delegates to sub-routines for checking:
+  - **Directory structure:** Correct place and flat tree constraints.
+  - **Field constraints:** Descriptions vs name match.
+  - **Relational properties:** Verifies relative links resolve correctly on disc.
+- Outputs `ValidationResult` objects wrapping aggregates of `ValidationError`.
+
+### 📜 4. Predefined Rules templates (`lib/src/rules.dart`)
+Contains global definitions for standard checks. Uses standard types (`CheckType`) allowing toggling and severity states.
+
+### 📦 5. Core Data Models (`lib/src/models/`)
+- **`ValidationError`:** Complex error object recording rule IDs, messages, severity contexts, and ignore statuses.
+- **`CheckType`:** A schema binding check descriptions to severity settings.
+- **`IgnoreEntry`:** Structure for serializing/deserializing file suppressions to/from JSON.
+
+---
+
+## ⏳ Execution Lifecycle
+
+A typical run of the linter follows this sequential graph:
+
+```mermaid
+graph TD
+    Start([CLI - runApp]) --> ArgParse[Parse ARGs & Load config.yaml]
+    ArgParse --> Discover[Resolve Target Directories]
+    Discover --> ValidatorLoad[Instantiate Validator w/ Settings]
+    ValidatorLoad --> DirLoop[Iterate Directories]
+    DirLoop --> Validation[Run validator.validate]
+    Validation --> ParseFront[YAML Frontmatter Parsing]
+    ParseFront --> RuleChecks[Run Field + Path Checks]
+    RuleChecks --> ResultAggregate[Compile ValidationError List]
+    ResultAggregate --> IgnoreFilter[Apply dart_skills_lint_ignore.json filters]
+    IgnoreFilter --> LogOutput[Print to console & Set exitCode]
+    LogOutput --> Next{Next Dir?}
+    Next -- Yes --> DirLoop
+    Next -- No --> Finish([Exit Term])
+```
+
+## 🧠 Design Principles
+
+- **Separation of Concerns:** CLI runners are isolated from pure validation units. The `Validator` takes objects and doesn't know about `ArgResults`.
+- **Stateless Configuration vs Overrides:** When running against a workspace with specific subdirectory traits, the `Validator` instances are re-instantiated with isolated context bindings so properties do not leak.
+- **Context Preservation:** Standardizing lint exceptions (Ignore Systems) as structural objects rather than ad-hoc string matches prevent brittle regressions.

package/skills/flutter-skills/tool/dart_skills_lint/lib/dart_skills_lint.dart

@@ -0,0 +1,11 @@
+// Copyright (c) 2026, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+export 'src/config_parser.dart';
+export 'src/entry_point.dart';
+export 'src/models/analysis_severity.dart';
+export 'src/models/skill_context.dart';
+export 'src/models/skill_rule.dart';
+export 'src/models/validation_error.dart';
+export 'src/validator.dart';

package/skills/flutter-skills/tool/dart_skills_lint/lib/src/config_parser.dart

@@ -0,0 +1,156 @@
+// Copyright (c) 2026, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+// ignore_for_file: specify_nonobvious_local_variable_types yaml parsing has dynamic types.
+
+import 'dart:io';
+import 'package:logging/logging.dart';
+import 'package:yaml/yaml.dart';
+import 'models/analysis_severity.dart';
+
+final _log = Logger('dart_skills_lint');
+
+class ConfigParser {
+  static const _dartSkillsLintKey = 'dart_skills_lint';
+  static const _rulesKey = 'rules';
+  static const _directoriesKey = 'directories';
+  static const _pathKey = 'path';
+  static const _ignoreFileKey = 'ignore_file';
+
+  static const Set<String> _allowedTopLevelKeys = {_rulesKey, _directoriesKey};
+  static const Set<String> _allowedDirectoryKeys = {_pathKey, _rulesKey, _ignoreFileKey};
+
+  static AnalysisSeverity _parseSeverity(String value) {
+    if (value == 'error') {
+      return AnalysisSeverity.error;
+    }
+    if (value == 'warning') {
+      return AnalysisSeverity.warning;
+    }
+    if (value == 'disabled') {
+      return AnalysisSeverity.disabled;
+    }
+    return AnalysisSeverity.disabled; // Default if unknown
+  }
+
+  /// Reads dart_skills_lint.yaml from the current directory and returns the configuration.
+  static Future<Configuration> loadConfig() async {
+    final configFile = File('dart_skills_lint.yaml');
+    if (!configFile.existsSync()) {
+      return Configuration();
+    }
+
+    try {
+      final String content = await configFile.readAsString();
+      final yaml = loadYaml(content);
+      if (yaml is YamlMap && yaml.containsKey(_dartSkillsLintKey)) {
+        final toolConfig = yaml[_dartSkillsLintKey];
+        if (toolConfig is YamlMap) {
+          final parsingErrors = <String>[];
+
+          _validateTopLevelKeys(toolConfig, parsingErrors);
+          final configuredRules = _parseRules(toolConfig);
+          final directoryConfigs = _parseDirectories(toolConfig, parsingErrors);
+          return Configuration(
+            directoryConfigs: directoryConfigs,
+            configuredRules: configuredRules,
+            parsingErrors: parsingErrors,
+          );
+        }
+      }
+    } catch (e) {
+      _log.warning('Failed to parse dart_skills_lint.yaml: $e');
+    }
+    return Configuration();
+  }
+
+  /// Validates that all keys at the top level of the `dart_skills_lint` configuration map are recognized.
+  /// Appends error messages to `parsingErrors` for any unrecognized keys.
+  static void _validateTopLevelKeys(YamlMap toolConfig, List<String> parsingErrors) {
+    for (final key in toolConfig.keys) {
+      if (!_allowedTopLevelKeys.contains(key.toString())) {
+        parsingErrors.add('Unrecognized top-level key "$key" in dart_skills_lint configuration.');
+      }
+    }
+  }
+
+  /// Parses the global rules configuration from the `dart_skills_lint` map.
+  /// Returns a map of rule names to their resolved `AnalysisSeverity`.
+  static Map<String, AnalysisSeverity> _parseRules(YamlMap toolConfig) {
+    final configuredRules = <String, AnalysisSeverity>{};
+    if (toolConfig.containsKey(_rulesKey)) {
+      final rules = toolConfig[_rulesKey];
+      if (rules is YamlMap) {
+        for (final key in rules.keys) {
+          configuredRules[key.toString()] = _parseSeverity(rules[key]?.toString() ?? '');
+        }
+      }
+    }
+    return configuredRules;
+  }
+
+  /// Parses the `directories` list from the configuration.
+  /// Validates keys for each directory entry and resolves path-specific rule overrides.
+  /// Appends any parsing errors to `parsingErrors`.
+  static List<DirectoryConfig> _parseDirectories(YamlMap toolConfig, List<String> parsingErrors) {
+    final directoryConfigs = <DirectoryConfig>[];
+    if (toolConfig.containsKey(_directoriesKey)) {
+      final dirs = toolConfig[_directoriesKey];
+      if (dirs is YamlList) {
+        for (final dir in dirs) {
+          if (dir is YamlMap && dir.containsKey(_pathKey)) {
+            final path = dir[_pathKey] as String;
+
+            for (final key in dir.keys) {
+              if (!_allowedDirectoryKeys.contains(key.toString())) {
+                parsingErrors.add('Unrecognized key "$key" in directory entry for "$path".');
+              }
+            }
+
+            final rules = <String, AnalysisSeverity>{};
+            if (dir.containsKey(_rulesKey)) {
+              final localRules = dir[_rulesKey];
+              if (localRules is YamlMap) {
+                for (final key in localRules.keys) {
+                  rules[key.toString()] = _parseSeverity(localRules[key]?.toString() ?? '');
+                }
+              }
+            }
+            final ignoreFile = dir[_ignoreFileKey] as String?;
+            directoryConfigs.add(DirectoryConfig(path: path, rules: rules, ignoreFile: ignoreFile));
+          }
+        }
+      }
+    }
+    return directoryConfigs;
+  }
+}
+
+/// Configuration for a specific directory containing skills.
+///
+/// Allows overriding rules and specifying a custom ignore file for skills
+/// located within this directory.
+class DirectoryConfig {
+  DirectoryConfig({required this.path, required this.rules, this.ignoreFile});
+
+  /// The path to the directory containing skills.
+  ///
+  /// Can be absolute or relative to the current working directory.
+  /// Supports tilde expansion (e.g., `~/...`).
+  final String path;
+  final Map<String, AnalysisSeverity> rules;
+  final String? ignoreFile;
+}
+
+/// Structured configuration for the linter.
+class Configuration {
+  Configuration({
+    this.directoryConfigs = const [],
+    this.configuredRules = const {},
+    this.parsingErrors = const [],
+  });
+  final List<DirectoryConfig> directoryConfigs;
+  final Map<String, AnalysisSeverity> configuredRules;
+  final List<String> parsingErrors;
+}