skiller 0.6.3 → 0.7.1

package/README.md

@@ -2,52 +2,50 @@
 
 A Claude-centric fork of [ruler](https://github.com/intellectronica/ruler) with native skills support:
 
-## 1. CLAUDE.md @filename References
+## 1. Skills as Source of Truth
+
+- `.claude/skills/` is the committed source of truth for skills
+- **Bidirectional sync** between `.mdc` and `SKILL.md`:
+  - Create `.claude/skills/foo.mdc` → auto-generates `.claude/skills/foo/SKILL.md`
+  - Create `.claude/skills/foo/SKILL.md` → auto-generates `.claude/skills/foo.mdc`
+- Uses `synced: true` frontmatter to track sync direction
+- Edit either file, the other stays in sync on next `skiller apply`
+- Skill folders from `.claude/rules/` are copied to `.claude/skills/`
+
+## 2. CLAUDE.md @filename References
 
 - Uses `@filename` syntax instead of merging content
 - Claude Code auto-includes referenced files
 - Reduces CLAUDE.md size and keeps sources separate
 - Other agents still get merged content
 
-## 2. MDC File Support
+## 3. MDC File Support
 
 - Supports both `.md` and `.mdc` files (Nuxt Content, Vue)
 - All patterns auto-expand: `"components"` → `"components/**/*.{md,mdc}"`
 
-## 3. Rules Filtering
+## 4. Rules Filtering
 
 - `include`/`exclude` glob patterns in `[rules]`
 - Directory names auto-expand to `directory/**/*.{md,mdc}`
 - Organize by team/feature, exclude drafts/internal docs
 
-## 4. Claude Root Folder
+## 5. Claude Root Folder
 
 - Default directory is `.claude/` (no extra flags needed)
 - Skills already in `.claude/skills` (no copying)
 - Single directory for all Claude Code config
 
-## 5. Cursor-style Rules
+## 6. Cursor-style Rules
 
 - `merge_strategy = "cursor"` parses `.mdc` frontmatter
 - Only includes rules with `alwaysApply: true`
 - Strips frontmatter, keeps body only
 
-## 6. Backup Control
+## 7. Backup Control
 
 - `[backup].enabled = false` disables `.bak` files
 
-## 7. Auto-Generate Skills from Rules
-
-- `[skills].generate_from_rules = true` creates skills from .mdc files
-- Only generates from files with `alwaysApply: false` (or undefined)
-- Files with `alwaysApply: true` are merged into AGENTS.md instead
-- Automatically removes skills when `alwaysApply` changes to `true`
-- Skills use @filename references to original .mdc (for Claude Code)
-- MCP agents (excluding Cursor) get full content in .skillz (frontmatter stripped)
-- Cursor uses .cursor/rules directly (no skillz MCP needed)
-- Globs appended to description: "Applies to files matching: ..."
-- **Folder support**: `rules/docx/docx.mdc` + `rules/docx/script.sh` → `skills/docx/SKILL.md` + `skills/docx/script.sh`
-
 ---
 
 # Skiller: Centralise Your AI Coding Assistant Instructions
@@ -555,19 +553,13 @@ Skiller uses this configuration with the `merge` (default) or `overwrite` strate
 export CODEX_HOME="$(pwd)/.codex"
 ```
 
-## Skills Support (Experimental)
+## Skills Support
 
-**⚠️ 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.
-
-Skiller can manage and propagate Claude Code-compatible skills to supported AI agents. Skills are stored in `.claude/skills/` and are automatically distributed to compatible agents when you run `skiller apply`.
+Skiller can manage and propagate Claude Code-compatible skills to supported AI agents. Skills are stored in `.claude/skills/` as the **committed source of truth** and are automatically discovered by Claude Code.
 
 ### How It Works
 
-Skills are specialized knowledge packages that extend AI agent capabilities with domain-specific expertise, workflows, or tool integrations. Skiller discovers skills in your `.claude/skills/` directory and propagates them to compatible agents:
-
-- **Claude Code**: Skills copied to `.claude/skills/` with @filename references preserved
-- **Cursor**: Uses `.cursor/rules/` directly (copied when `merge_strategy = "cursor"`), no skillz MCP needed
-- **Other MCP agents**: Skills copied to `.skillz/` with @filename references expanded to full content (frontmatter stripped), Skillz MCP server auto-configured via `uvx`
+Skills are specialized knowledge packages that extend AI agent capabilities with domain-specific expertise, workflows, or tool integrations. Skiller discovers skills in your `.claude/skills/` directory and keeps them in sync.
 
 ### Skills Directory Structure
 
@@ -575,66 +567,62 @@ Skills can be organized flat or nested:
 
 ```
 .claude/skills/
+├── my-skill.mdc           # Standalone skill file (auto-syncs to folder)
 ├── my-skill/
-│   ├── SKILL.md           # Required: skill instructions/knowledge
+│   └── SKILL.md           # Generated from my-skill.mdc (synced: true)
+├── another-skill/
+│   ├── SKILL.md           # Manually created skill
 │   ├── helper.py          # Optional: additional resources (scripts)
 │   └── reference.md       # Optional: additional resources (docs)
-└── another-skill/
-    └── SKILL.md
 ```
 
-Each skill must contain:
+Each skill can be defined in two ways:
+
+1. **Standalone `.mdc` file** - Simple skills can be a single `.mdc` file at the skills root
+2. **Skill folder with `SKILL.md`** - Complex skills with additional resources
 
-- `SKILL.md` - Primary skill file with instructions or knowledge base
+### Bidirectional Sync
 
-Skills can optionally include additional resources like:
+Skiller provides bidirectional sync between `.mdc` files and `SKILL.md` folders:
 
-- Markdown files with supplementary documentation
-- Python, JavaScript, or other scripts
-- Configuration files or data
+| Scenario | Sync Direction |
+|----------|---------------|
+| `.mdc` exists, no `SKILL.md` | → Generate `SKILL.md` with `synced: true` |
+| `SKILL.md` has `synced: true` | .mdc → `SKILL.md` (regenerate from .mdc) |
+| `SKILL.md` without `synced: true` | `SKILL.md` → .mdc (SKILL.md is source of truth) |
 
-### Auto-Generated Skills from Rules (with `generate_from_rules = true`)
+The `synced: true` frontmatter flag indicates that the `.mdc` file is the source of truth:
+
+```yaml
+---
+name: my-skill
+description: My custom skill
+synced: true
+---
+
+# Skill content here
+```
 
-When using `[skills].generate_from_rules = true`, skills are automatically created from `.mdc` files in your rules directory. This feature supports folder-based organization:
+### Skill Folders from Rules
 
-**Folder Support**: If your `.mdc` file is in a folder with the same name, all additional files in that folder are automatically copied to the generated skill:
+Skill folders (directories containing `SKILL.md`) in `.claude/rules/` are automatically copied to `.claude/skills/` during `skiller apply`:
 
 ```
 .claude/rules/docx/
-├── docx.mdc          # Main rule (with frontmatter)
+├── SKILL.md          # Makes this a skill folder
 ├── script.sh         # Helper script
 └── templates/        # Subdirectory
     └── default.docx  # Template file
 
-→ Generated:
+→ Copied to:
 
 .claude/skills/docx/
-├── SKILL.md          # Generated from docx.mdc
+├── SKILL.md          # Copied as-is
 ├── script.sh         # Copied automatically
 └── templates/        # Copied automatically
     └── default.docx  # Copied automatically
 ```
 
-**Requirements for folder copying**:
-
-- The `.mdc` file must be in a folder with the same basename (e.g., `docx/docx.mdc`)
-- The `.mdc` file must have frontmatter with `alwaysApply: false` (or undefined)
-- All files and subdirectories in that folder (except the `.mdc` file itself) are copied
-
-**Example `.mdc` file with frontmatter**:
-
-```markdown
----
-description: DOCX file processing utilities
-globs: ['**/*.docx']
-alwaysApply: false
----
-
-# DOCX Processing
-
-Use script.sh to process DOCX files. Templates are in templates/ directory.
-```
-
 ### Configuration
 
 Skills support is **enabled by default** but can be controlled via:
@@ -656,46 +644,6 @@ skiller apply --no-skills
 enabled = true  # or false to disable
 ```
 
-### Skillz MCP Server
-
-For agents that support MCP but don't have native skills support (excluding Claude Code and Cursor), Skiller automatically:
-
-1. Copies skills to `.skillz/` directory with @filename references expanded to full content
-2. Strips frontmatter from referenced .mdc files to avoid duplication
-3. Configures a Skillz MCP server in the agent's configuration
-4. Uses `uvx` to launch the server with the absolute path to `.skillz`
-
-**Note**: Cursor is excluded from Skillz MCP because it uses `.cursor/rules/` directory natively.
-
-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, Skiller automatically adds:
-
-- `.claude/skills/` (when generated from `.claude/rules/` or copied from `.claude/skills/`)
-- `.skillz/` (for MCP-based agents excluding Cursor)
-- `.cursor/rules/` (when using `merge_strategy = "cursor"`)
-
-to your `.gitignore` file within the managed Skiller block.
-
-**Note**: If you manually create `.claude/skills/` without `.claude/rules/`, it won't be gitignored (assumed to be versioned).
-
-### 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
 
 Skiller validates discovered skills and issues warnings for:
@@ -713,32 +661,39 @@ Test skills propagation without making changes:
 skiller apply --dry-run
 ```
 
-This shows which skills would be copied and which MCP servers would be configured.
+This shows which skills would be synced and validated.
 
 ### Example Workflow
 
 ```bash
-# 1. Add a skill to your project
-mkdir -p .claude/skills/my-skill
-cat > .claude/skills/my-skill/SKILL.md << 'EOF'
+# Option 1: Create a skill using .mdc file
+cat > .claude/skills/my-skill.mdc << 'EOF'
+---
+description: My custom skill
+---
+
 # My Custom Skill
 
 This skill provides specialized knowledge for...
+EOF
+
+# Option 2: Create a skill folder directly
+mkdir -p .claude/skills/my-skill
+cat > .claude/skills/my-skill/SKILL.md << 'EOF'
+---
+name: my-skill
+description: My custom skill
+---
 
-## Usage
+# My Custom Skill
 
-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
+This skill provides specialized knowledge for...
 EOF
 
-# 2. Apply to all agents (skills enabled by default)
+# Apply to sync skills (runs bidirectional sync)
 skiller 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
+# Skills are now available to Claude Code via .claude/skills/
 ```
 
 ## `.gitignore` Integration

package/dist/constants.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SKILLZ_MCP_SERVER_NAME = exports.SKILL_MD_FILENAME = exports.SKILLZ_DIR = exports.CLAUDE_SKILLS_PATH = exports.SKILLS_DIR = exports.DEFAULT_RULES_FILENAME = exports.ERROR_PREFIX = void 0;
+exports.MAX_RECURSION_DEPTH = exports.SKILL_MD_FILENAME = exports.CLAUDE_SKILLS_PATH = exports.SKILLS_DIR = exports.DEFAULT_RULES_FILENAME = exports.ERROR_PREFIX = void 0;
 exports.actionPrefix = actionPrefix;
 exports.createSkillerError = createSkillerError;
 exports.logVerbose = logVerbose;
@@ -51,6 +51,6 @@ function logVerboseInfo(message, isVerbose, dryRun = false) {
 // Skills-related constants
 exports.SKILLS_DIR = 'skills';
 exports.CLAUDE_SKILLS_PATH = '.claude/skills';
-exports.SKILLZ_DIR = '.skillz';
 exports.SKILL_MD_FILENAME = 'SKILL.md';
-exports.SKILLZ_MCP_SERVER_NAME = 'skillz';
+// Security: Maximum recursion depth to prevent DoS via deeply nested directories
+exports.MAX_RECURSION_DEPTH = 50;

package/dist/core/ConfigLoader.js

@@ -78,8 +78,6 @@ const skillerConfigSchema = zod_1.z.object({
     skills: zod_1.z
         .object({
         enabled: zod_1.z.boolean().optional(),
-        generate_from_rules: zod_1.z.boolean().optional(),
-        prune: zod_1.z.boolean().optional(),
     })
         .optional(),
     rules: zod_1.z
@@ -233,11 +231,12 @@ async function loadConfig(options) {
     if (typeof rawSkillsSection.enabled === 'boolean') {
         skillsConfig.enabled = rawSkillsSection.enabled;
     }
-    if (typeof rawSkillsSection.generate_from_rules === 'boolean') {
-        skillsConfig.generate_from_rules = rawSkillsSection.generate_from_rules;
+    // Deprecation warnings for removed config options
+    if ('generate_from_rules' in rawSkillsSection) {
+        console.warn(`[skiller] Warning: skills.generate_from_rules is deprecated and has no effect. Skills are now edited directly in .claude/skills/`);
     }
-    if (typeof rawSkillsSection.prune === 'boolean') {
-        skillsConfig.prune = rawSkillsSection.prune;
+    if ('prune' in rawSkillsSection) {
+        console.warn(`[skiller] Warning: skills.prune is deprecated and has no effect. Skills in .claude/skills/ are never auto-deleted.`);
     }
     const rawRulesSection = raw.rules && typeof raw.rules === 'object' && !Array.isArray(raw.rules)
         ? raw.rules

package/dist/core/FileSystemUtils.js

@@ -47,6 +47,7 @@ const fs_1 = require("fs");
 const path = __importStar(require("path"));
 const os = __importStar(require("os"));
 const FrontmatterParser_1 = require("./FrontmatterParser");
+const constants_1 = require("../constants");
 /**
  * Gets the XDG config directory path, falling back to ~/.config if XDG_CONFIG_HOME is not set.
  */
@@ -172,12 +173,16 @@ function matchesPattern(filePath, pattern) {
 async function readMarkdownFiles(skillerDir, options) {
     const mdFiles = [];
     // Gather all markdown files (recursive) first
-    async function walk(dir) {
+    async function walk(dir, depth = 0) {
+        // Security: Prevent DoS via deeply nested directories
+        if (depth >= constants_1.MAX_RECURSION_DEPTH) {
+            return;
+        }
         const entries = await fs_1.promises.readdir(dir, { withFileTypes: true });
         for (const entry of entries) {
             const fullPath = path.join(dir, entry.name);
             if (entry.isDirectory()) {
-                await walk(fullPath);
+                await walk(fullPath, depth + 1);
             }
             else if (entry.isFile() &&
                 (entry.name.endsWith('.md') || entry.name.endsWith('.mdc'))) {
@@ -186,7 +191,7 @@ async function readMarkdownFiles(skillerDir, options) {
             }
         }
     }
-    await walk(skillerDir);
+    await walk(skillerDir, 0);
     // Apply include/exclude filters
     let filteredFiles = mdFiles;
     if (options?.include || options?.exclude) {
@@ -358,7 +363,11 @@ exports.findGlobalRulerDir = findGlobalSkillerDir;
 async function findAllSkillerDirs(startPath) {
     const skillerDirs = [];
     // Search the entire directory tree downwards from startPath
-    async function findSkillerDirsRecursive(dir) {
+    async function findSkillerDirsRecursive(dir, depth = 0) {
+        // Security: Prevent DoS via deeply nested directories
+        if (depth >= constants_1.MAX_RECURSION_DEPTH) {
+            return;
+        }
         try {
             const entries = await fs_1.promises.readdir(dir, { withFileTypes: true });
             for (const entry of entries) {
@@ -378,7 +387,7 @@ async function findAllSkillerDirs(startPath) {
                     else {
                         // Recursively search subdirectories (but skip hidden directories like .git)
                         if (!entry.name.startsWith('.')) {
-                            await findSkillerDirsRecursive(fullPath);
+                            await findSkillerDirsRecursive(fullPath, depth + 1);
                         }
                     }
                 }
@@ -389,7 +398,7 @@ async function findAllSkillerDirs(startPath) {
         }
     }
     // Start searching from the startPath
-    await findSkillerDirsRecursive(startPath);
+    await findSkillerDirsRecursive(startPath, 0);
     // Sort by depth (most specific first) - deeper paths come first
     skillerDirs.sort((a, b) => {
         const depthA = a.split(path.sep).length;

package/dist/core/FrontmatterParser.js

@@ -67,7 +67,10 @@ function parseFrontmatter(content) {
     const [, yamlContent, body] = match;
     try {
         // Try parsing YAML as-is first
-        const parsed = yaml.load(yamlContent);
+        // Use JSON_SCHEMA for safety - prevents YAML-specific type coercion attacks
+        const parsed = yaml.load(yamlContent, {
+            schema: yaml.JSON_SCHEMA,
+        });
         return extractFrontmatter(parsed, body);
     }
     catch {
@@ -91,7 +94,9 @@ function parseFrontmatter(content) {
             });
             // Try parsing again with fixed YAML
             if (fixedYaml !== yamlContent) {
-                const parsed = yaml.load(fixedYaml);
+                const parsed = yaml.load(fixedYaml, {
+                    schema: yaml.JSON_SCHEMA,
+                });
                 return extractFrontmatter(parsed, body);
             }
         }
@@ -134,6 +139,10 @@ function extractFrontmatter(parsed, body) {
         if (typeof parsed.alwaysApply === 'boolean') {
             frontmatter.alwaysApply = parsed.alwaysApply;
         }
+        // Extract name (for SKILL.md)
+        if (typeof parsed.name === 'string') {
+            frontmatter.name = parsed.name;
+        }
     }
     return {
         frontmatter,