ruff-sync 0.1.5.dev2__tar.gz → 0.1.5.dev4__tar.gz

ruff_sync-0.1.5.dev4/.agents/decisions/0001-type-refactoring-strategy.md

@@ -0,0 +1,36 @@
+# ADR 0001: Type Refactoring Strategy
+
+---
+status: accepted
+date: 2026-04-05
+decider: Agent
+---
+
+## Context
+
+The `ruff-sync` codebase, particularly the TUI and TOML merging logic, has historically relied on `dict[str, Any]` and deep `isinstance` checks. This makes the codebase difficult to maintain, prone to runtime errors, and provides poor IDE support.
+
+Based on the establishing `type-checking` skill, we need a strategic approach to "Complexity Shifting" and "Healthy Abstraction".
+
+## Decision
+
+We will implement a multi-phase type-refactoring strategy:
+
+1.  **Eliminate unstructured `dict[str, Any]`**: Introduce `TypedDict` for core payloads (Ruff rules, linters) in the TUI and System modules.
+2.  **Polymorphic TUI Widgets**: Replace recursive `isinstance(data, dict/list)` chains in widgets with structural polymorphism (e.g., `@singledispatchmethod` or a dedicated Node AST).
+3.  **Strategic Complexity (High-ROI typing)**: Apply strict typing (`tomlkit` bounds) to core infrastructure like `core.py` (TOML merging) while keeping feature code simple.
+4.  **Result Type Patterns**: Shift away from `Union[Success, Error]` with `isinstance` checks towards robust `Result` or tuple patterns.
+
+## Consequences
+
+- **Pros**:
+    - Improved static analysis via `mypy`.
+    - Better developer experience (autocompletion, go-to-definition).
+    - Reduced runtime "surprises" in complex TOML merges.
+- **Cons**:
+    - Initial "complexity tax" in core infrastructure types.
+    - Requires wrapping raw TOML data into structured nodes before rendering.
+
+## References
+
+- [type-checking skill](../skills/type-checking/SKILL.md)

ruff_sync-0.1.5.dev4/.agents/decisions/0002-tui-node-ast.md

@@ -0,0 +1,36 @@
+# ADR 0002: TUI Node AST Architecture
+
+---
+status: accepted
+date: 2026-04-05
+decider: Agent
+---
+
+## Context
+
+The TUI's configuration rendering (`widgets.py`) and selection logic (`app.py`) rely heavily on nested `isinstance` checks to navigate raw `dict`/`list` structures. This breaks down as the TOML structure becomes more complex (dotted keys, custom tables, list-of-tables).
+
+We need a way to shift "rendering complexity" into "data structure complexity" using the polymorphism principle from ADR 0001.
+
+## Decision
+
+We will implement a polymorphic **ConfigNode AST** for the TUI:
+
+1.  **`ConfigNode` Protocol**: A baseline interface (`path()`, `key()`, `children()`, `doc_target()`).
+2.  **Concrete Nodes**: `DictNode`, `ListNode`, `ScalarNode`, `LinterNode`, and `RulesCollectionNode`.
+3.  **Recursive Wrapping**: A `wrap_data()` factory that converts raw TOML data into a `ConfigNode` tree during initial load.
+4.  **UI-Layer Polymorphism**: Use `@singledispatchmethod` in widgets (e.g., `CategoryTable.render_node(node)`) to route rendering logic based on the node type, keeping Rich markup out of the model layer.
+
+## Consequences
+
+- **Pros**:
+    - Centralized documentation routing (`doc_target()`).
+    - Widgets no longer need to know "what" they are rendering, only "how" to render a `ConfigNode`.
+    - Eliminates fragile nested type-inference logic.
+- **Cons**:
+    - Requires an additional "wrapping" step during data load.
+    - Slightly more boilerplate in `src/ruff_sync/tui/types_.py`.
+
+## References
+
+- [ADR 0001: Type Refactoring Strategy](./0001-type-refactoring-strategy.md)

ruff_sync-0.1.5.dev4/.agents/decisions/README.md

