ruff skill

docs/architecture.md

@@ -124,7 +124,7 @@ Repository indexing metadata is declared in `x-personal-mcp`:
 3. tags
 4. capabilities
 5. depends_on
-6. references map (ref id to relative path and optional metadata)
+6. optional references map (for nested entries, overrides, and aliases)
 
 No `metadata.yaml` sidecar is part of the end-state contract.
 
@@ -143,7 +143,9 @@ For the full URI semantics, parameter validation rules, and compatibility policy
 Validation rules:
 
 1. `skill_id` is lowercase kebab-case and must satisfy the stable skill id contract.
-2. `ref_id` is lowercase kebab-case and must be declared in the skill references manifest.
+2. `ref_id` is lowercase kebab-case and must resolve from either:
+    - top-level auto-discovery of `references/*.md` filename stems, or
+    - an explicit `x-personal-mcp.references` entry.
 3. `path*` resolves only to normalized markdown paths under `docs/`.
 
 ### Resource Registration Contract

docs/content.md

@@ -43,7 +43,7 @@ Rules:
 
 1. Skill metadata is embedded in YAML frontmatter in `SKILL.md`.
 2. No `metadata.yaml` sidecar exists in the end state.
-3. Reference lookup metadata, including reference id to relative path mappings, is declared from `SKILL.md` frontmatter rather than inferred as a hidden global convention.
+3. Reference lookup metadata is documented and explicit: top-level `references/*.md` are auto-discovered from filenames, while `SKILL.md` frontmatter declares overrides and nested mappings when needed.
 
 ## Skill Id Contract
 

docs/frontmatter.md

@@ -107,6 +107,28 @@ Reference entry rules:
 6. `title` is an optional display label.
 7. Renaming `ref-id` values is allowed when needed; optional aliases may be used during transitions.
 
+## Auto-Generated Reference IDs
+
+Top-level markdown files directly under `references/` are auto-registered as MCP references even when `x-personal-mcp.references` is empty.
+
+How `ref-id` is derived:
+
+1. Start from the filename stem (without `.md`).
+2. Normalize to lowercase kebab-case.
+3. Publish at `resource://skills/<skill-id>/references/<ref-id>`.
+
+Examples:
+
+1. `references/ruff-docs.md` -> `ref-id: ruff-docs`
+2. `references/Ruff Integrations.md` -> `ref-id: ruff-integrations`
+3. `references/python_logging_docs.md` -> `ref-id: python-logging-docs`
+
+When to use explicit `x-personal-mcp.references` entries:
+
+1. The file is nested, for example `references/guides/ci.md`.
+2. You need to override defaults (`title`, `mime_type`, or custom `ref-id`).
+3. You need compatibility aliases during a rename.
+
 ## Validation Models
 
 The normative model uses Pydantic v2 with change-friendly validation:

docs/skills/new-skill/SKILL.md

@@ -19,14 +19,15 @@ x-personal-mcp:
 
 # New Skill Bootstrap
 
-Use this skill to bootstrap a new skill in the docs-first architecture.
+Use this skill to bootstrap a new skill in the docs-first architecture. Try to use the `/create-skill` where possible to structure the output, but place it alongside the other skills in this repo.
 
 ## Scope
 
 1. Create docs under docs/skills/<skill-id>/.
 2. Define SKILL frontmatter with Anthropic and x-personal-mcp fields.
-3. Declare references via x-personal-mcp.references when needed.
+3. Treat top-level `references/*.md` as auto-discovered references with `ref-id` generated from filename.
-4. Validate the docs build and MCP resource reads.
+4. Declare `x-personal-mcp.references` only when you need overrides or nested `references/**` entries.
+5. Validate the docs build and MCP resource reads.
 
 ## Authoring Checklist
 
@@ -35,6 +36,8 @@ Use this skill to bootstrap a new skill in the docs-first architecture.
 3. Keep skill id and directory name aligned.
 4. Keep frontmatter name equal to x-personal-mcp.id.
 5. Include resource://skills/<skill-id>/document in capabilities.
+6. For each top-level `references/<name>.md`, expect `resource://skills/<skill-id>/references/<name>` (normalized to lowercase kebab-case).
+7. Add explicit `x-personal-mcp.references` entries only for nested paths or metadata overrides.
 
 ## Validation
 

