@intellectronica/ruler 0.3.10 → 0.3.11

package/README.md

@@ -54,16 +54,16 @@ Ruler solves this by providing a **single source of truth** for all your AI agen
 
 ## Supported AI Agents
 
-| Agent            | Rules File(s)                                    | MCP Configuration / Notes                        |
-| ---------------- | ------------------------------------------------ | ------------------------------------------------ |
-| AGENTS.md        | `AGENTS.md`                                      | (pseudo-agent ensuring root `AGENTS.md` exists)  |
-| GitHub Copilot   | `AGENTS.md`                                      | `.vscode/mcp.json`                               |
-| Claude Code      | `CLAUDE.md`                                      | `.mcp.json`                                      |
-| OpenAI Codex CLI | `AGENTS.md`                                      | `.codex/config.toml`                             |
-| Jules            | `AGENTS.md`                                      | -                                                |
-| Cursor           | `.cursor/rules/ruler_cursor_instructions.mdc`    | `.cursor/mcp.json`                               |
-| Windsurf         | `.windsurf/rules/ruler_windsurf_instructions.md` | -                                                |
-| Cline            | `.clinerules`                                    | -                                                |
+| Agent            | Rules File(s)                                 | MCP Configuration / Notes                        |
+| ---------------- | --------------------------------------------- | ------------------------------------------------ |
+| AGENTS.md        | `AGENTS.md`                                   | (pseudo-agent ensuring root `AGENTS.md` exists)  |
+| GitHub Copilot   | `AGENTS.md`                                   | `.vscode/mcp.json`                               |
+| Claude Code      | `CLAUDE.md`                                   | `.mcp.json`                                      |
+| OpenAI Codex CLI | `AGENTS.md`                                   | `.codex/config.toml`                             |
+| Jules            | `AGENTS.md`                                   | -                                                |
+| Cursor           | `.cursor/rules/ruler_cursor_instructions.mdc` | `.cursor/mcp.json`                               |
+| Windsurf         | `AGENTS.md`                                   | `.windsurf/mcp_config.json`                      |
+| Cline            | `.clinerules`                                 | -                                                |
 | Crush            | `CRUSH.md`                                       | `.crush.json`                                    |
 | Amp              | `AGENTS.md`                                      | -                                                |
 | Amazon Q CLI     | `.amazonq/rules/ruler_q_rules.md`                | `.amazonq/mcp.json`                              |
@@ -105,10 +105,11 @@ npx @intellectronica/ruler apply
 1. Navigate to your project's root directory
 2. Run `ruler init`
 3. This creates:
-  - `.ruler/` directory
-  - `.ruler/AGENTS.md`: The primary starter Markdown file for your rules
-  - `.ruler/ruler.toml`: The main configuration file for Ruler (now contains sample MCP server sections; legacy `.ruler/mcp.json` no longer scaffolded)
-  - (Optional legacy fallback) If you previously used `.ruler/instructions.md`, it is still respected when `AGENTS.md` is absent. (The prior runtime warning was removed.)
+
+- `.ruler/` directory
+- `.ruler/AGENTS.md`: The primary starter Markdown file for your rules
+- `.ruler/ruler.toml`: The main configuration file for Ruler (now contains sample MCP server sections; legacy `.ruler/mcp.json` no longer scaffolded)
+- (Optional legacy fallback) If you previously used `.ruler/instructions.md`, it is still respected when `AGENTS.md` is absent. (The prior runtime warning was removed.)
 
 Additionally, you can create a global configuration to use when no local `.ruler/` directory is found:
 
@@ -160,7 +161,15 @@ project/
 
 - Discover all `.ruler/` directories in the project hierarchy
 - Load and concatenate rules from each directory in order
-- Enable with: `ruler apply --nested`
+- Decide whether nested mode is enabled using the following precedence:
+  1. `ruler apply --nested` (or `--no-nested`) takes top priority
+  2. `nested = true` in `ruler.toml`
+  3. Default to disabled when neither option is provided
+- When a run is nested, downstream configs are forced to keep `nested = true`. If a child config attempts to disable it, Ruler keeps nested processing active and emits a warning in the logs.
+- Nested processing carries forward each directory's own MCP bundle and configuration settings so that generated files remain scoped to their source directories while being normalized back to the project root.
+
+> [!CAUTION]
+> Nested mode is experimental and may change in future releases. The CLI logs this warning the first time a nested run is detected so you know the behavior may evolve.
 
 **Perfect for:**
 