@@ -0,0 +1,11 @@
+# ADR Index
+
+This is an internal record of architectural decisions for `ruff-sync`. These documents capture the historical "Why" for design choices made by both human and agentic developers.
+
+| ID | Date | Status | Title |
+| --- | --- | --- | --- |
+| [0001](./0001-type-refactoring-strategy.md) | 2026-04-05 | Accepted | Type Refactoring Strategy |
+| [0002](./0002-tui-node-ast.md) | 2026-04-05 | Accepted | TUI Node AST Architecture |
+
+---
+*For instructions on how to create or manage ADRs, see the [ADR Skill](../skills/adr/SKILL.md).*

ruff_sync-0.1.5.dev4/.agents/ruff.toml

@@ -0,0 +1,37 @@
+# Agents-specific ruff linter overrides.
+# This configuration applies to all files within the .agents/ directory.
+#
+# WHY AGENT SCRIPTS ARE TREATED DIFFERENTLY:
+# ------------------------------------------
+# 1. Faster iteration: Agent-related code (skills, scripts, and examples) is
+#    often experimental, short-lived, or used for automation.
+# 2. Lower maintenance: We relax requirements like module-level docstrings
+#    to maintain speed and reduce boilerplate.
+# 3. Local use: These scripts are usually run locally by the agent or developer
+#    rather than being part of the core production library.
+# 4. Prototyping: Allowing assert statements (S101) makes it easier to write
+#    concise validation for specialized agent workflows.
+# 5. Usage context for examples: We disable rules that move imports into
+#    if TYPE_CHECKING blocks because skill examples may be integrated into
+#    other applications in ways we cannot predict. Runtime access to
+#    imported objects is preserved to ensure compatibility with various
+#    application patterns (decorators, runtime reflection, etc).
+
+# Inherit root linter settings from the project's pyproject.toml.
+extend = "../pyproject.toml"
+
+[lint]
+# Specific overrides for agent python code, scripts, and skills.
+extend-ignore = [
+    "D100",   # missing-docstring-in-module - Agent scripts don't require module-level docstrings.
+    "D103",   # missing-docstring-in-public-function - Agent functions don't require public docstrings.
+    "S101",   # assert-statement - Asserts are preferred over other validation for internal agent scripts.
+
+    # Preserve runtime access for standalone examples and unknown integration:
+    # Disable rules that move imports into if TYPE_CHECKING: blocks.
+    "TC001",  # Move third-party import into a type-checking block
+    "TC002",  # Move third-party import into a type-checking block
+    "TC003",  # Move second-party import into a type-checking block
+    "TC004",  # Move first-party import into a type-checking block
+    "TC005",  # Move standard library import into a type-checking block
+]

ruff_sync-0.1.5.dev4/.agents/skills/adr/SKILL.md

@@ -0,0 +1,66 @@
+# ADR (Architectural Decision Record) Skill
+
+## Overview
+
+Use this skill to capture, manage, and reference significant architectural decisions for `ruff-sync`. ADRs are stored internally in `.agents/decisions/` and provide a historical record of "Why" things are designed the way they are.
+
+## When to Create an ADR
+
+Create an ADR when:
+- A significant architectural change is proposed (e.g., new internal AST, changing the merging strategy).
+- A long-running refactoring strategy is initiated (e.g., the Type-Checking Refactoring).
+- A decision is made that will impact future development and needs to be "remembered" by future agent sessions.
+- A "Implementation Plan" has been approved and reaches a level of architectural significance that warrants long-term persistence.
+
+## ADR Structure
+
+Each ADR should be named `NNNN-slug.md` (e.g., `0001-type-refactoring-strategy.md`) and located in `.agents/decisions/`.
+
+> [!IMPORTANT]
+> **Use relative paths for ALL internal links.** Never use absolute paths (`file:///Users/...`) as they are machine-specific and break in different environments.
+
+Use the following template:
+
+```markdown
+# ADR [NNNN]: [Short Title]
+
+---
+status: [proposed | accepted | superseded | deprecated]
+date: YYYY-MM-DD
+decider: [Agent | User]
+---
+
+## Context
+
+What is the problem we are trying to solve? What are the constraints?
+
+## Decision
+
+What are we doing? Be specific about the architectural shift.
+
+## Consequences
+
+What are the trade-offs? What will be easier? What will be harder?
+
+## References
+
+- Links to PRs or Issues (use `gh-issues` skill).
+- Links to other ADRs (e.g., "Supersedes [NNNN]").
+- Links to implementation plans or research.
+```
+
+## Workflows
+
+### 1. Creating a New ADR
+1. Identify the need for a persistent architectural record.
+2. Draft the ADR in `.agents/decisions/` using the next available number.
+3. Update `.agents/decisions/README.md` with the new entry.
+4. Reference the ADR in `AGENTS.md` if it represents a foundational shift.
+
+### 2. Superseding an ADR
+1. Create the new ADR (e.g., `0005`).
+2. Mark the old ADR (e.g., `0002`) as `status: superseded`.
+3. Add a link in the old ADR's `References` to the new one, and vice versa.
+
+### 3. Graduation
+Implementation plans in `.agents/` are often temporary. When a plan is completed, if its decisions are architecturally significant, "graduate" it by distilling its core decisions into an ADR.