docs/skills/ruff-linting-formating/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: ruff-linting-formating
+description: "Reference-first Ruff skill for repository preferences, baseline defaults, and source links. Use to pick consistent Ruff conventions and integration references, not to run migration playbooks."
+argument-hint: "Which Ruff preferences or integrations are you deciding (rules, formatting, pre-commit, GitHub Actions)?"
+x-personal-mcp:
+  id: ruff-linting-formating
+  version: 1.0.0
+  tags:
+    - ruff
+    - linting
+    - formatting
+    - python
+    - ci
+  capabilities:
+    - resource://skills/ruff-linting-formating/document
+  depends_on: []
+---
+
+# Ruff Preferences and References
+
+Use this skill as a reference index for Ruff preferences, conventions, and source documentation.
+
+This document is intentionally not a migration or transition playbook.
+
+Load references only when needed:
+- Ruff core documentation: [Ruff docs](./references/ruff-docs.md)
+- Tooling integrations (pre-commit and GitHub Actions): [Ruff integrations](./references/ruff-integrations.md)
+
+## When To Use
+
+- You want canonical Ruff preferences for this repository context.
+- You need source links for rule selection, formatter behavior, and integrations.
+- You are deciding configuration defaults, not planning a migration sequence.
+
+## Preference Baseline
+
+Use these as default preferences unless the target repository states otherwise:
+
+1. Keep linting and formatting both enabled.
+2. Keep imports sorted via Ruff (`I` rules) rather than a separate import tool.
+3. Prefer explicit, small rule-family selection first (`E`, `F`, `I`, `UP`) and expand deliberately.
+4. Keep line length, target Python, and formatter settings aligned to repository policy.
+5. Keep local and CI execution behavior equivalent.
+
+### Rule Link Requirement
+
+When adding a specific rule or ruleset to `ruff.toml`, search for the authoritative Ruff documentation page for that rule or ruleset and include a link to it. You may add the URL as a nearby comment in `ruff.toml` or record it in the repository docs (for example in a CONTRIBUTING or linting section). Prefer links to the official [Ruff rules reference](https://docs.astral.sh/ruff/rules/).
+
+### Version Discovery Requirement
+
+When integrating Ruff or any third-party Action for the first time, always search for the latest stable release of:
+
+- the `ruff` package ([releases](https://github.com/astral-sh/ruff/releases))
+- the `astral-sh/ruff-pre-commit` hook ([releases](https://github.com/astral-sh/ruff-pre-commit/releases))
+- the `astral-sh/ruff-action` ([releases](https://github.com/astral-sh/ruff-action/releases))
+- the `astral-sh/setup-uv` action ([releases](https://github.com/astral-sh/setup-uv/releases))
+
+Document the version you chose in the example snippet or in a nearby docs file and prefer pinning to a released tag in CI examples. If you intentionally use `latest`, note the reason and the associated risk in repo docs.
+
+## Decision Inputs
+
+Collect only the minimum context needed for preference decisions:
+
+1. Supported Python versions.
+2. Existing `pyproject.toml` constraints.
+3. CI provider and required checks.
+4. Whether pre-commit is in use.
+
+## Template
+
+[Full template ruff.toml](https://gitea.john-stream.com/john/python-template/src/branch/main/project/ruff.toml)
+
+```toml title="Preferred Baseline"
+line-length = 120
+indent-width = 4
+target-version = "py313"
+
+exclude = [
+  ".git",
+  ".venv",
+  ".devenv",
+]
+
+[lint]
+extend-fixable = ["ALL"]
+extend-select = [
+    "C4",       # https://docs.astral.sh/ruff/rules/#flake8-comprehensions-c4
+    "E", "W",   # https://docs.astral.sh/ruff/rules/#pycodestyle-e-w
+    "F",        # https://docs.astral.sh/ruff/rules/#pyflakes-f
+    "FURB",     # https://docs.astral.sh/ruff/rules/#refurb-furb
+    "I",        # https://docs.astral.sh/ruff/rules/#isort-i
+    "N",        # https://docs.astral.sh/ruff/rules/#pep8-naming-n
+    "PD",       # https://docs.astral.sh/ruff/rules/#pandas-vet-pd
+    "PTH",      # https://docs.astral.sh/ruff/rules/#flake8-use-pathlib-pth
+    "UP",       # https://docs.astral.sh/ruff/rules/#pyupgrade-up
+    "SIM",      # https://docs.astral.sh/ruff/rules/#flake8-simplify-sim
+]
+
+[lint.isort]
+force-single-line = true
+
+[format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "auto"
+```
+
+## Reference Map
+
+1. Rules and settings source of truth: [Ruff docs](./references/ruff-docs.md)
+2. pre-commit and GitHub Actions examples: [Ruff integrations](./references/ruff-integrations.md)
+3. Template to copy from or compare against: [python-template ruff.toml](https://gitea.john-stream.com/john/python-template/src/branch/main/project/ruff.toml)
+
+## Non-Goals
+
+This skill does not define:
+
+1. Step-by-step migration phases.
+2. Rollout modes or cutover timelines.
+3. Mechanical rewrite plans for legacy tooling.

docs/skills/ruff-linting-formating/references/ruff-docs.md

@@ -0,0 +1,31 @@
+# Ruff Source Documentation
+
+Use this reference when implementing or tuning Ruff in repositories.
+
+## Core Docs
+
+- [Ruff overview](https://docs.astral.sh/ruff/)
+- [Rules reference](https://docs.astral.sh/ruff/rules/)
+- [Settings reference](https://docs.astral.sh/ruff/settings/)
+- [Formatter docs](https://docs.astral.sh/ruff/formatter/)
+- [The Ruff linter](https://docs.astral.sh/ruff/linter/)
+
+## Migration And Integration
+
+- [Migrating from Black](https://docs.astral.sh/ruff/formatter/#migrating-from-black)
+- [Migrating from Flake8](https://docs.astral.sh/ruff/linter/#migrating-from-flake8)
+- [Migrating from isort](https://docs.astral.sh/ruff/formatter/#sorting-imports)
+- [Pre-commit integration](https://docs.astral.sh/ruff/integrations/#pre-commit)
+- [GitHub Actions integration](https://docs.astral.sh/ruff/integrations/#github-actions)
+
+## Python Packaging Context
+
+- [PEP 621 project metadata in pyproject.toml](https://peps.python.org/pep-0621/)
+- [uv project and workflow docs](https://docs.astral.sh/uv/)
+
+## Suggested Reading Order
+
+1. Overview and settings.
+2. Rules and linter behavior.
+3. Formatter and migration references.
+4. CI and pre-commit integration notes.

docs/skills/ruff-linting-formating/references/ruff-integrations.md

@@ -0,0 +1,128 @@
+# Ruff Integrations: Tooling Patterns
+
+Use this page when wiring Ruff into local developer workflows and CI.
+
+## Scope
+
+This reference covers:
+
+1. [pre-commit](https://pre-commit.com/) hooks for local and pre-push enforcement.
+2. [GitHub Actions](https://docs.github.com/en/actions) checks for pull request and branch protection gates.
+
+For Ruff-specific flags and settings, see [Ruff docs](./ruff-docs.md).
+
+## pre-commit Integration
+
+### Why use it
+
+Use pre-commit when you want fast feedback before code reaches CI and consistent checks across contributors.
+
+### Add hooks
+
+Create or update [.pre-commit-config.yaml](https://pre-commit.com/#2-add-a-pre-commit-configuration) with Ruff hooks from [astral-sh/ruff-pre-commit](https://github.com/astral-sh/ruff-pre-commit):
+
+```yaml title=".pre-commit-config.yaml"
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.18
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+```
+
+Pin the hook revision and update intentionally during dependency maintenance.
+
+### Install and run
+
+```bash
+uv run pre-commit install
+uv run pre-commit run --all-files
+```
+
+If the project does not manage pre-commit via uv, use your standard Python environment installation path.
+
+### Recommended policy
+
+1. Keep auto-fix enabled locally with ruff-check --fix.
+2. Keep CI in check-only mode so violations fail loudly.
+3. Run hooks on all files in migration PRs to avoid drift.
+
+## GitHub Actions Integration
+
+### Why use it
+
+Use GitHub Actions when you need required status checks on pull requests and a single source of truth for lint and format gates.
+
+### Minimal workflow
+
+Create [.github/workflows/ruff.yml](https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions):
+
+```yaml title=".github/workflows/ruff.yml"
+name: Ruff
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  ruff:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install project dependencies
+        run: uv sync --dev
+
+      - name: Ruff lint
+        run: uv run ruff check .
+
+      - name: Ruff format check
+        run: uv run ruff format --check .
+```
+
+### Alternative: official Ruff action
+
+If you want an action-focused setup, see [Ruff GitHub Actions integration](https://docs.astral.sh/ruff/integrations/#github-actions). The official Ruff action is commonly used pinned at `astral-sh/ruff-action@v4.0.0`. Keep behavior equivalent to local commands so results do not diverge.
+
+## Alignment Checklist
+
+Keep local hooks and CI checks aligned:
+
+1. Same rule set from pyproject.toml.
+2. Same target Python version and dependency graph.
+3. Clear developer remediation command in docs:
+   - uv run ruff check . --fix
+   - uv run ruff format .
+
+## Troubleshooting
+
+### Hook passes locally but CI fails
+
+1. Ensure CI uses the same pyproject.toml and not a stale cache.
+2. Confirm matching Ruff versions in local and CI environments.
+3. Verify CI is not running on a different Python target than local config.
+
+### CI is slow
+
+1. Keep Ruff in a dedicated job so failures return early.
+2. Use dependency caching from your package workflow.
+3. Avoid running both legacy linters and Ruff after migration completion.
+
+## Source Links
+
+- [Ruff integrations](https://docs.astral.sh/ruff/integrations/)
+- [Ruff pre-commit docs](https://docs.astral.sh/ruff/integrations/#pre-commit)
+- [Ruff GitHub Actions docs](https://docs.astral.sh/ruff/integrations/#github-actions)
+- [pre-commit official docs](https://pre-commit.com/)
+- [GitHub Actions documentation](https://docs.github.com/en/actions)

zensical.toml

@@ -108,6 +108,11 @@ nav = [
       { "Overview" = "skills/python-logging-dictconfig/SKILL.md" },
       { "Docs" = "skills/python-logging-dictconfig/references/python-logging-docs.md" },
     ] },
+    { "Ruff" = [
+      { "Overview" = "skills/ruff-linting-formating/SKILL.md" },
+      { "Docs" = "skills/ruff-linting-formating/references/ruff-docs.md" },
+      { "Integrations" = "skills/ruff-linting-formating/references/ruff-integrations.md" },
+    ] },
     { "Zensical" = [
       { "Overview" = "skills/zensical-docs/SKILL.md" },
       { "Map" = "skills/zensical-docs/references/index.md" },