ruff-sync 0.1.5.dev3__tar.gz → 0.1.5.dev5__tar.gz

ruff_sync-0.1.5.dev5/.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.dev5/.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.dev5/.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.dev5/.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.dev5/.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.dev3 → ruff_sync-0.1.5.dev5}/.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.dev3 → ruff_sync-0.1.5.dev5}/.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.dev3 → ruff_sync-0.1.5.dev5}/.agents/skills/ruff-sync-usage/references/ci-integration.md

@@ -12,7 +12,10 @@ Add this step to any existing workflow (e.g., `.github/workflows/ci.yaml`):
 ```
 
 `--semantic` ignores cosmetic differences (comments, whitespace) — only real value or rule changes cause failure.
-`--output-format github` creates inline PR annotations for errors and warnings.
+`--output-format github` creates inline PR annotations and a structured Job Summary report.
+
+> [!TIP]
+> `ruff-sync` automatically groups multiple drifts in the same file into a single annotation to reduce PR noise.
 
 ### Full Workflow Example
 
@@ -73,7 +76,13 @@ For repositories with GitHub Advanced Security enabled, upload SARIF results to
 The `|| true` ensures the upload step always runs even when `ruff-sync` exits 1 (drift detected). Without it, GitHub Actions would skip the upload step on failure.
 
 > **Why SARIF over `--output-format github`?**
-> The `github` format creates ephemeral workflow annotations that disappear once the check re-runs. SARIF findings are persisted in the Security tab, tracked as "introduced" and "resolved" across branches, and each drifted TOML key (`lint.select`, `target-version`, etc.) is a separate finding with a stable fingerprint — making it easy to trend configuration health over time.
+>
+> | Feature | `github` | `sarif` |
+> |---------|----------|---------|
+> | **PR Feedback** | Inline annotations (grouped) | Inline annotations (per-key) |
+> | **Job Summary** | ✅ Markdown table | ❌ (requires separate parsing) |
+> | **Persistence** | Ephemeral (until re-run) | Persistent (Security tab) |
+> | **Tracking** | Manual | Automated "introduced/resolved" |
 
 ---
 

ruff_sync-0.1.5.dev5/.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.dev5/.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.dev5/.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.dev5/.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.dev5/.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.dev5/.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.

ruff_sync-0.1.5.dev5/.agents/skills/skill-creator/references/using-scripts.md

@@ -0,0 +1,59 @@
+# Using Scripts in Skills
+
+Bundling executable logic within your skills makes them more powerful and reliable than instruction-only skills.
+
+## 1. One-off Commands
+
+Use tool runners to invoke common utilities without pre-installing them.
+- **Python**: `uvx ruff check .` or `pipx run black .`
+- **Node.js**: `npx eslint@9 --fix .`
+- **Go**: `go run golang.org/x/tools/cmd/goimports@latest .`
+
+**Pin versions** (e.g., `eslint@9.0.0`) for reproducibility.
+
+## 2. Self-Contained Scripts (`scripts/`)
+
+For complex logic, bundle a script in the `scripts/` directory.
+
+### Python (PEP 723)
+Use inline dependency metadata so the script is self-documenting and runnable via `uv run`.
+
+```python
+# /// script
+# dependencies = [
+#     "httpx",
+#     "rich",
+# ]
+# ///
+import httpx
+from rich import print
+
+# ... script logic ...
+```
+
+### Deno / Bun
+TypeScript runs natively without `package.json`.
+- **Deno**: `deno run --allow-read scripts/process.ts`
+- **Bun**: `bun run scripts/process.ts`
+
+## 3. Designing for Agentic Use
+
+- **No Interactive Prompts**: Scripts should fail with a clear error and usage instructions rather than hanging for input.
+- **Helpful `--help`**: Ensure the agent can run `python scripts/my_script.py --help` to understand flags and examples.
+- **Structured Output**: Prefer JSON or CSV over whitespace-aligned tables for easier parsing by the agent.
+- **Idempotency**: "Create if not exists" is safer than failing on duplicates, as agents may retry commands.
+- **Meaningful Exit Codes**: Use distinct codes for "Not Found," "Invalid Args," and "System Error."
+
+## 4. Referencing from SKILL.md
+
+Document the available scripts clearly in your core instructions:
+
+```markdown
+## Available Scripts
+- **`scripts/validate.py`**: Validates input data and returns a JSON report.
+- **`scripts/generate_chart.py`**: Creates a bar chart from the validation report.
+
+## Workflow
+1. Run validation: `uv run scripts/validate.py input.json` -> `results.json`.
+2. Generate chart: `uv run scripts/generate_chart.py results.json`.
+```