ruff_sync-0.1.5.dev4/.agents/skills/mike/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: mike
+description: Use this skill to manage multiple versions of documentation for MkDocs-powered sites. Deploy new versions, update aliases (like 'latest' or 'stable'), set the default version for the site root, and manage versioned subdirectories in the deployment branch. Use this whenever the user wants to publish, version, or alias documentation, even if they don't explicitly mention "mike". Also use this when the user wants to troubleshoot or debug versioned documentation.
+---
+
+# mike: MkDocs Versioning
+
+`mike` is used in this project to manage a versioned documentation site, allowing side-by-side availability of `dev` (main branch) and stable release docs (e.g., `0.1.4`).
+
+## Prerequisites
+
+`mike` is included in the `docs` dependency group.
+```bash
+# Sync documentation dependencies
+uv sync --group docs
+```
+
+## Project Strategy
+
+This project follows a specific versioning strategy:
+1.  **`dev`**: Represents the current `main` branch.
+2.  **Stable Releases**: Versioned documentation (e.g., `0.1.4`) created upon release.
+3.  **`stable`**: An alias always pointing to the most recent non-dev release.
+4.  **`latest`**: An alias pointing to the most recent release (including dev, if applicable).
+
+## Theme Overrides
+
+To support the version switcher and custom banners, the project uses a `custom_dir` override in `mkdocs.yml`:
+
+```yaml
+theme:
+  name: material
+  custom_dir: docs/overrides
+```
+
+### Version switcher
+
+The version switcher is enabled via `extra.version.provider: mike`:
+
+```yaml
+extra:
+  version:
+    provider: mike
+```
+
+## Versioning Banner
+
+A custom banner is displayed when users are viewing the `dev` documentation. This is handled via `docs/overrides/main.html` and `docs/overrides/partials/version_warning.html`.
+
+### How it works:
+-   `main.html`: Extends the base template and includes the `version_warning.html` partial at the start of the `content` block.
+-   `version_warning.html`: Contains an HTML snippet that is hidden by default and shown via JavaScript if the URL path contains `/dev/`.
+
+Example in `version_warning.html`:
+```html
+<div id="version-warning" style="display: none;">
+  <div class="admonition warning">
+    <p class="admonition-title">Warning</p>
+    <p>
+      You are viewing the documentation for the <strong>development</strong> version.
+      The latest stable release can be found at <a href="https://kilo59.github.io/ruff-sync/">kilo59.github.io/ruff-sync</a>.
+    </p>
+  </div>
+</div>
+<script>
+  (function() {
+    const version_warning = document.getElementById("version-warning");
+    if (!version_warning) return;
+
+    // mike provides a 'mike' object with some metadata if available
+    // Otherwise fall back to checking the pathname
+    const isDev = window.location.pathname.includes("/dev/") ||
+                 (window.mike && typeof window.mike.version === 'string' && window.mike.version === "dev");
+
+    if (isDev) {
+      version_warning.style.display = "block";
+    }
+  })();
+</script>
+```
+
+### 1. Deploying Development Docs
+Run this from the `main` branch to update the `dev` version:
+```bash
+mike deploy dev --push --update-aliases
+```
+
+### 2. Deploying a Stable Release
+When a new version is released (e.g., `0.1.4`), deploy it and update the `stable` alias:
+```bash
+# Deploy the specific version and update 'stable'
+mike deploy 0.1.4 stable --push --update-aliases
+
+# Set 'stable' as the default version for the site root
+mike set-default --push stable
+```
+
+## Reference Commands
+
+| Action | Command |
+| :--- | :--- |
+| **Deploy** | `mike deploy <version> [alias]` |
+| **List** | `mike list` |
+| **Set Default** | `mike set-default <version>` |
+| **Alias** | `mike alias <version> <alias>` |
+| **Delete** | `mike delete <identifier>` |
+
+## CI/CD Integration
+
+The deployment logic is automated in [.github/workflows/ci.yaml](.github/workflows/ci.yaml). It automatically:
+- Extracts the version from `pyproject.toml`.
+- Deploys to `dev` if the version contains `.dev`.
+- Deploys to `<version>` and updates `stable` for official releases.
+
+> [!IMPORTANT]
+> **Do NOT** use `mike install-gh-pages`. It is deprecated and removed in the version used by this project. `mike deploy` handles branch initialization automatically.
+
+> [!TIP]
+> Use `mike serve` locally to preview the version switcher before pushing changes.
+
+## Troubleshooting
+
+### Version Selector Not Appearing
+- **Missing `versions.json`**: Ensure `mike deploy` or `mike update-aliases` has been run. The file must exist at the site root.
+- **Incomplete `versions.json`**: If the current page's version (e.g., `stable`) is not listed in `versions.json`, some themes (like Material) may hide the selector.
+- **`site_url` Case Sensitivity**: On GitHub Pages, ensure `site_url` in `mkdocs.yml` matches the actual deployment URL (usually lowercase). Discrepancies can cause the switcher to fail to find `versions.json` due to 404s.
+- **Redundant Config**: Ensure `theme.version` is NOT set in `mkdocs.yml`. Use `extra.version.provider: mike` instead.
+- **`canonical_version` Missing**: If the switcher is hidden on the root page, adding `canonical_version: stable` (or your main alias) to the `mike` plugin configuration can help the theme associate the root with the switcher metadata.
+
+### 404 for `versions.json`
+- If you see a 404 for `/versions.json` but `https://<user>.github.io/<repo>/versions.json` exists, the switcher is looking at the domain root instead of the project root. Verify `site_url` includes the repository name and has a trailing slash.
+
+## Post-Mortem & Known Issues
+
+> [!CAUTION]
+> **Current Status**: Documentation versioning is currently **BROKEN** on the live site (`kilo59.github.io/ruff-sync`).
+
+### Failed Repair History
+The following fixes have been attempted and **FAILED** to resolve the issue:
+1.  **Lowercasing `site_url`**: Normalizing the repository name in the URL (e.g., `ruff-sync` instead of `Ruff-Sync`) did not fix the 404s for `versions.json`.
+2.  **Removing `theme.version`**: Removing the redundant Material 9.x config did not restore the switcher.
+3.  **Adding `canonical_version: stable`**: Adding this to the `mike` plugin in `mkdocs.yml` was intended to fix path resolution but has not fixed the root page 404.
+4.  **CI Restoration Logic**: Adding `mike alias --push stable stable` to the CI to manually repair `versions.json` hasn't restored the picker on the root page.
+
+### Root Cause Suspicions
+- **GitHub Pages Subfolder Pathing**: The site is served from a subfolder (`/ruff-sync/`). `mike`'s JavaScript for the version switcher frequently struggles with calculating relative paths to `versions.json` when served from a subfolder if `site_url` or base paths are not perfectly aligned with the deployment environment.
+- **`versions.json` Drift**: The `versions.json` file on the `gh-pages` branch frequently becomes desynchronized or loses the `stable` entry, which triggers `mkdocs-material` to hide the switcher entirely.
+
+### Guidance for Future Agents
+Before attempting another "fix," you **MUST** verify the current state of `versions.json` on the `gh-pages` branch and check the browser console on the live site for 404 paths. Do not assume standard configurations will work without manual verification of the deployed assets.