@@ -212,21 +221,22 @@ The `apply` command looks for `.ruler/` in the current directory tree, reading t
 
 ### Options
 
-| Option                         | Description                                                                                                                                                                     |
-| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--project-root <path>`        | Path to your project's root (default: current directory)                                                                                                                        |
-| `--agents <agent1,agent2,...>` | Comma-separated list of agent names to target (agentsmd, aider, amazonqcli, amp, augmentcode, claude, cline, codex, copilot, crush, cursor, firebase, firebender, gemini-cli, goose, jules, junie, kilocode, kiro, opencode, openhands, qwen, roo, trae, warp, windsurf, zed) |
-| `--config <path>`              | Path to a custom `ruler.toml` configuration file                                                                                                                                |
-| `--mcp` / `--with-mcp`         | Enable applying MCP server configurations (default: true)                                                                                                                       |
-| `--no-mcp`                     | Disable applying MCP server configurations                                                                                                                                      |
-| `--mcp-overwrite`              | Overwrite native MCP config entirely instead of merging                                                                                                                         |
-| `--gitignore`                  | Enable automatic .gitignore updates (default: true)                                                                                                                             |
-| `--no-gitignore`               | Disable automatic .gitignore updates                                                                                                                                            |
-| `--nested`                     | Enable nested rule loading from nested .ruler directories (default: disabled)                                                                                                  |
-| `--backup`                     | Enable/disable creation of .bak backup files (default: enabled)                                                                                                                |
-| `--dry-run`                    | Preview changes without writing files                                                                                                                                           |
-| `--local-only`                 | Do not look for configuration in `$XDG_CONFIG_HOME`                                                                                                                             |
-| `--verbose` / `-v`             | Display detailed output during execution                                                                                                                                        |
+| Option                         | Description                                                            |
+| ------------------------------ | ---------------------------------------------------------------------- |
+| `--project-root <path>`        | Project root path (default: current directory).                        |
+| `--agents <agent1,agent2,...>` | Comma-separated agent names to target (see supported list below).      |
+| `--config <path>`              | Custom `ruler.toml` path.                                              |
+| `--mcp` / `--with-mcp`         | Enable applying MCP server configurations (default: true).             |
+| `--no-mcp`                     | Disable applying MCP server configurations.                            |
+| `--mcp-overwrite`              | Overwrite native MCP config instead of merging.                        |
+| `--gitignore`                  | Enable automatic .gitignore updates (default: true).                   |
+| `--no-gitignore`               | Disable automatic .gitignore updates.                                  |
+| `--nested`                     | Enable nested rule loading (default: inherit from config or disabled). |
+| `--no-nested`                  | Disable nested rule loading even if `nested = true` in config.         |
+| `--backup`                     | Toggle creation of `.bak` backup files (default: enabled).             |
+| `--dry-run`                    | Preview changes without writing files.                                 |
+| `--local-only`                 | Skip `$XDG_CONFIG_HOME` when looking for configuration.                |
+| `--verbose` / `-v`             | Display detailed output during execution.                              |
 
 ### Common Examples
 
@@ -305,15 +315,15 @@ ruler revert [options]
 
 ### Options
 
-| Option                         | Description                                                                                                                                                                  |
-| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--project-root <path>`        | Path to your project's root (default: current directory)                                                                                                                     |
+| Option                         | Description                                                                                                                                                                                                                                                                   |
+| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--project-root <path>`        | Path to your project's root (default: current directory)                                                                                                                                                                                                                      |
 | `--agents <agent1,agent2,...>` | Comma-separated list of agent names to revert (agentsmd, aider, amazonqcli, amp, augmentcode, claude, cline, codex, copilot, crush, cursor, firebase, firebender, gemini-cli, goose, jules, junie, kilocode, kiro, opencode, openhands, qwen, roo, trae, warp, windsurf, zed) |
-| `--config <path>`              | Path to a custom `ruler.toml` configuration file                                                                                                                             |
-| `--keep-backups`               | Keep backup files (.bak) after restoration (default: false)                                                                                                                  |
-| `--dry-run`                    | Preview changes without actually reverting files                                                                                                                             |
-| `--verbose` / `-v`             | Display detailed output during execution                                                                                                                                     |
-| `--local-only`                 | Only search for local .ruler directories, ignore global config                                                                                                               |
+| `--config <path>`              | Path to a custom `ruler.toml` configuration file                                                                                                                                                                                                                              |
+| `--keep-backups`               | Keep backup files (.bak) after restoration (default: false)                                                                                                                                                                                                                   |
+| `--dry-run`                    | Preview changes without actually reverting files                                                                                                                                                                                                                              |
+| `--verbose` / `-v`             | Display detailed output during execution                                                                                                                                                                                                                                      |
+| `--local-only`                 | Only search for local .ruler directories, ignore global config                                                                                                                                                                                                                |
 
 ### Common Examples
 
@@ -525,6 +535,7 @@ DEBUG = "1"
 ```
 
 **Remote servers** require a `url` field (headers optional; bearer Authorization token auto-extracted for OpenHands when possible):
