john/prompts
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

ruff skill

Browse Source
This commit is contained in:
John Lancaster
2026-06-20 17:25:47 -05:00
parent 660ca88e47
commit 0a9dadd5a8
8 changed files with 318 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture.md
+4 -2
View File
@@ -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
+1 -1
View File
@@ -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
+22
View File
@@ -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
+6 -3
View File
@@ -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.
4. Validate the docs build and MCP resource reads.
3. Treat top-level `references/*.md` as auto-discovered references with `ref-id` generated from filename.
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
+121
View File
@@ -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
+31
View File
@@ -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
+128
View File
@@ -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
+5
View File
@@ -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" },