{ruff_sync-0.1.5.dev2 → ruff_sync-0.1.5.dev4}/.agents/skills/mkdocs-generation/templates/api-reference.md

@@ -26,7 +26,7 @@ For nested API structure, create subdirectories:
 docs/api/
 ├── index.md      - API overview
 ├── client.md     - ::: package.client.Client
-├── models.md     - ::: package.models
+├── types_.md      - ::: package.types_
 └── entities/
     ├── user.md   - ::: package.entities.User
     └── item.md   - ::: package.entities.Item

{ruff_sync-0.1.5.dev2 → ruff_sync-0.1.5.dev4}/.agents/skills/mkdocs-generation/templates/mkdocs.yml

@@ -59,4 +59,4 @@ nav:
 #       - Overview: api/index.md
 #       - Core:
 #           - Client: api/client.md
-#           - Models: api/models.md
+#           - Types: api/types_.md

ruff_sync-0.1.5.dev4/.agents/skills/skill-creator/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: skill-creator
+description: >-
+  Create or update Agent Skills to extend capabilities for specific tasks,
+  frameworks, or domain-specific workflows. Use this when the user asks to
+  "add a skill," "create a tool for X," or "teach the agent how to Y."
+---
+
+# Skill Creator Meta-Skill
+
+This skill provides a systematic approach to creating and optimizing "Agent Skills" within the `.agents/skills/` directory.
+
+## Available Scripts
+
+- **`scripts/scaffold_skill.py`**: Automated scaffolding for new Agent Skill directories and `SKILL.md` templates.
+
+## Workflow
+
+1. **Scaffold the Skill**:
+   - Run the scaffolding script to create the directory structure:
+     ```bash
+     uv run .agents/skills/skill-creator/scripts/scaffold_skill.py <name> \\
+       --description "user intent" \\
+       --keywords "key, word"
+     ```
+   - This creates `.agents/skills/<name>/SKILL.md` and standard subdirectories.
+
+2. **Research & Plan**:
+   - Check existing skills in `.agents/skills/` to prevent duplication. Identify if an existing skill can just be extended instead of creating a new one.
+   - **Research Tool Usage**: Prioritize `search_web` and `read_url_content` for gathering information. Use the browser subagent (`read_browser_page`) only as a last resort for sites requiring JavaScript or authentication.
+   - Determine the scope of the skill (e.g., CLI wrapper, documentation guide, testing helper).
+   - Identify existing project artifacts (style guides, API specs, CI workflows) to pull information from.
+   - Design a test case or a set of "should-trigger" queries.
+   - See [references/quickstart.md](references/quickstart.md) for the basic structure.
+
+3. **Define Frontmatter**:
+   - `name`: Must match the folder name in `.agents/skills/`.
+   - `description`: Write an imperative, user-intent-focused description.
+   - See [references/optimizing-descriptions.md](references/optimizing-descriptions.md) for optimization tips.
+
+4. **Develop the Procedure & Scripts**:
+   - Favor procedural instructions ("To do X, run Y") over declarative ones.
+   - Bundle complex logic in `scripts/` using [references/using-scripts.md](references/using-scripts.md). Ensure any helper scripts are robust (add type hints, lint with `ruff`, and consider unit tests).
+   - Include a "Quick Start" section for the most common use case.
+   - Use checklists for multi-step workflows.
+
+5. **Progressive Disclosure (PD)**:
+   - **Procedural Entry Point**: Keep the main `SKILL.md` strictly procedural (The "How-To") and under 110 lines.
+   - **Offload Details**: Move illustrative recipes, deep-dive code examples, technical deep-dives, and troubleshooting logs to a `references/` subdirectory.
+   - See [references/best-practices.md](references/best-practices.md) for structuring tips.
+
+6. **Validation & Iteration**:
+   - Run the prompt *with* and *without* the skill instructions.
+   - Use [references/evaluating-skills.md](references/evaluating-skills.md) to grade outputs with assertions.
+   - Add a "Gotchas" section to address common pitfalls.
+   - Iterate on instructions based on failed assertions or high variance.
+
+7. **Global Knowledge Sync**:
+   - If the new skill introduces fundamental rules or overarching context that all agents *must* inherently know *before* using the skill, add a very brief mention in `AGENTS.md`.
+   - **Caution**: Do not bloat `AGENTS.md`. Only link to the skill or summarize the rule in 1-2 sentences. Keep the detailed documentation inside the skill folder.
+
+## Skill Quality Checklist
+
+- [ ] **Frontmatter**: Does the name match the directory name?
+- [ ] **Description**: Is it imperative ("Use this skill when...") and under 1024 characters?
+- [ ] **Procedural**: Does it provide clear, actionable steps for the agent to follow?
+- [ ] **Context**: Does it include project-specific context (e.g., using `uv run`, `gh`, `ruff`)?
+- [ ] **Specificity**: Does the level of detail match the fragility of the task?
+- [ ] **Overlap**: Is the domain distinct enough that it doesn't overlap excessively with existing skills?
+- [ ] **Global Sync**: Have overarching project rules been bubbled up to `AGENTS.md` (while avoiding bloat)?
+- [ ] **PD Audit**: Is the main file under 110 lines and free of dense examples/logic trees?
+- [ ] **Quick Start**: Does the main file have a "Quick Start" section for the primary use case?
+- [ ] **Research Efficiency**: Did you prioritize fast tools (`search_web`/`read_url_content`) over the slow browser subagent for research?
+
+## References
+
+- [Quickstart](references/quickstart.md) — Basic SKILL.md structure
+- [Best Practices](references/best-practices.md) — How to scope and calibrate skills
+- [Optimizing Descriptions](references/optimizing-descriptions.md) — Reliable triggering strategies
+- [Evaluating Skills](references/evaluating-skills.md) — Eval-driven iteration and assertions
+- [Using Scripts](references/using-scripts.md) — Bundling logic and agentic script design
+- [Research Sources](references/sources.md) — External documentation used to create this skill