+
 ```toml
 [mcp_servers.remote_server]
 url = "https://api.example.com"
@@ -543,6 +554,135 @@ Ruler uses this configuration with the `merge` (default) or `overwrite` strategy
 export CODEX_HOME="$(pwd)/.codex"
 ```
 
+## Skills Support (Experimental)
+
+**⚠️ Experimental Feature**: Skills support is currently experimental and requires `uv` (the Python package manager) to be installed on your system for MCP-based agent integration.
+
+Ruler can manage and propagate Claude Code-compatible skills to supported AI agents. Skills are stored in `.ruler/skills/` and are automatically distributed to compatible agents when you run `ruler apply`.
+
+### How It Works
+
+Skills are specialized knowledge packages that extend AI agent capabilities with domain-specific expertise, workflows, or tool integrations. Ruler discovers skills in your `.ruler/skills/` directory and propagates them to compatible agents:
+
+- **Claude Code agents**: Skills are copied to `.claude/skills/` in their native format
+- **Other MCP-compatible agents**: Skills are copied to `.skillz/` and a Skillz MCP server is automatically configured via `uvx`
+
+### Skills Directory Structure
+
+Skills can be organized flat or nested:
+
+```
+.ruler/skills/
+├── my-skill/
+│   ├── SKILL.md           # Required: skill instructions/knowledge
+│   ├── helper.py          # Optional: additional resources (scripts)
+│   └── reference.md       # Optional: additional resources (docs)
+└── another-skill/
+    └── SKILL.md
+```
+
+Each skill must contain:
+- `SKILL.md` - Primary skill file with instructions or knowledge base
+
+Skills can optionally include additional resources like:
+- Markdown files with supplementary documentation
+- Python, JavaScript, or other scripts
+- Configuration files or data
+
+### Configuration
+
+Skills support is **enabled by default** but can be controlled via:
+
+**CLI flags:**
+```bash
+# Enable skills (default)
+ruler apply --skills
+
+# Disable skills
+ruler apply --no-skills
+```
+
+**Configuration in `ruler.toml`:**
+```toml
+[skills]
+enabled = true  # or false to disable
+```
+
+### Skillz MCP Server
+
+For agents that support MCP but don't have native skills support (all agents except Claude Code), Ruler automatically:
+
+1. Copies skills to `.skillz/` directory
+2. Configures a Skillz MCP server in the agent's configuration
+3. Uses `uvx` to launch the server with the absolute path to `.skillz`
+
+Example auto-generated MCP server configuration:
+```toml
+[mcp_servers.skillz]
+command = "uvx"
+args = ["skillz@latest", "/absolute/path/to/project/.skillz"]
+```
+
+### `.gitignore` Integration
+
+When skills support is enabled and gitignore integration is active, Ruler automatically adds:
+- `.claude/skills/` (for Claude Code agents)
+- `.skillz/` (for MCP-based agents)
+
+to your `.gitignore` file within the managed Ruler block.
+
+### Requirements
+
+- **For Claude Code**: No additional requirements
+- **For MCP agents**: `uv` must be installed and available in your PATH
+  ```bash
+  # Install uv if needed
+  curl -LsSf https://astral.sh/uv/install.sh | sh
+  ```
+
+### Validation
+
+Ruler validates discovered skills and issues warnings for:
+- Missing required file (`SKILL.md`)
+- Invalid directory structures (directories without `SKILL.md` and no sub-skills)
+
+Warnings don't prevent propagation but help identify potential issues.
+
+### Dry-Run Mode
+
+Test skills propagation without making changes:
+```bash
+ruler apply --dry-run
+```
+
+This shows which skills would be copied and which MCP servers would be configured.
+
+### Example Workflow
+
+```bash
+# 1. Add a skill to your project
+mkdir -p .ruler/skills/my-skill
+cat > .ruler/skills/my-skill/SKILL.md << 'EOF'
+# My Custom Skill
+
+This skill provides specialized knowledge for...
+
+## Usage
+
+When working on this project, always follow these guidelines:
+- Use TypeScript for all new code
+- Write tests for all features
+- Follow the existing code style
+EOF
+
+# 2. Apply to all agents (skills enabled by default)
+ruler apply
+
+# 3. Skills are now available to compatible agents:
+#    - Claude Code: .claude/skills/my-skill/
+#    - Other MCP agents: .skillz/my-skill/ + Skillz MCP server configured
+```
+
 ## `.gitignore` Integration
 
 Ruler automatically manages your `.gitignore` file to keep generated agent configuration files out of version control.