ruff_sync-0.1.5.dev4/.agents/skills/skill-creator/references/best-practices.md

@@ -0,0 +1,56 @@
+# Best Practices for Skill Creation
+
+How to write skills that are well-scoped and calibrated to the task.
+
+## 1. Spending Context Wisely
+
+**Add what the agent lacks, omit what it knows.**
+- **Bad**: "PDF (Portable Document Format) is a common file format..." (The agent knows this).
+- **Good**: "Use `pdfplumber` for text extraction. For scans, fall back to `pytesseract`." (This is project-specific guidance).
+
+## 2. Match Specificity to Fragility
+
+**Low fragility (General task)**:
+- Provide high-level goals and examples.
+- Allow the agent to decide the best path (e.g., "Check database queries for SQLi...").
+
+**High fragility (Specific/Dangerous task)**:
+- Provide exact command sequences.
+- Add warnings: "Do not modify flags or skip steps."
+- Example: "Run exactly `python migrate.py --verify --backup`."
+
+## 3. Favor Procedures over Declarations
+
+- **Bad**: "This skill manages database migrations."
+- **Good**: "To perform a migration: 1. Run script A. 2. Verify output B. 3. Update file C."
+- Use checklists for multi-step workflows to help the agent track progress.
+
+## 4. Progressive Disclosure
+
+**Spending context wisely: Main file = Procedural. References = Illustrative.**
+- **Limit**: Keep the main `SKILL.md` under **110 lines**.
+- **The Entry Point**: Focus strictly on the "How-To" (workflows, checklists, high-level procedures).
+- **The References**: Move anything that is "Illustrative" or "Dense" to the `references/` directory. This includes:
+  - Complex decision trees or logic tables.
+  - Multi-line code examples/recipes.
+  - Full API references or error-code lookups.
+  - Troubleshooting logs or edge-case post-mortems.
+- This ensures the agent is only "weighed down" by relevant context when needed.
+
+## 5. Gotchas & Common Pitfalls
+
+- Include a "Gotchas" section to address recurring issues.
+- Document reasons *why* certain approaches are forbidden (e.g., "Do not use library X because of security vulnerability Y").
+- Link to troubleshooting guides for deeper dives.
+
+## 6. Plan-Validate-Execute Loops
+
+- Instruct the agent to create a plan first.
+- Provide validation scripts to check work before "committing" (e.g., linting, type-checking, or running a validator).
+
+## 7. Research Performance
+
+**Prioritize fast, text-based tools over the browser.**
+- **Fast**: Use `search_web` and `read_url_content` for documentation and general research.
+- **Slow**: Avoid `read_browser_page` (browser subagent) unless the target site is a single-page app (SPA) that requires JavaScript rendering or authentication.
+- **Guideline**: If you can see the content with a simple `curl`-like tool, do not spin up a browser. This saves significant time and keeps the agent focused.

ruff_sync-0.1.5.dev4/.agents/skills/skill-creator/references/evaluating-skills.md

@@ -0,0 +1,49 @@
+# Evaluating Skill Quality
+
+"Eval-driven iteration" is the process of testing your skill against realistic prompts to ensure it produces high-quality, reliable outputs.
+
+## 1. Designing Test Cases
+
+A good test case includes:
+- **Prompt**: A realistic user message (e.g., "Analyze the CSV at data/sales.csv").
+- **Expected Output**: A human-readable description of success.
+- **Input Files**: Mock data or real project files needed for the task.
+- **Assertions**: Specific, observable criteria for success.
+
+### Example Eval (evals.json)
+```json
+{
+  "id": 1,
+  "prompt": "Summarize the linting errors in src/core.py",
+  "expected_output": "A markdown table with Error Code, Message, and Line Number.",
+  "assertions": [
+    "Output is a markdown table",
+    "Includes at least 3 columns",
+    "All error codes start with 'E' or 'W'"
+  ]
+}
+```
+
+## 2. Running Evals
+
+**The Loop**:
+1. **Baseline**: Run the prompt *without* the new skill instructions.
+2. **With Skill**: Run same prompt with the skill active.
+3. **Compare**: Measure the delta in quality, time, and tokens.
+
+**Workspace Structure**:
+Store iteration results in separate folders (e.g., `iteration-1/with_skill/outputs/`) to track progress over time.
+
+## 3. Grading with Assertions
+
+- **Programmatic**: "Output is valid JSON."
+- **Observable**: "The chart has labeled axes."
+- **Countable**: "Includes at least 3 recommendations."
+
+**Grading Principle**: Require concrete evidence for a PASS. If it's vague, it's a FAIL.
+
+## 4. Analyzing Patterns
+
+- **High StdDev**: If results vary wildly across runs, the instructions may be too ambiguous.
+- **Plateau**: If more rules don't improve the pass rate, the skill may be over-constrained. Try simplifying.
+- **Delta**: Focus on where the skill actually changes the agent's behavior compared to the baseline.