@@ -599,7 +739,7 @@ ruler apply
 
 ### Scenario 2: Complex Projects with Nested Rules
 
-For large projects with multiple components or services, use nested rule loading:
+For large projects with multiple components or services, enable nested rule loading so each directory keeps its own rules and MCP bundle:
 
 ```bash
 # Set up nested .ruler directories
@@ -609,12 +749,25 @@ mkdir -p src/.ruler tests/.ruler docs/.ruler
 echo "# API Design Guidelines" > src/.ruler/api_rules.md
 echo "# Testing Best Practices" > tests/.ruler/test_rules.md
 echo "# Documentation Standards" > docs/.ruler/docs_rules.md
+```
 
-# Apply with nested loading
-ruler apply --nested --verbose
+```toml
+# .ruler/ruler.toml
+nested = true
 ```
 
-This creates context-specific instructions for different parts of your project while maintaining global rules in the root `.ruler/` directory.
+```bash
+# The CLI inherits nested mode from ruler.toml
+ruler apply --verbose
+
+# Override from the CLI at any time
+ruler apply --no-nested
+```
+
+This creates context-specific instructions for different parts of your project while maintaining global rules in the root `.ruler/` directory. Nested runs automatically keep every nested config enabled even if a child tries to disable it.
+
+> [!NOTE]
+> The CLI prints "Nested mode is experimental and may change in future releases." the first time nested processing runs. Expect refinements in future versions.
 
 ### Scenario 3: Team Standardization
 
@@ -719,7 +872,7 @@ This shows:
 A: Currently, all agents receive the same concatenated rules. For agent-specific instructions, include sections in your rule files like "## GitHub Copilot Specific" or "## Aider Configuration".
 
 **Q: How do I set up different instructions for different parts of my project?**
-A: Use the `--nested` flag with `ruler apply --nested`. This enables Ruler to discover and load rules from multiple `.ruler/` directories throughout your project hierarchy. Place component-specific instructions in `src/.ruler/`, test-specific rules in `tests/.ruler/`, etc., while keeping global rules in the root `.ruler/` directory.
+A: Enable nested mode either by setting `nested = true` in `ruler.toml` or by passing `ruler apply --nested`. The CLI inherits the config setting by default, but `--no-nested` always wins if you need to opt out for a run. Nested mode keeps loading rules (and MCP settings) from every `.ruler/` directory in the hierarchy, forces child configs to remain nested, and logs "Nested mode is experimental and may change in future releases." if any nested processing occurs.
 
 **Q: How do I temporarily disable Ruler for an agent?**
 A: Set `enabled = false` in `ruler.toml` under `[agents.agentname]`, or use `--agents` flag to specify only the agents you want.