ruff_sync-0.1.5.dev4/.agents/skills/skill-creator/references/optimizing-descriptions.md

@@ -0,0 +1,29 @@
+# Optimizing Skill Descriptions
+
+The `description` field in a Skill's frontmatter determines *if* the agent chooses to use the skill.
+
+## 1. Writing Effective Descriptions
+
+- **Imperative Phrase**: Use "Use this skill when..." rather than "This skill does...".
+- **Focus on User Intent**: Describe what the user wants to achieve (e.g., "Analyze CSVs") rather than internal mechanics ("Run `scripts/csv_parser.py`").
+- **Err on the Side of Being Pushy**: Explicitly list contexts where the skill applies, including synonyms (e.g., "even if they don't explicitly mention 'CSV' or 'analysis'").
+- **Concise & Goal-Oriented**: A short paragraph (<1024 chars) is usually right.
+
+## 2. Avoiding Overfitting
+
+- **Broaden the Scope**: If you miss a "should-trigger" case, broaden the description.
+- **Avoid Keyword Stuffing**: Don't just add words from failed queries. Identify the *general category* those words represent.
+- **Structural Changes**: If tweaks fail, try a different framing or sentence structure.
+
+## 3. Testing with Queries
+
+- **Should-Trigger Queries**: Test with formal, casual, and typo-ridden prompts.
+- **Should-Not-Trigger Queries**: Test with "near-misses" (e.g., "I need to edit Excel budget" vs "I need to analyze CSV sales").
+- **Validation Pass Rate**: Use fresh queries (not the ones used to train/optimize) to check for generalization.
+
+## Checklist for Activation
+
+- [ ] Is it under 1024 characters? (Hard limit)
+- [ ] Does it start with "Use this skill when..."?
+- [ ] Does it cover at least 3-4 likely phrasing variations?
+- [ ] Is it separate from other skills in the same repository? (Avoid overlap)