package/dist/agents/AbstractAgent.js

@@ -80,5 +80,12 @@ class AbstractAgent {
     supportsMcpRemote() {
         return false;
     }
+    /**
+     * Returns whether this agent has native skills support.
+     * Defaults to false if not overridden.
+     */
+    supportsNativeSkills() {
+        return false;
+    }
 }
 exports.AbstractAgent = AbstractAgent;

package/dist/agents/ClaudeAgent.js

@@ -55,5 +55,8 @@ class ClaudeAgent extends AbstractAgent_1.AbstractAgent {
     supportsMcpRemote() {
         return true;
     }
+    supportsNativeSkills() {
+        return true;
+    }
 }
 exports.ClaudeAgent = ClaudeAgent;

package/dist/agents/WindsurfAgent.js

@@ -1,88 +1,21 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WindsurfAgent = void 0;
-const path = __importStar(require("path"));
-const AbstractAgent_1 = require("./AbstractAgent");
-const FileSystemUtils_1 = require("../core/FileSystemUtils");
+const AgentsMdAgent_1 = require("./AgentsMdAgent");
 /**
  * Windsurf agent adapter.
+ * Now uses AGENTS.md format like other agents.
  */
-class WindsurfAgent extends AbstractAgent_1.AbstractAgent {
+class WindsurfAgent extends AgentsMdAgent_1.AgentsMdAgent {
     getIdentifier() {
         return 'windsurf';
     }
     getName() {
         return 'Windsurf';
     }
-    async applyRulerConfig(concatenatedRules, projectRoot, rulerMcpJson, // eslint-disable-line @typescript-eslint/no-unused-vars
-    agentConfig, backup = true) {
-        const output = agentConfig?.outputPath ?? this.getDefaultOutputPath(projectRoot);
-        const absolutePath = path.resolve(projectRoot, output);
-        // Windsurf expects a YAML front-matter block with a `trigger` flag.
-        const frontMatter = ['---', 'trigger: always_on', '---', ''].join('\n');
-        const content = `${frontMatter}${concatenatedRules.trimStart()}`;
-        const maxFileSize = 10000; // 10K characters
-        await (0, FileSystemUtils_1.ensureDirExists)(path.dirname(absolutePath));
-        if (backup) {
-            await (0, FileSystemUtils_1.backupFile)(absolutePath);
-        }
-        // Check if content exceeds the 10K limit
-        if (content.length <= maxFileSize) {
-            // Content fits in single file - use original behavior
-            await (0, FileSystemUtils_1.writeGeneratedFile)(absolutePath, content);
-        }
-        else {
-            // Content exceeds limit - split into multiple files
-            console.warn(`[ruler] Warning: Windsurf rule content exceeds ${maxFileSize} characters (${content.length}). Splitting into multiple files.`);
-            const files = this.splitContentIntoFiles(concatenatedRules.trimStart(), frontMatter, maxFileSize);
-            // Write each split file
-            const rulesDir = path.dirname(absolutePath);
-            const baseName = path.basename(absolutePath, '.md');
-            for (let i = 0; i < files.length; i++) {
-                const fileName = `${baseName}_${i.toString().padStart(2, '0')}.md`;
-                const filePath = path.join(rulesDir, fileName);
-                if (backup) {
-                    await (0, FileSystemUtils_1.backupFile)(filePath);
-                }
-                await (0, FileSystemUtils_1.writeGeneratedFile)(filePath, files[i]);
-            }
-        }
-    }
-    getDefaultOutputPath(projectRoot) {
-        return path.join(projectRoot, '.windsurf', 'rules', 'ruler_windsurf_instructions.md');
+    // Windsurf supports MCP configuration
+    getMcpServerKey() {
+        return 'mcpServers';
     }
     supportsMcpStdio() {
         return true;
@@ -90,69 +23,5 @@ class WindsurfAgent extends AbstractAgent_1.AbstractAgent {
     supportsMcpRemote() {
         return true;
     }
-    /**
-     * Gets all actual output paths that will be created, including split files.
-     * This allows the gitignore system to know about split files before they're created.
-     */
-    getActualOutputPaths(concatenatedRules, projectRoot, agentConfig) {
-        const output = agentConfig?.outputPath ?? this.getDefaultOutputPath(projectRoot);
-        const absolutePath = path.resolve(projectRoot, output);
-        // Windsurf expects a YAML front-matter block with a `trigger` flag.
-        const frontMatter = ['---', 'trigger: always_on', '---', ''].join('\n');
-        const content = `${frontMatter}${concatenatedRules.trimStart()}`;
-        const maxFileSize = 10000; // 10K characters
-        // Check if content will be split
-        if (content.length <= maxFileSize) {
-            // Content fits in single file
-            return [absolutePath];
-        }
-        else {
-            // Content will be split - calculate how many files will be created
-            const files = this.splitContentIntoFiles(concatenatedRules.trimStart(), frontMatter, maxFileSize);
-            const rulesDir = path.dirname(absolutePath);
-            const baseName = path.basename(absolutePath, '.md');
-            const splitPaths = [];
-            for (let i = 0; i < files.length; i++) {
-                const fileName = `${baseName}_${i.toString().padStart(2, '0')}.md`;
-                const filePath = path.join(rulesDir, fileName);
-                splitPaths.push(filePath);
-            }
-            return splitPaths;
-        }
-    }
-    /**
-     * Splits content into multiple files, each under the specified size limit.
-     * Splits at the closest newline within the limit.
-     * Each file gets its own front-matter.
-     */
-    splitContentIntoFiles(rules, frontMatter, maxFileSize) {
-        const files = [];
-        const availableSpace = maxFileSize - frontMatter.length;
-        let remainingRules = rules;
-        while (remainingRules.length > 0) {
-            if (remainingRules.length <= availableSpace) {
-                // Remaining content fits in one file
-                files.push(`${frontMatter}${remainingRules}`);
-                break;
-            }
-            // Find the last newline within the available space
-            let splitIndex = availableSpace;
-            const searchSpace = remainingRules.substring(0, availableSpace);
-            const lastNewline = searchSpace.lastIndexOf('\n');
-            if (lastNewline > 0) {
-                // Split at the newline (include the newline in the current file)
-                splitIndex = lastNewline + 1;
-            }
-            else {
-                // No newline found within limit - split at the limit
-                // This shouldn't happen often but we handle it gracefully
-                splitIndex = availableSpace;
-            }
-            const chunk = remainingRules.substring(0, splitIndex);
-            files.push(`${frontMatter}${chunk}`);
-            remainingRules = remainingRules.substring(splitIndex);
-        }
-        return files;
-    }
 }
 exports.WindsurfAgent = WindsurfAgent;

package/dist/cli/commands.js

@@ -63,13 +63,16 @@ function run() {
         })
             .option('nested', {
             type: 'boolean',
-            description: 'Enable nested rule loading from nested .ruler directories (default: disabled)',
-            default: false,
+            description: 'Enable nested rule loading from nested .ruler directories (default: from config or disabled)',
         })
             .option('backup', {
             type: 'boolean',
             description: 'Enable/disable creation of .bak backup files (default: enabled)',
             default: true,
+        })
+            .option('skills', {
+            type: 'boolean',
+            description: 'Enable/disable skills support (experimental, default: enabled)',
         });
     }, handlers_1.applyHandler)
         .command('init', 'Scaffold a .ruler directory with default files', (y) => {

package/dist/cli/handlers.js

@@ -42,6 +42,7 @@ const path = __importStar(require("path"));
 const os = __importStar(require("os"));
 const fs = __importStar(require("fs/promises"));
 const constants_1 = require("../constants");
+const ConfigLoader_1 = require("../core/ConfigLoader");
 /**
  * Handler for the 'apply' command.
  */
@@ -58,7 +59,6 @@ async function applyHandler(argv) {
     const verbose = argv.verbose;
     const dryRun = argv['dry-run'];
     const localOnly = argv['local-only'];
-    const nested = argv.nested;
     const backup = argv.backup;
     // Determine gitignore preference: CLI > TOML > Default (enabled)
     // yargs handles --no-gitignore by setting gitignore to false
@@ -69,8 +69,37 @@ async function applyHandler(argv) {
     else {
         gitignorePreference = undefined; // Let TOML/default decide
     }
+    // Determine nested preference: CLI > TOML > Default (false)
+    let nested;
+    if (argv.nested !== undefined) {
+        // CLI explicitly set nested (either --nested or --no-nested)
+        nested = argv.nested;
+    }
+    else {
+        // CLI didn't set nested, check TOML configuration
+        try {
+            const config = await (0, ConfigLoader_1.loadConfig)({
+                projectRoot,
+                configPath,
+            });
+            // Use TOML setting if available, otherwise default to false
+            nested = config.nested ?? false;
+        }
+        catch {
+            // If config loading fails, use default (false)
+            nested = false;
+        }
+    }
+    // Determine skills preference: CLI > TOML > Default (enabled)
+    let skillsEnabled;
+    if (argv.skills !== undefined) {
+        skillsEnabled = argv.skills;
+    }
+    else {
+        skillsEnabled = undefined; // Let config/default decide
+    }
     try {
-        await (0, lib_1.applyAllAgentConfigs)(projectRoot, agents, configPath, mcpEnabled, mcpStrategy, gitignorePreference, verbose, dryRun, localOnly, nested, backup);
+        await (0, lib_1.applyAllAgentConfigs)(projectRoot, agents, configPath, mcpEnabled, mcpStrategy, gitignorePreference, verbose, dryRun, localOnly, nested, backup, skillsEnabled);
         console.log('Ruler apply completed successfully.');
     }
     catch (err) {

package/dist/constants.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_RULES_FILENAME = exports.ERROR_PREFIX = void 0;
+exports.SKILLZ_MCP_SERVER_NAME = exports.SKILL_MD_FILENAME = exports.SKILLZ_DIR = exports.CLAUDE_SKILLS_PATH = exports.RULER_SKILLS_PATH = exports.SKILLS_DIR = exports.DEFAULT_RULES_FILENAME = exports.ERROR_PREFIX = void 0;
 exports.actionPrefix = actionPrefix;
 exports.createRulerError = createRulerError;
 exports.logVerbose = logVerbose;
@@ -49,3 +49,10 @@ function logVerboseInfo(message, isVerbose, dryRun = false) {
         console.log(`${prefix} ${message}`);
     }
 }
+// Skills-related constants
+exports.SKILLS_DIR = 'skills';
+exports.RULER_SKILLS_PATH = '.ruler/skills';
+exports.CLAUDE_SKILLS_PATH = '.claude/skills';
+exports.SKILLZ_DIR = '.skillz';
+exports.SKILL_MD_FILENAME = 'SKILL.md';
+exports.SKILLZ_MCP_SERVER_NAME = 'skillz';

package/dist/core/ConfigLoader.js

@@ -69,6 +69,11 @@ const rulerConfigSchema = zod_1.z.object({
         enabled: zod_1.z.boolean().optional(),
     })
         .optional(),
+    skills: zod_1.z
+        .object({
+        enabled: zod_1.z.boolean().optional(),
+    })
+        .optional(),
     nested: zod_1.z.boolean().optional(),
 });
 /**
@@ -175,13 +180,23 @@ async function loadConfig(options) {
     if (typeof rawGitignoreSection.enabled === 'boolean') {
         gitignoreConfig.enabled = rawGitignoreSection.enabled;
     }
-    const nested = typeof raw.nested === 'boolean' ? raw.nested : false;
+    const rawSkillsSection = raw.skills && typeof raw.skills === 'object' && !Array.isArray(raw.skills)
+        ? raw.skills
+        : {};
+    const skillsConfig = {};
+    if (typeof rawSkillsSection.enabled === 'boolean') {
+        skillsConfig.enabled = rawSkillsSection.enabled;
+    }
+    const nestedDefined = typeof raw.nested === 'boolean';
+    const nested = nestedDefined ? raw.nested : false;
     return {
         defaultAgents,
         agentConfigs,
         cliAgents,
         mcp: globalMcpConfig,
         gitignore: gitignoreConfig,
+        skills: skillsConfig,
         nested,
+        nestedDefined,
     };
 }