ruff_sync-0.1.5.dev4/.agents/skills/skill-creator/references/quickstart.md

@@ -0,0 +1,64 @@
+# Skill Creation Quickstart
+
+A "Skill" is a directory containing a `SKILL.md` file that provides instructions to an agent.
+
+## Basic Structure
+
+Create your skill at `.agents/skills/<name>/SKILL.md`:
+
+```markdown
+---
+name: <name>
+description: >-
+  Use this skill when <user intent/achievement>.
+  Trigger on <keywords/context>.
+---
+
+# <Title>
+
+<High-level overview of the skill's purpose.>
+
+## Quick Start
+
+```bash
+# Provide the most common command or procedure
+<command>
+```
+
+## Common Workflows
+
+### Workflow 1
+
+- [ ] Step 1: <action>
+- [ ] Step 2: <action>
+- [ ] Step 3: <action>
+
+## Gotchas
+
+- **<pitfall>**: <resolution>
+- **<limitation>**: <alternative>
+
+## References
+
+- [Reference 1](references/ref1.md)
+- [Reference 2](references/ref2.md)
+```
+
+## Directory Layout
+
+```text
+.agents/skills/<name>/
+  SKILL.md              # Entry point (Frontmatter + Core Instructions)
+  references/           # (Optional) Detailed guides
+    config.md
+    troubleshooting.md
+  scripts/              # (Optional) Reusable scripts
+    scaffold.py
+  assets/               # (Optional) Static assets or images
+```
+
+## Activation Rules
+
+1. **Frontmatter**: The `name` must match the parent folder exactly.
+2. **Detection**: The agent reads the `description` at the start of a session. It only loads the full `SKILL.md` when it decides to "activate" based on the user's request.
+3. **Imperative Phrase**: Always start descriptions with "Use this skill when..." to help the agent decide.

ruff_sync-0.1.5.dev4/.agents/skills/skill-creator/references/sources.md

@@ -0,0 +1,18 @@
+# External Research Sources
+
+These sources were used to build the initial version of the `skill-creator` meta-skill. Refer to them whenever recommendations change.
+
+**Last Updated**: 2026-04-05 (Meta-skill created)
+
+## Official Documentation
+
+- **[Quickstart](https://agentskills.io/skill-creation/quickstart)** — Basic structure and directory layout.
+- **[Best Practices](https://agentskills.io/skill-creation/best-practices)** — Scoping, calibration, and procedural instructions.
+- **[Optimizing Descriptions](https://agentskills.io/skill-creation/optimizing-descriptions)** — Imperative phrasing and reliable triggering strategies.
+- **[Evaluating Skills](https://agentskills.io/skill-creation/evaluating-skills)** — Eval-driven iteration and assertion-based grading.
+- **[Using Scripts](https://agentskills.io/skill-creation/using-scripts)** — Bundling executable logic and agentic script design.
+
+## Maintenance Policy
+
+- **Check regularly**: Periodically visit these URLs to see if new "Gotchas" or pattern recommendations have been added.
+- **Update Workflow**: If a source is updated, update the corresponding reference file in this skill.