Compare commits
8 Commits
bb7508cf65
...
main
| Author | SHA1 | Date | |
|---|---|---|---|
 John Lancaster
|
06d5fc18f2 | ||
|
John Lancaster
|
38edc4ac36 | ||
|
John Lancaster
|
c73771c2f4 | ||
|
John Lancaster
|
33144da02f | ||
|
John Lancaster
|
0a9dadd5a8 | ||
|
John Lancaster
|
660ca88e47 | ||
|
John Lancaster
|
e60fc4b27b | ||
|
John Lancaster
|
8817d2586f |
@@ -0,0 +1,12 @@
|
||||
---
|
||||
name: New Skill Bootstrap
|
||||
description: Create and fully implement a new docs-first skill in this repository.
|
||||
argument-hint: skill-id and goal for the new skill
|
||||
agent: agent
|
||||
---
|
||||
|
||||
# New Skill Bootstrap
|
||||
|
||||
Use the canonical bootstrap guidance in [docs/skills/new-skill/SKILL.md](../../docs/skills/new-skill/SKILL.md).
|
||||
|
||||
If the request is to create or implement a new skill, load that skill document and follow it as the source of truth.
|
||||
@@ -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
|
||||
|
||||
+5
-1
@@ -1,3 +1,7 @@
|
||||
---
|
||||
icon: lucide/file-text
|
||||
---
|
||||
|
||||
# Content Contract
|
||||
|
||||
This page defines the authored content contract for the docs-first MCP architecture.
|
||||
@@ -39,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
|
||||
|
||||
|
||||
+34
-5
@@ -1,3 +1,7 @@
|
||||
---
|
||||
icon: lucide/braces
|
||||
---
|
||||
|
||||
# Frontmatter Contract
|
||||
|
||||
This page defines the `SKILL.md` frontmatter and FastMCP metadata contract.
|
||||
@@ -72,6 +76,8 @@ x-personal-mcp:
|
||||
capabilities:
|
||||
- resource://skills/<skill-id>/document
|
||||
depends_on: []
|
||||
# Optional: overrides and nested references only.
|
||||
# Top-level references/*.md are auto-discovered.
|
||||
references:
|
||||
<ref-id>:
|
||||
path: references/<file>.md
|
||||
@@ -89,16 +95,39 @@ Rules for `x-personal-mcp`:
|
||||
3. `tags` is optional and should be a list of kebab-case discovery labels.
|
||||
4. `capabilities` is required and lists the MCP URIs the skill publishes.
|
||||
5. `depends_on` is optional and lists other skill ids.
|
||||
6. `references` is an optional map keyed by `ref-id`.
|
||||
6. `references` is an optional map keyed by `ref-id` for overrides and nested entries.
|
||||
|
||||
Reference entry rules:
|
||||
|
||||
1. `ref-id` is lowercase kebab-case.
|
||||
2. `path` is a skill-relative markdown path and must stay inside the same skill directory.
|
||||
3. Nested folders under `references/` are allowed.
|
||||
4. `mime_type` defaults to `text/markdown` when omitted.
|
||||
5. `title` is an optional display label.
|
||||
6. Renaming `ref-id` values is allowed when needed; optional aliases may be used during transitions.
|
||||
3. Top-level files under `references/*.md` are auto-discovered with `ref-id` derived from a normalized filename stem (lowercase kebab-case).
|
||||
4. Nested folders under `references/` are not auto-discovered and must be declared explicitly.
|
||||
5. `mime_type` defaults to `text/markdown` when omitted.
|
||||
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
|
||||
|
||||
|
||||
@@ -1,3 +1,7 @@
|
||||
---
|
||||
icon: lucide/server
|
||||
---
|
||||
|
||||
# Static Docs Hosting Pattern
|
||||
|
||||
## Purpose
|
||||
|
||||
@@ -1,121 +0,0 @@
|
||||
# Hooking Up a New Skill
|
||||
|
||||
Use this checklist to add a new skill in the docs-first model.
|
||||
|
||||
For the full contract details, see [Content Contract](./content.md), [Frontmatter Contract](./frontmatter.md), and [URI Contract](./uris.md).
|
||||
|
||||
## Canonical Skill Shape
|
||||
|
||||
Create one skill directory under `docs/skills/`:
|
||||
|
||||
```text
|
||||
docs/
|
||||
skills/
|
||||
<skill-id>/
|
||||
SKILL.md
|
||||
references/
|
||||
... (optional markdown files, nested folders allowed)
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
1. `SKILL.md` is required.
|
||||
2. All skill-specific supporting docs live under `references/`.
|
||||
3. Skill directories are ownership boundaries; no cross-skill writes.
|
||||
4. `skill-id` is lowercase kebab-case and should remain stable.
|
||||
|
||||
## SKILL.md Frontmatter
|
||||
|
||||
`SKILL.md` frontmatter is authoritative for metadata.
|
||||
|
||||
Required top-level fields:
|
||||
|
||||
1. `name`
|
||||
2. `description`
|
||||
3. `x-personal-mcp`
|
||||
|
||||
Required `x-personal-mcp` fields:
|
||||
|
||||
1. `id`
|
||||
2. `version`
|
||||
3. `capabilities`
|
||||
|
||||
Optional `x-personal-mcp` fields:
|
||||
|
||||
1. `tags`
|
||||
2. `depends_on`
|
||||
3. `references`
|
||||
|
||||
Canonical frontmatter template:
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: <skill-id>
|
||||
description: <what this skill does and when to use it>
|
||||
|
||||
x-personal-mcp:
|
||||
id: <skill-id>
|
||||
version: 1.0.0
|
||||
tags: []
|
||||
capabilities:
|
||||
- resource://skills/<skill-id>/document
|
||||
depends_on: []
|
||||
references:
|
||||
<ref-id>:
|
||||
path: references/<file>.md
|
||||
mime_type: text/markdown
|
||||
title: <optional short title>
|
||||
---
|
||||
```
|
||||
|
||||
Reference manifest rules:
|
||||
|
||||
1. `ref-id` is lowercase kebab-case.
|
||||
2. `path` is skill-relative and must stay under `references/`.
|
||||
3. Reference paths are markdown files.
|
||||
|
||||
No `metadata.yaml` sidecar is part of this model.
|
||||
|
||||
## URI Surface
|
||||
|
||||
Canonical resource URIs for a skill:
|
||||
|
||||
1. `resource://skills/<skill_id>/document`
|
||||
2. `resource://skills/<skill_id>/references/<ref_id>`
|
||||
|
||||
Canonical discovery URIs:
|
||||
|
||||
1. `resource://catalog/skills_index`
|
||||
2. `resource://catalog/skills/{skill_id}`
|
||||
|
||||
Docs passthrough URI:
|
||||
|
||||
1. `resource://docs/{path*}`
|
||||
|
||||
Compatibility rule:
|
||||
|
||||
1. Keep URI families unversioned by default.
|
||||
2. For breaking changes, update clients to the canonical replacement URIs directly.
|
||||
|
||||
## Checklist
|
||||
|
||||
1. Create `docs/skills/<skill-id>/SKILL.md`.
|
||||
2. Add optional references under `docs/skills/<skill-id>/references/`.
|
||||
3. Populate frontmatter with `name`, `description`, and `x-personal-mcp` metadata.
|
||||
4. Ensure `x-personal-mcp.id` equals `name` and directory `<skill-id>`.
|
||||
5. Ensure `capabilities` includes `resource://skills/<skill-id>/document`.
|
||||
6. If references are exposed, declare each `ref-id` in `x-personal-mcp.references`.
|
||||
|
||||
## Quick Validation
|
||||
|
||||
1. Confirm docs build succeeds:
|
||||
|
||||
```bash
|
||||
uv run zensical build
|
||||
```
|
||||
|
||||
2. Confirm tests succeed:
|
||||
|
||||
```bash
|
||||
uv run pytest -q
|
||||
```
|
||||
@@ -22,11 +22,6 @@ x-personal-mcp:
|
||||
depends_on:
|
||||
- new-skill
|
||||
- zensical-docs
|
||||
references:
|
||||
vscode-customization:
|
||||
path: references/vscode-customization.md
|
||||
mime_type: text/markdown
|
||||
title: VS Code Customization
|
||||
---
|
||||
|
||||
# Copilot Customization
|
||||
@@ -35,7 +30,12 @@ Use this skill when a task is about changing how GitHub Copilot or VS Code agent
|
||||
|
||||
## When to Use
|
||||
|
||||
- Creating or updating `.github/copilot-instructions.md`, `AGENTS.md`, `CLAUDE.md`, or `*.instructions.md` files.
|
||||
- Creating or updating:
|
||||
- `.github/copilot-instructions.md`
|
||||
- `AGENTS.md`
|
||||
- `CLAUDE.md`
|
||||
- `*.instructions.md` files
|
||||
- `*.prompt.md` files
|
||||
- Creating prompt files, custom agents, hooks, or Agent Skills.
|
||||
- Deciding whether behavior belongs in instructions, prompts, skills, agents, hooks, MCP servers, or agent plugins.
|
||||
- Debugging why a customization is not discovered, loaded, or invoked.
|
||||
@@ -60,6 +60,60 @@ If the request is ambiguous, ask only for the missing axis that changes the file
|
||||
|
||||
Use [VS Code customization references](./references/vscode-customization.md) for official-source details about locations, frontmatter, discovery behavior, priority, and troubleshooting.
|
||||
|
||||
## Repo Shim Pattern For Personal MCP
|
||||
|
||||
Use a shim when you want another repository to consume this server as a preference and documentation source without duplicating methodology content.
|
||||
|
||||
### What the shim does
|
||||
|
||||
1. Tells the agent when to consult this MCP server.
|
||||
2. Tells the agent how to retrieve relevant guidance.
|
||||
3. Keeps repo-local behavior thin while canonical guidance stays in Personal MCP resources.
|
||||
|
||||
### Shim formats
|
||||
|
||||
Use either:
|
||||
|
||||
1. A repo instruction file (`*.instructions.md`) for always-on or file-scoped behavior.
|
||||
2. A prompt file (`*.prompt.md`) for explicit, on-demand guidance retrieval.
|
||||
|
||||
### Retrieval strategies
|
||||
|
||||
Choose one of these patterns:
|
||||
|
||||
1. Direct URI strategy:
|
||||
- Reference known resources directly, such as:
|
||||
- `resource://catalog/skills_index`
|
||||
- `resource://catalog/skills/{skill_id}`
|
||||
- `resource://skills/<skill-id>/document`
|
||||
- `resource://skills/<skill-id>/references/<ref-id>`
|
||||
2. Discovery-first strategy:
|
||||
- Start at catalog discovery (`resource://catalog/skills_index`), select the best skill match, then load the skill document and only the minimal references needed.
|
||||
|
||||
### Authoring guidance for shims
|
||||
|
||||
1. Keep shim content short and procedural; avoid copying large guidance blocks from Personal MCP.
|
||||
2. State trigger conditions clearly (for example: "when creating a new skill" or "when editing docs contracts").
|
||||
3. Specify whether to use direct URIs or discovery for that repo's common workflows.
|
||||
4. Prefer loading only the most relevant skill document first; expand to references only when needed.
|
||||
5. For stable repeated workflows, use explicit URIs. For broader or ambiguous requests, use discovery-first.
|
||||
|
||||
### Minimal shim examples
|
||||
|
||||
Instruction-style shim intent:
|
||||
|
||||
1. "For markdown edits (`applyTo: '**/*.md'`), load `resource://skills/zensical-docs/document` and apply Zensical-native documentation conventions unless they conflict with expected MkDocs compatibility."
|
||||
|
||||
Prompt-style shim intent:
|
||||
|
||||
1. "For docs authoring tasks, consult `resource://skills/zensical-docs/document`, summarize the relevant authoring constraints, then propose the smallest markdown change for this repository."
|
||||
|
||||
### Validation for shim implementation
|
||||
|
||||
1. Confirm the shim triggers in expected contexts.
|
||||
2. Confirm resource loading path is unambiguous (direct URI or discovery).
|
||||
3. Confirm repo-local customization remains thin and references Personal MCP as source of truth.
|
||||
|
||||
## Workspace Customization Workflow
|
||||
|
||||
1. Identify the customization primitive and scope.
|
||||
@@ -71,20 +125,6 @@ Use [VS Code customization references](./references/vscode-customization.md) for
|
||||
7. For skills, make the folder name match the `name` field exactly and reference any extra files from `SKILL.md` with relative links.
|
||||
8. Validate placement, YAML frontmatter, discovery settings, and whether the customization should be workspace or user scoped.
|
||||
|
||||
## Repo Integration Workflow
|
||||
|
||||
When adding a new skill to this `personal-mcp` repo, follow the resource-first pattern:
|
||||
|
||||
1. Search the catalog for `new skill` and load `resource://skills/new-skill/document`.
|
||||
2. Create authored docs under `docs/skills/<skill-id>/SKILL.md`, with optional nested `references/` markdown files.
|
||||
3. Keep `skill-id` stable and consistent across directory name, `name`, and `x-personal-mcp.id`.
|
||||
4. Put discovery metadata in `SKILL.md` frontmatter under `x-personal-mcp`.
|
||||
5. Declare `resource://skills/<skill-id>/document` in `x-personal-mcp.capabilities`.
|
||||
6. Declare references in `x-personal-mcp.references` as `ref-id -> references/<file>.md` mappings.
|
||||
7. Validate with the registry loader and `uv run zensical build`.
|
||||
|
||||
Keep runtime implementation registry-driven in `src/personal_mcp/mcp.py`; do not add per-skill Python server modules.
|
||||
|
||||
## Quality Checks
|
||||
|
||||
Before finishing:
|
||||
|
||||
@@ -13,35 +13,6 @@ x-personal-mcp:
|
||||
capabilities:
|
||||
- resource://skills/fastapi-async-sqlalchemy-modernization/document
|
||||
depends_on: []
|
||||
references:
|
||||
index:
|
||||
path: references/index.md
|
||||
mime_type: text/markdown
|
||||
title: Index
|
||||
engine:
|
||||
path: references/engine.md
|
||||
mime_type: text/markdown
|
||||
title: Engine
|
||||
session:
|
||||
path: references/session.md
|
||||
mime_type: text/markdown
|
||||
title: Session
|
||||
transactions:
|
||||
path: references/transactions.md
|
||||
mime_type: text/markdown
|
||||
title: Transactions
|
||||
implicit-io:
|
||||
path: references/implicit_io.md
|
||||
mime_type: text/markdown
|
||||
title: Implicit IO
|
||||
observability:
|
||||
path: references/observability.md
|
||||
mime_type: text/markdown
|
||||
title: Observability
|
||||
template:
|
||||
path: references/template.md
|
||||
mime_type: text/markdown
|
||||
title: Template
|
||||
---
|
||||
|
||||
# FastAPI Async SQLAlchemy Modernization Plan
|
||||
|
||||
@@ -12,23 +12,6 @@ x-personal-mcp:
|
||||
capabilities:
|
||||
- resource://skills/fastapi-uv-docker/document
|
||||
depends_on: []
|
||||
references:
|
||||
fastapi-best-practices:
|
||||
path: references/fastapi-best-practices.md
|
||||
mime_type: text/markdown
|
||||
title: FastAPI Best Practices
|
||||
uv-project-layout:
|
||||
path: references/uv-project-layout.md
|
||||
mime_type: text/markdown
|
||||
title: uv Project Layout
|
||||
uvicorn-settings:
|
||||
path: references/uvicorn-settings.md
|
||||
mime_type: text/markdown
|
||||
title: Uvicorn Settings
|
||||
docker-cloud-native:
|
||||
path: references/docker-cloud-native.md
|
||||
mime_type: text/markdown
|
||||
title: Docker Cloud Native
|
||||
---
|
||||
|
||||
# FastAPI Project Best Practices
|
||||
|
||||
@@ -19,14 +19,125 @@ 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.
|
||||
|
||||
## Inputs
|
||||
|
||||
1. New skill id (lowercase kebab-case)
|
||||
2. One-sentence capability statement (what it does and when to use it)
|
||||
3. Optional list of references to include under `references/`
|
||||
|
||||
## Source of Truth and Required References
|
||||
|
||||
1. Use this file as the baseline template for new skill authoring.
|
||||
2. Read and follow these docs before implementing a new skill:
|
||||
- [docs/architecture.md](../../architecture.md)
|
||||
- [docs/content.md](../../content.md)
|
||||
- [docs/frontmatter.md](../../frontmatter.md)
|
||||
- [docs/mcp_layout.md](../../mcp_layout.md)
|
||||
- [docs/uris.md](../../uris.md)
|
||||
|
||||
## Canonical Skill Shape
|
||||
|
||||
Create one skill directory under `docs/skills/`:
|
||||
|
||||
```text
|
||||
docs/
|
||||
skills/
|
||||
<skill-id>/
|
||||
SKILL.md
|
||||
references/
|
||||
... (optional markdown files, nested folders allowed)
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
1. `SKILL.md` is required.
|
||||
2. All skill-specific supporting docs live under `references/`.
|
||||
3. Skill directories are ownership boundaries; no cross-skill writes.
|
||||
4. `skill-id` is lowercase kebab-case and should remain stable.
|
||||
|
||||
### Framing
|
||||
|
||||
Phrasing and language in the skills should reflect the intent of providing preferences and reference documentation, rather than being for a migration or transition. When a particular resource is brought in, it should focus the general way something is done.
|
||||
|
||||
## SKILL.md Frontmatter Contract
|
||||
|
||||
`SKILL.md` frontmatter is authoritative for skill metadata.
|
||||
|
||||
Required top-level fields:
|
||||
|
||||
1. `name`
|
||||
2. `description`
|
||||
3. `x-personal-mcp`
|
||||
|
||||
Required `x-personal-mcp` fields:
|
||||
|
||||
1. `id`
|
||||
2. `version`
|
||||
3. `capabilities`
|
||||
|
||||
Optional `x-personal-mcp` fields:
|
||||
|
||||
1. `tags`
|
||||
2. `depends_on`
|
||||
3. `references`
|
||||
|
||||
Canonical frontmatter template:
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: <skill-id>
|
||||
description: <what this skill does and when to use it>
|
||||
|
||||
x-personal-mcp:
|
||||
id: <skill-id>
|
||||
version: 1.0.0
|
||||
tags: []
|
||||
capabilities:
|
||||
- resource://skills/<skill-id>/document
|
||||
depends_on: []
|
||||
# Optional: only for nested references or metadata overrides.
|
||||
references:
|
||||
<ref-id>:
|
||||
path: references/<file>.md
|
||||
mime_type: text/markdown
|
||||
title: <optional short title>
|
||||
---
|
||||
```
|
||||
|
||||
Reference manifest rules:
|
||||
|
||||
1. `ref-id` is lowercase kebab-case.
|
||||
2. `path` is skill-relative and must stay under `references/`.
|
||||
3. Top-level `references/*.md` files are auto-discovered, and `ref-id` is derived from a normalized filename stem.
|
||||
4. Nested `references/**` markdown files must be declared explicitly.
|
||||
5. Reference paths are markdown files.
|
||||
|
||||
## URI Surface
|
||||
|
||||
Canonical resource URIs for a skill:
|
||||
|
||||
1. `resource://skills/<skill_id>/document`
|
||||
2. `resource://skills/<skill_id>/references/<ref_id>`
|
||||
|
||||
Canonical discovery URIs:
|
||||
|
||||
1. `resource://catalog/skills_index`
|
||||
2. `resource://catalog/skills/{skill_id}`
|
||||
|
||||
Compatibility rule:
|
||||
|
||||
1. Keep URI families unversioned by default.
|
||||
2. For breaking changes, update clients to the canonical replacement URIs directly.
|
||||
|
||||
## 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,8 +146,26 @@ 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.
|
||||
|
||||
## Required Outcomes
|
||||
|
||||
1. Create `docs/skills/<skill-id>/SKILL.md` with valid frontmatter and a practical skill body.
|
||||
2. Create and populate `docs/skills/<skill-id>/references/` with any needed markdown references.
|
||||
3. Ensure frontmatter follows repository contract, including `x-personal-mcp` fields and canonical capabilities.
|
||||
4. Keep URI and reference mapping consistent with repository conventions.
|
||||
5. Reconcile all updates with repository implementation and avoid introducing parallel metadata systems.
|
||||
|
||||
## Validation
|
||||
|
||||
1. uv run zensical build
|
||||
2. uv run pytest -q
|
||||
|
||||
## Output Contract
|
||||
|
||||
Return:
|
||||
|
||||
1. Files created or updated
|
||||
2. Validation results
|
||||
3. Follow-up suggestions for improving the skill
|
||||
|
||||
@@ -13,19 +13,6 @@ x-personal-mcp:
|
||||
capabilities:
|
||||
- resource://skills/nicegui-ui-customization/document
|
||||
depends_on: []
|
||||
references:
|
||||
architecture-and-styling:
|
||||
path: references/architecture-and-styling.md
|
||||
mime_type: text/markdown
|
||||
title: Architecture and Styling
|
||||
interaction-patterns:
|
||||
path: references/interaction-patterns.md
|
||||
mime_type: text/markdown
|
||||
title: Interaction Patterns
|
||||
troubleshooting-and-quality-gates:
|
||||
path: references/troubleshooting-and-quality-gates.md
|
||||
mime_type: text/markdown
|
||||
title: Troubleshooting and Quality Gates
|
||||
---
|
||||
|
||||
# NiceGUI UI Customization Workflow
|
||||
|
||||
@@ -13,15 +13,6 @@ x-personal-mcp:
|
||||
capabilities:
|
||||
- resource://skills/nicegui/document
|
||||
depends_on: []
|
||||
references:
|
||||
architecture:
|
||||
path: references/architecture.md
|
||||
mime_type: text/markdown
|
||||
title: Architecture
|
||||
source-documentation:
|
||||
path: references/source-documentation.md
|
||||
mime_type: text/markdown
|
||||
title: Source Documentation
|
||||
---
|
||||
|
||||
# NiceGUI
|
||||
|
||||
@@ -12,19 +12,6 @@ x-personal-mcp:
|
||||
capabilities:
|
||||
- resource://skills/pytest-scaffolding/document
|
||||
depends_on: []
|
||||
references:
|
||||
pytest-docs:
|
||||
path: references/pytest-docs.md
|
||||
mime_type: text/markdown
|
||||
title: Pytest Docs
|
||||
fastapi-testing:
|
||||
path: references/fastapi-testing.md
|
||||
mime_type: text/markdown
|
||||
title: FastAPI Testing
|
||||
sqlalchemy-testing:
|
||||
path: references/sqlalchemy-testing.md
|
||||
mime_type: text/markdown
|
||||
title: SQLAlchemy Testing
|
||||
---
|
||||
|
||||
# Pytest Scaffolding
|
||||
|
||||
@@ -12,11 +12,6 @@ x-personal-mcp:
|
||||
capabilities:
|
||||
- resource://skills/python-logging-dictconfig/document
|
||||
depends_on: []
|
||||
references:
|
||||
python-logging-docs:
|
||||
path: references/python-logging-docs.md
|
||||
mime_type: text/markdown
|
||||
title: Python Logging Docs
|
||||
---
|
||||
|
||||
# Idiomatic Python Logging with dictConfig
|
||||
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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)
|
||||
@@ -16,31 +16,26 @@ x-personal-mcp:
|
||||
capabilities:
|
||||
- resource://skills/vscode-configuration/document
|
||||
depends_on: []
|
||||
references:
|
||||
debug-launch-configurations:
|
||||
path: references/debug-launch-configurations.md
|
||||
mime_type: text/markdown
|
||||
title: Debug Launch Configurations
|
||||
fastapi-debugpy-launch:
|
||||
path: references/fastapi-debugpy-launch.md
|
||||
mime_type: text/markdown
|
||||
title: FastAPI Debugpy Launch
|
||||
tasks-json-configuration:
|
||||
path: references/tasks-json-configuration.md
|
||||
mime_type: text/markdown
|
||||
title: Tasks JSON Configuration
|
||||
---
|
||||
|
||||
# VS Code Configuration
|
||||
|
||||
Use this skill to design or repair repeatable VS Code workspace configuration for local development workflows.
|
||||
|
||||
Primary VS Code source docs:
|
||||
|
||||
- [Python debugging in VS Code](https://code.visualstudio.com/docs/python/debugging)
|
||||
- [Debug configuration (`launch.json`)](https://code.visualstudio.com/docs/debugtest/debugging-configuration)
|
||||
- [Tasks (`tasks.json`)](https://code.visualstudio.com/docs/editor/tasks)
|
||||
- [MCP servers in VS Code](https://code.visualstudio.com/docs/agent-customization/mcp-servers)
|
||||
|
||||
## When to Use
|
||||
|
||||
- You need to create or fix `.vscode/launch.json` debug profiles.
|
||||
- You need robust Python debugging with `debugpy`.
|
||||
- You need FastAPI-specific launch profiles (app module, host/port, reload options, env files).
|
||||
- You need `.vscode/tasks.json` build/test/run tasks and optional debug pre-launch integration.
|
||||
- You need `.vscode/mcp.json` workspace or user profile MCP server configuration.
|
||||
- You need consistent workspace onboarding where users can run and debug from VS Code with minimal manual setup.
|
||||
|
||||
## Progressive References
|
||||
@@ -50,6 +45,7 @@ Load only the page that matches the current request:
|
||||
- Launch profile mechanics and debugpy patterns: [debug launch configurations](./references/debug-launch-configurations.md)
|
||||
- FastAPI-focused debug profiles using debugpy: [FastAPI + debugpy launch patterns](./references/fastapi-debugpy-launch.md)
|
||||
- Task runner setup in VS Code: [tasks.json project tasks](./references/tasks-json-configuration.md)
|
||||
- MCP server setup in VS Code: [mcp.json MCP server configuration](./references/mcp-server-configuration.md)
|
||||
|
||||
## Procedure
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Debug Launch Configurations in VS Code
|
||||
|
||||
This reference focuses on Python debugging through `debugpy` using `.vscode/launch.json`.
|
||||
This reference focuses on Python debugging through [`debugpy`](https://github.com/microsoft/debugpy) using [`.vscode/launch.json`](https://code.visualstudio.com/docs/debugtest/debugging-configuration).
|
||||
|
||||
## Core Structure
|
||||
|
||||
@@ -15,15 +15,15 @@ A minimal launch file:
|
||||
|
||||
Useful fields for Python configs:
|
||||
|
||||
- `type`: Use `debugpy`.
|
||||
- `type`: Use [`debugpy`](https://code.visualstudio.com/docs/python/debugging).
|
||||
- `request`: Usually `launch`, sometimes `attach`.
|
||||
- `name`: Friendly profile name shown in the Run and Debug panel.
|
||||
- `program`: Script path for script-based entry.
|
||||
- `module`: Module name for `python -m ...` style launches.
|
||||
- `args`: CLI arguments.
|
||||
- `cwd`: Working directory.
|
||||
- `env` / `envFile`: Environment variables.
|
||||
- `console`: `integratedTerminal` is usually most practical.
|
||||
- `cwd`: Working directory (supports [variable substitution](https://code.visualstudio.com/docs/editor/variables-reference)).
|
||||
- `env` / `envFile`: Environment variables (commonly from [environment variable definitions files](https://code.visualstudio.com/docs/python/environments#_environment-variable-definitions-file)).
|
||||
- `console`: `integratedTerminal` is usually most practical ([launch options](https://code.visualstudio.com/docs/debugtest/debugging-configuration#_launchjson-attributes)).
|
||||
- `justMyCode`: `true` by default; set `false` when stepping into dependencies.
|
||||
|
||||
## Launch vs Attach
|
||||
@@ -46,7 +46,7 @@ Attach profile example:
|
||||
}
|
||||
```
|
||||
|
||||
Remote process side command example:
|
||||
Remote process side command example (from [debugpy CLI usage](https://code.visualstudio.com/docs/python/debugging#_command-line-debugging)):
|
||||
|
||||
```bash
|
||||
python -m debugpy --listen 5678 -m your_package.main
|
||||
@@ -90,6 +90,13 @@ Prefer module mode when imports depend on package layout.
|
||||
- Keep secrets out of committed launch configs.
|
||||
- Ensure the selected VS Code interpreter matches project tooling.
|
||||
|
||||
## Source Documentation
|
||||
|
||||
- [Python debugging in VS Code](https://code.visualstudio.com/docs/python/debugging)
|
||||
- [Debug configuration and launch.json](https://code.visualstudio.com/docs/debugtest/debugging-configuration)
|
||||
- [Variables reference](https://code.visualstudio.com/docs/editor/variables-reference)
|
||||
- [debugpy project](https://github.com/microsoft/debugpy)
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If breakpoints do not hit:
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# FastAPI Debug Launch with debugpy
|
||||
|
||||
This reference provides practical `.vscode/launch.json` patterns for FastAPI applications started with uvicorn.
|
||||
This reference provides practical [`.vscode/launch.json`](https://code.visualstudio.com/docs/debugtest/debugging-configuration) patterns for [FastAPI](https://fastapi.tiangolo.com/) applications started with [uvicorn](https://www.uvicorn.org/).
|
||||
|
||||
## Launch FastAPI via Module
|
||||
|
||||
@@ -57,9 +57,11 @@ If app is created via factory function:
|
||||
}
|
||||
```
|
||||
|
||||
Factory mode is powered by uvicorn's [`--factory`](https://www.uvicorn.org/settings/#application) option.
|
||||
|
||||
## Attach to an Existing FastAPI Process
|
||||
|
||||
If the app is launched externally, start with debugpy:
|
||||
If the app is launched externally, start with [`debugpy`](https://code.visualstudio.com/docs/python/debugging#_command-line-debugging):
|
||||
|
||||
```bash
|
||||
python -m debugpy --listen 5678 -m uvicorn your_package.main:app --host 127.0.0.1 --port 8000 --reload
|
||||
@@ -96,3 +98,10 @@ A profile is considered valid when:
|
||||
2. A breakpoint inside an endpoint is hit on request.
|
||||
3. A breakpoint in startup/lifespan logic is hit at app boot.
|
||||
4. Terminal output appears in integrated terminal with expected log level.
|
||||
|
||||
## Source Documentation
|
||||
|
||||
- [FastAPI docs](https://fastapi.tiangolo.com/)
|
||||
- [Uvicorn settings and CLI options](https://www.uvicorn.org/settings/)
|
||||
- [Python debugging in VS Code](https://code.visualstudio.com/docs/python/debugging)
|
||||
- [Debug configuration and launch.json](https://code.visualstudio.com/docs/debugtest/debugging-configuration)
|
||||
|
||||
@@ -0,0 +1,123 @@
|
||||
# Configure MCP Servers in VS Code
|
||||
|
||||
Use this reference to configure MCP servers for GitHub Copilot chat in VS Code with `.vscode/mcp.json` (workspace) or profile-level `mcp.json` (user scope).
|
||||
|
||||
## Where Configuration Lives
|
||||
|
||||
VS Code supports two MCP configuration locations:
|
||||
|
||||
- Workspace scope: `.vscode/mcp.json` in the repository.
|
||||
- User profile scope: open with the `MCP: Open User Configuration` command.
|
||||
|
||||
Use workspace scope for shared team configuration, and user scope for personal or machine-specific servers.
|
||||
|
||||
## Minimal mcp.json
|
||||
|
||||
```json
|
||||
{
|
||||
"servers": {
|
||||
"github": {
|
||||
"type": "http",
|
||||
"url": "https://api.githubcopilot.com/mcp"
|
||||
},
|
||||
"playwright": {
|
||||
"type": "stdio",
|
||||
"command": "npx",
|
||||
"args": ["-y", "@microsoft/mcp-server-playwright"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The `servers` object keys are logical server names shown in VS Code MCP management surfaces.
|
||||
|
||||
## Add Servers Through VS Code UI
|
||||
|
||||
1. Run `MCP: Add Server` from the Command Palette.
|
||||
2. Choose Workspace or Global target.
|
||||
3. Review generated config in `mcp.json`.
|
||||
4. Start or restart the server from `MCP: List Servers`.
|
||||
|
||||
This guided flow is usually safer than manual edits when onboarding teammates.
|
||||
|
||||
## Security and Secrets
|
||||
|
||||
1. Do not hardcode tokens or API keys in `mcp.json`.
|
||||
2. Prefer input variables or environment-file patterns supported by the MCP configuration schema.
|
||||
3. Start only trusted servers, because local servers can execute code on your machine.
|
||||
4. Use trust prompts as a checkpoint instead of bypassing review.
|
||||
|
||||
## Security Best Practices
|
||||
|
||||
1. Apply least privilege by default.
|
||||
2. Keep workspace `mcp.json` limited to team-safe, non-secret configuration.
|
||||
3. Keep personal credentials and machine-specific settings in user-scope configuration, not repository files.
|
||||
4. Prefer explicit allowlists for filesystem writes and outbound network access when sandboxing is enabled.
|
||||
5. Use one server per trust boundary instead of one large multi-purpose server.
|
||||
6. Review server `command` and `args` as code during pull requests.
|
||||
7. Disable or uninstall unused MCP servers to reduce attack surface.
|
||||
8. Use HTTPS endpoints for remote MCP servers whenever available.
|
||||
9. Pin server packages or versions where practical to avoid accidental supply-chain drift.
|
||||
10. Reset trust and re-review configuration after major server changes.
|
||||
|
||||
### Operational Guardrails
|
||||
|
||||
1. Treat MCP resources as publishable unless an explicit access control layer exists.
|
||||
2. Capture server logs during onboarding so failures and suspicious behavior are easier to detect.
|
||||
3. Define ownership for each server entry, including who approves changes and who rotates secrets.
|
||||
4. Document upgrade triggers: if a server starts reading private data or executing side-effectful actions, require stronger access controls before rollout.
|
||||
|
||||
### Team Review Checklist
|
||||
|
||||
Use this checklist before merging workspace MCP configuration changes:
|
||||
|
||||
1. No plaintext secrets in `mcp.json`.
|
||||
2. `command` and `args` are from trusted publishers and expected binaries.
|
||||
3. Server scope is correct (workspace vs user profile).
|
||||
4. Sandboxing is enabled for local `stdio` servers when supported.
|
||||
5. Sandbox allowlists are narrow (minimum paths and domains).
|
||||
6. The change includes an owner and rollback path.
|
||||
|
||||
## Sandbox Local stdio Servers (Linux/macOS)
|
||||
|
||||
For local `stdio` servers, enable sandboxing when possible:
|
||||
|
||||
```json
|
||||
{
|
||||
"servers": {
|
||||
"myServer": {
|
||||
"type": "stdio",
|
||||
"command": "npx",
|
||||
"args": ["-y", "@example/mcp-server"],
|
||||
"sandboxEnabled": true
|
||||
}
|
||||
},
|
||||
"sandbox": {
|
||||
"filesystem": {
|
||||
"allowWrite": ["${workspaceFolder}"]
|
||||
},
|
||||
"network": {
|
||||
"allowedDomains": ["api.example.com"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Sandboxing is currently available on Linux and macOS, not Windows.
|
||||
|
||||
## Troubleshooting Checklist
|
||||
|
||||
1. Open server logs from `MCP: List Servers` -> `Show Output`.
|
||||
2. Confirm trust state (or run `MCP: Reset Trust` if needed).
|
||||
3. Confirm server command and arguments run outside VS Code.
|
||||
4. Confirm workspace-vs-user scope matches where you expect the server to run.
|
||||
5. If using remote development, configure the server in the remote scope when needed.
|
||||
|
||||
## Source Documentation
|
||||
|
||||
- [Add and manage MCP servers in VS Code](https://code.visualstudio.com/docs/agent-customization/mcp-servers)
|
||||
- [MCP configuration reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration)
|
||||
- [Input variables for sensitive data](https://code.visualstudio.com/docs/agents/reference/mcp-configuration#_input-variables-for-sensitive-data)
|
||||
- [Sandbox configuration reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration#_sandbox-configuration)
|
||||
- [AI security guidance in VS Code](https://code.visualstudio.com/docs/agents/security)
|
||||
- [Model Context Protocol overview](https://modelcontextprotocol.io/docs/getting-started/intro)
|
||||
@@ -1,6 +1,6 @@
|
||||
# Configure Project Tasks in tasks.json
|
||||
|
||||
Use `.vscode/tasks.json` to define repeatable project commands and optional hooks for debugging.
|
||||
Use [`.vscode/tasks.json`](https://code.visualstudio.com/docs/editor/tasks) to define repeatable project commands and optional hooks for debugging.
|
||||
|
||||
## Minimal File
|
||||
|
||||
@@ -14,12 +14,12 @@ Use `.vscode/tasks.json` to define repeatable project commands and optional hook
|
||||
## Task Fields You Will Use Most
|
||||
|
||||
- `label`: Task name shown in VS Code.
|
||||
- `type`: Usually `shell`.
|
||||
- `type`: Usually [`shell`](https://code.visualstudio.com/docs/editor/tasks#_custom-tasks).
|
||||
- `command`: Executable to run.
|
||||
- `args`: Command arguments.
|
||||
- `options.cwd`: Working directory.
|
||||
- `group`: Mark default build or test tasks.
|
||||
- `problemMatcher`: Parse errors into the Problems panel.
|
||||
- `options.cwd`: Working directory (supports [variable substitution](https://code.visualstudio.com/docs/editor/variables-reference)).
|
||||
- `group`: Mark default build or test tasks ([task groups](https://code.visualstudio.com/docs/editor/tasks#_grouping-tasks)).
|
||||
- `problemMatcher`: Parse errors into the Problems panel ([problem matchers](https://code.visualstudio.com/docs/editor/tasks#_defining-a-problem-matcher)).
|
||||
- `isBackground`: `true` for long-running tasks (for example dev server watch).
|
||||
|
||||
## Python Project Example
|
||||
@@ -56,7 +56,7 @@ Use `.vscode/tasks.json` to define repeatable project commands and optional hook
|
||||
|
||||
## Connect Tasks to Debug Profiles
|
||||
|
||||
In `launch.json`, you can run a task first:
|
||||
In [`launch.json`](https://code.visualstudio.com/docs/debugtest/debugging-configuration), you can run a task first with [`preLaunchTask`](https://code.visualstudio.com/docs/debugtest/debugging-configuration#_launchjson-attributes):
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -90,3 +90,10 @@ If a task fails unexpectedly:
|
||||
3. Confirm tool availability in environment path.
|
||||
4. Confirm quoting and argument boundaries in `args`.
|
||||
5. Confirm the task is not blocked by an outdated background process.
|
||||
|
||||
## Source Documentation
|
||||
|
||||
- [VS Code Tasks (official)](https://code.visualstudio.com/docs/editor/tasks)
|
||||
- [Tasks Appendix (schema and interfaces)](https://code.visualstudio.com/docs/reference/tasks-appendix)
|
||||
- [Variables Reference](https://code.visualstudio.com/docs/editor/variables-reference)
|
||||
- [Debug configuration and launch.json](https://code.visualstudio.com/docs/debugtest/debugging-configuration)
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: zensical-docs
|
||||
description: 'Reference skill for Zensical documentation mechanics. Use for quick lookup of docs structure, feature options, and source links, then edit this skill over time to record project preferences for when each feature should be used.'
|
||||
description: 'Reference skill for Zensical documentation mechanics. Use for quick lookup of docs structure, feature options, and source links. Prefer inline Markdown links to source docs and avoid bare URLs because this content is rendered as human docs and MCP resources.'
|
||||
argument-hint: 'What are you documenting, who is the audience, and what Zensical features are in scope?'
|
||||
x-personal-mcp:
|
||||
id: zensical-docs
|
||||
@@ -20,31 +20,6 @@ x-personal-mcp:
|
||||
capabilities:
|
||||
- resource://skills/zensical-docs/document
|
||||
depends_on: []
|
||||
references:
|
||||
index:
|
||||
path: references/index.md
|
||||
mime_type: text/markdown
|
||||
title: Source Map
|
||||
zensical-features:
|
||||
path: references/zensical-features.md
|
||||
mime_type: text/markdown
|
||||
title: Feature Catalog
|
||||
theme-customization-and-icons:
|
||||
path: references/theme-customization-and-icons.md
|
||||
mime_type: text/markdown
|
||||
title: Theme Customization and Icons
|
||||
documentation-quality:
|
||||
path: references/documentation-quality.md
|
||||
mime_type: text/markdown
|
||||
title: Documentation Quality
|
||||
discoverability-and-ia:
|
||||
path: references/discoverability-and-ia.md
|
||||
mime_type: text/markdown
|
||||
title: Discoverability and IA
|
||||
code-heavy-docs-and-mkdocstrings:
|
||||
path: references/code-heavy-docs-and-mkdocstrings.md
|
||||
mime_type: text/markdown
|
||||
title: Code-Heavy Docs and Mkdocstrings
|
||||
---
|
||||
|
||||
# Zensical Documentation Authoring
|
||||
@@ -124,6 +99,30 @@ Keep this section short and revise it over time.
|
||||
|
||||
When making a recommendation, link back to the relevant reference file first, and when possible to the upstream docs linked from that reference.
|
||||
|
||||
## Link Formatting Rule
|
||||
|
||||
Because this project publishes the same markdown for both `/docs` and MCP resources, link quality is part of the content contract.
|
||||
|
||||
- Never leave a bare URL in prose or list items.
|
||||
- Prefer using in-place Markdown links with meaningful labels.
|
||||
- For external sources, prefer `[descriptive label](https://...)` over raw `https://...`.
|
||||
- For internal files, prefer relative Markdown links so rendered docs remain navigable.
|
||||
- Any mention of a library or a specific library feature should include a link to source documentation somewhere on the page.
|
||||
- If inline linking is awkward or the citation payload is too large, use a footnote or tooltip citation instead.
|
||||
|
||||
Example preferred style:
|
||||
|
||||
- `See [importlib.resources](https://docs.python.org/3/library/importlib.resources.html) for packaging details.`
|
||||
|
||||
Example to avoid:
|
||||
|
||||
- `See https://docs.python.org/3/library/importlib.resources.html for packaging details.`
|
||||
|
||||
Acceptable alternatives when inline links are not ideal:
|
||||
|
||||
- Add a footnote-style source citation at the end of the section or page.
|
||||
- Add a tooltip citation when the docs pattern supports it.
|
||||
|
||||
## Compatibility Rule
|
||||
|
||||
Prefer the Zensical-native way of doing something when it exists and is well-supported.
|
||||
@@ -136,3 +135,4 @@ Return only what is useful for the current docs task:
|
||||
1. Which reference to read next.
|
||||
2. The smallest recommended docs or config change.
|
||||
3. Any repo-specific preference this suggests should be added back into this skill.
|
||||
4. For any library or feature-level claim, include a source-doc citation somewhere (inline link preferred; footnote or tooltip acceptable).
|
||||
|
||||
@@ -1,3 +1,7 @@
|
||||
---
|
||||
icon: lucide/link
|
||||
---
|
||||
|
||||
# URI Contract
|
||||
|
||||
This page defines the canonical resource URI contract, template parameter rules, and compatibility policy.
|
||||
|
||||
@@ -20,3 +20,9 @@ build-backend = "hatchling.build"
|
||||
|
||||
[tool.hatch.build.targets.wheel]
|
||||
packages = ["src/personal_mcp"]
|
||||
|
||||
[dependency-groups]
|
||||
dev = [
|
||||
"pre-commit>=4.6.0",
|
||||
"ruff>=0.15.18",
|
||||
]
|
||||
|
||||
@@ -258,6 +258,51 @@ def _normalize_docs_path(path: str) -> str:
|
||||
return normalized.as_posix()
|
||||
|
||||
|
||||
def _title_from_reference_filename(filename: str) -> str:
|
||||
stem = PurePosixPath(filename).stem
|
||||
normalized = stem.replace("-", " ").replace("_", " ").split()
|
||||
if not normalized:
|
||||
return stem
|
||||
return " ".join(token.capitalize() for token in normalized)
|
||||
|
||||
|
||||
def _reference_id_from_filename(filename: str) -> str | None:
|
||||
stem = PurePosixPath(filename).stem.strip().lower().replace("_", "-")
|
||||
normalized = re.sub(r"[^a-z0-9-]+", "-", stem)
|
||||
normalized = re.sub(r"-+", "-", normalized).strip("-")
|
||||
if not normalized:
|
||||
return None
|
||||
if not SKILL_ID_RE.fullmatch(normalized):
|
||||
return None
|
||||
return normalized
|
||||
|
||||
|
||||
def _discover_top_level_references(
|
||||
*,
|
||||
skill_dir: Traversable,
|
||||
) -> dict[str, ReferenceEntry]:
|
||||
references_dir = skill_dir.joinpath("references")
|
||||
if not references_dir.is_dir():
|
||||
return {}
|
||||
|
||||
discovered: dict[str, ReferenceEntry] = {}
|
||||
for child in sorted(references_dir.iterdir(), key=lambda item: item.name):
|
||||
if child.is_dir() or not child.is_file():
|
||||
continue
|
||||
if not child.name.lower().endswith(".md"):
|
||||
continue
|
||||
|
||||
ref_id = _reference_id_from_filename(child.name)
|
||||
if ref_id is None:
|
||||
continue
|
||||
|
||||
discovered[ref_id] = ReferenceEntry(
|
||||
path=PurePosixPath("references").joinpath(child.name).as_posix(),
|
||||
title=_title_from_reference_filename(child.name),
|
||||
)
|
||||
return discovered
|
||||
|
||||
|
||||
def _ensure_no_cycles(skills_by_id: dict[str, SkillRecord]) -> list[tuple[str, str]]:
|
||||
visiting: set[str] = set()
|
||||
visited: set[str] = set()
|
||||
@@ -370,8 +415,11 @@ def load_docs_registry(
|
||||
)
|
||||
continue
|
||||
|
||||
effective_reference_entries = _discover_top_level_references(skill_dir=skill_dir)
|
||||
effective_reference_entries.update(frontmatter.x_personal_mcp.references)
|
||||
|
||||
references: dict[str, ReferenceRecord] = {}
|
||||
for ref_id, ref_entry in frontmatter.x_personal_mcp.references.items():
|
||||
for ref_id, ref_entry in effective_reference_entries.items():
|
||||
ref_relpath = skill_rel_root.joinpath(ref_entry.path).as_posix()
|
||||
if ref_relpath not in docs_markdown_by_path:
|
||||
issues.append(
|
||||
|
||||
@@ -178,6 +178,15 @@ wheels = [
|
||||
{ url = "https://files.pythonhosted.org/packages/ae/3a/dbeec9d1ee0844c679f6bb5d6ad4e9f198b1224f4e7a32825f47f6192b0c/cffi-2.0.0-cp314-cp314t-win_arm64.whl", hash = "sha256:0a1527a803f0a659de1af2e1fd700213caba79377e27e4693648c2923da066f9", size = 184195, upload-time = "2025-09-08T23:23:43.004Z" },
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "cfgv"
|
||||
version = "3.5.0"
|
||||
source = { registry = "https://pypi.org/simple" }
|
||||
sdist = { url = "https://files.pythonhosted.org/packages/4e/b5/721b8799b04bf9afe054a3899c6cf4e880fcf8563cc71c15610242490a0c/cfgv-3.5.0.tar.gz", hash = "sha256:d5b1034354820651caa73ede66a6294d6e95c1b00acc5e9b098e917404669132", size = 7334, upload-time = "2025-11-19T20:55:51.612Z" }
|
||||
wheels = [
|
||||
{ url = "https://files.pythonhosted.org/packages/db/3c/33bac158f8ab7f89b2e59426d5fe2e4f63f7ed25df84c036890172b412b5/cfgv-3.5.0-py2.py3-none-any.whl", hash = "sha256:a8dc6b26ad22ff227d2634a65cb388215ce6cc96bbcc5cfde7641ae87e8dacc0", size = 7445, upload-time = "2025-11-19T20:55:50.744Z" },
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "click"
|
||||
version = "8.4.1"
|
||||
@@ -273,6 +282,15 @@ wheels = [
|
||||
{ url = "https://files.pythonhosted.org/packages/2d/82/e5d2c1c67d19841e9edc74954c827444ae826978499bde3dfc1d007c8c11/deepmerge-2.0-py3-none-any.whl", hash = "sha256:6de9ce507115cff0bed95ff0ce9ecc31088ef50cbdf09bc90a09349a318b3d00", size = 13475, upload-time = "2024-08-30T05:31:48.659Z" },
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "distlib"
|
||||
version = "0.4.3"
|
||||
source = { registry = "https://pypi.org/simple" }
|
||||
sdist = { url = "https://files.pythonhosted.org/packages/c9/02/bd72be9134d25ed783ecbbc38a539ffaefbf90c78418c7fb7229600dbac7/distlib-0.4.3.tar.gz", hash = "sha256:f152097224a0ae24be5a0f6bae1b9359af82133bce63f98a95f86cae1aede9ed", size = 615141, upload-time = "2026-06-12T08:04:52.847Z" }
|
||||
wheels = [
|
||||
{ url = "https://files.pythonhosted.org/packages/02/08/9c41fb51ab5b43eb21674aff13df270e8ba6c4b29c8624e328dc7a9482af/distlib-0.4.3-py2.py3-none-any.whl", hash = "sha256:4b0ce306c966eb73bc3a7b6abad017c556dadd92c44701562cd528ac7fde4d5b", size = 470628, upload-time = "2026-06-12T08:04:50.506Z" },
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "dnspython"
|
||||
version = "2.8.0"
|
||||
@@ -395,6 +413,15 @@ server = [
|
||||
{ name = "websockets" },
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "filelock"
|
||||
version = "3.29.4"
|
||||
source = { registry = "https://pypi.org/simple" }
|
||||
sdist = { url = "https://files.pythonhosted.org/packages/e6/dc/be6cbe99670cd6e4ad387123647cb08e0c32975e223f82551e914c5568a6/filelock-3.29.4.tar.gz", hash = "sha256:10cdb3656fc44541cdf30652a93fb10ec6b05325620eb316bd26893e4201538a", size = 63028, upload-time = "2026-06-13T16:12:00.744Z" }
|
||||
wheels = [
|
||||
{ url = "https://files.pythonhosted.org/packages/13/37/a065dc3bd6e49423a6532c642ca7378d3f467b1ef44c2800c937af7f9739/filelock-3.29.4-py3-none-any.whl", hash = "sha256:dac1648087d5115554850d113e7dd8c83ab2d38e3435dde2d4f163847e57b767", size = 42757, upload-time = "2026-06-13T16:11:59.582Z" },
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "griffelib"
|
||||
version = "2.0.2"
|
||||
@@ -486,6 +513,15 @@ wheels = [
|
||||
{ url = "https://files.pythonhosted.org/packages/d2/fd/6668e5aec43ab844de6fc74927e155a3b37bf40d7c3790e49fc0406b6578/httpx_sse-0.4.3-py3-none-any.whl", hash = "sha256:0ac1c9fe3c0afad2e0ebb25a934a59f4c7823b60792691f779fad2c5568830fc", size = 8960, upload-time = "2025-10-10T21:48:21.158Z" },
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "identify"
|
||||
version = "2.6.19"
|
||||
source = { registry = "https://pypi.org/simple" }
|
||||
sdist = { url = "https://files.pythonhosted.org/packages/52/63/51723b5f116cc04b061cb6f5a561790abf249d25931d515cd375e063e0f4/identify-2.6.19.tar.gz", hash = "sha256:6be5020c38fcb07da56c53733538a3081ea5aa70d36a156f83044bfbf9173842", size = 99567, upload-time = "2026-04-17T18:39:50.265Z" }
|
||||
wheels = [
|
||||
{ url = "https://files.pythonhosted.org/packages/94/84/d9273cd09688070a6523c4aee4663a8538721b2b755c4962aafae0011e72/identify-2.6.19-py2.py3-none-any.whl", hash = "sha256:20e6a87f786f768c092a721ad107fc9df0eb89347be9396cadf3f4abbd1fb78a", size = 99397, upload-time = "2026-04-17T18:39:49.221Z" },
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "idna"
|
||||
version = "3.18"
|
||||
@@ -756,6 +792,15 @@ wheels = [
|
||||
{ url = "https://files.pythonhosted.org/packages/e8/3d/1087453384dbde46a8c7f9356eead2c58be8a7bf156bca40243377c85715/more_itertools-11.1.0-py3-none-any.whl", hash = "sha256:4b65538ae22f6fed0ce4874efd317463a7489796a0939fa66824dd542125a192", size = 72226, upload-time = "2026-05-22T14:14:28.824Z" },
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "nodeenv"
|
||||
version = "1.10.0"
|
||||
source = { registry = "https://pypi.org/simple" }
|
||||
sdist = { url = "https://files.pythonhosted.org/packages/24/bf/d1bda4f6168e0b2e9e5958945e01910052158313224ada5ce1fb2e1113b8/nodeenv-1.10.0.tar.gz", hash = "sha256:996c191ad80897d076bdfba80a41994c2b47c68e224c542b48feba42ba00f8bb", size = 55611, upload-time = "2025-12-20T14:08:54.006Z" }
|
||||
wheels = [
|
||||
{ url = "https://files.pythonhosted.org/packages/88/b2/d0896bdcdc8d28a7fc5717c305f1a861c26e18c05047949fb371034d98bd/nodeenv-1.10.0-py2.py3-none-any.whl", hash = "sha256:5bb13e3eed2923615535339b3c620e76779af4cb4c6a90deccc9e36b274d3827", size = 23438, upload-time = "2025-12-20T14:08:52.782Z" },
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "openapi-pydantic"
|
||||
version = "0.5.1"
|
||||
@@ -807,6 +852,22 @@ wheels = [
|
||||
{ url = "https://files.pythonhosted.org/packages/81/e6/cd9575ac904136b3cbf7aa7ee819ef86eedb7274e46f230e94ea4342e729/platformdirs-4.10.0-py3-none-any.whl", hash = "sha256:fb516cdb12eb0d857d0cd85a7c57cea4d060bee4578d6cf5a14dfdf8cbf8784a", size = 22743, upload-time = "2026-05-28T03:32:52.175Z" },
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "pre-commit"
|
||||
version = "4.6.0"
|
||||
source = { registry = "https://pypi.org/simple" }
|
||||
dependencies = [
|
||||
{ name = "cfgv" },
|
||||
{ name = "identify" },
|
||||
{ name = "nodeenv" },
|
||||
{ name = "pyyaml" },
|
||||
{ name = "virtualenv" },
|
||||
]
|
||||
sdist = { url = "https://files.pythonhosted.org/packages/8e/22/2de9408ac81acbb8a7d05d4cc064a152ccf33b3d480ebe0cd292153db239/pre_commit-4.6.0.tar.gz", hash = "sha256:718d2208cef53fdc38206e40524a6d4d9576d103eb16f0fec11c875e7716e9d9", size = 198525, upload-time = "2026-04-21T20:31:41.613Z" }
|
||||
wheels = [
|
||||
{ url = "https://files.pythonhosted.org/packages/80/6e/4b28b62ecb6aae56769c34a8ff1d661473ec1e9519e2d5f8b2c150086b26/pre_commit-4.6.0-py2.py3-none-any.whl", hash = "sha256:e2cf246f7299edcabcf15f9b0571fdce06058527f0a06535068a86d38089f29b", size = 226472, upload-time = "2026-04-21T20:31:40.092Z" },
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "prompts"
|
||||
version = "0.1.0"
|
||||
@@ -820,6 +881,12 @@ dependencies = [
|
||||
{ name = "zensical" },
|
||||
]
|
||||
|
||||
[package.dev-dependencies]
|
||||
dev = [
|
||||
{ name = "pre-commit" },
|
||||
{ name = "ruff" },
|
||||
]
|
||||
|
||||
[package.metadata]
|
||||
requires-dist = [
|
||||
{ name = "fastapi", specifier = ">=0.115.0" },
|
||||
@@ -830,6 +897,12 @@ requires-dist = [
|
||||
{ name = "zensical", specifier = ">=0.0.45" },
|
||||
]
|
||||
|
||||
[package.metadata.requires-dev]
|
||||
dev = [
|
||||
{ name = "pre-commit", specifier = ">=4.6.0" },
|
||||
{ name = "ruff", specifier = ">=0.15.18" },
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "py-key-value-aio"
|
||||
version = "0.4.5"
|
||||
@@ -1018,6 +1091,19 @@ wheels = [
|
||||
{ url = "https://files.pythonhosted.org/packages/df/80/fc9d01d5ed37ba4c42ca2b55b4339ae6e200b456be3a1aaddf4a9fa99b8c/pyperclip-1.11.0-py3-none-any.whl", hash = "sha256:299403e9ff44581cb9ba2ffeed69c7aa96a008622ad0c46cb575ca75b5b84273", size = 11063, upload-time = "2025-09-26T14:40:36.069Z" },
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "python-discovery"
|
||||
version = "1.4.2"
|
||||
source = { registry = "https://pypi.org/simple" }
|
||||
dependencies = [
|
||||
{ name = "filelock" },
|
||||
{ name = "platformdirs" },
|
||||
]
|
||||
sdist = { url = "https://files.pythonhosted.org/packages/0b/1a/cbbaf13b730abb0a16b964d984e19f2fe520c21a4dc664051359a3f5a9e7/python_discovery-1.4.2.tar.gz", hash = "sha256:8f3746c4b4968d22afbb97d36e1a0e5b66e6c0f297290f2e95f05b9b8bf18690", size = 70277, upload-time = "2026-06-11T16:10:42.383Z" }
|
||||
wheels = [
|
||||
{ url = "https://files.pythonhosted.org/packages/1a/82/a70006589557f267f15bd384c0642ad49f0d97b690c3a05b166b9dcbad3b/python_discovery-1.4.2-py3-none-any.whl", hash = "sha256:475803f53b7b2ed6e490e27373f9d8340f7d2eebf9acdaf645d7d714c97bb500", size = 33886, upload-time = "2026-06-11T16:10:41.192Z" },
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "python-dotenv"
|
||||
version = "1.2.2"
|
||||
@@ -1260,6 +1346,31 @@ wheels = [
|
||||
{ url = "https://files.pythonhosted.org/packages/79/cb/966040123eb102371559746908ef2c9471f4d43e17ec9a645a2258dab64b/rpds_py-2026.5.1-cp315-cp315t-win_amd64.whl", hash = "sha256:90bd6630002a1c7f09e7843dd79f0d24f3d2897cc25a753480917865d14f15b3", size = 225441, upload-time = "2026-05-28T12:01:51.408Z" },
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "ruff"
|
||||
version = "0.15.18"
|
||||
source = { registry = "https://pypi.org/simple" }
|
||||
sdist = { url = "https://files.pythonhosted.org/packages/74/98/1295ad5a5aa9bc85bdcdfa5d82fe7b49c61af5657df4f227637ff9de0da6/ruff-0.15.18.tar.gz", hash = "sha256:2698a964c70e8bf402dcb99c8810472d270d141e7aa8c4e13599fd52033a2f33", size = 4761437, upload-time = "2026-06-18T18:25:39.224Z" }
|
||||
wheels = [
|
||||
{ url = "https://files.pythonhosted.org/packages/b9/d0/686e984941269621e2be72612d5c1e461f8f7b38415a2a7d7a81c8ae6715/ruff-0.15.18-py3-none-linux_armv6l.whl", hash = "sha256:8b6850172348c8381b8b3084c5915a4393c2373b9b54cd5b5e1ea15812bc10df", size = 10887308, upload-time = "2026-06-18T18:25:03.062Z" },
|
||||
{ url = "https://files.pythonhosted.org/packages/ed/21/bc4123e3f5515ee99f8ce1eb93a14a0628fe4d1678663cd08f933ac16931/ruff-0.15.18-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:3fccc153a85417dcd976883160cacce486997b0a0058dd18f54b8aaaac7d1ce2", size = 11281305, upload-time = "2026-06-18T18:25:30.026Z" },
|
||||
{ url = "https://files.pythonhosted.org/packages/51/93/4769464c25cf7ab2acb3c7dda9cad3d867eb41c59565b3e2a9d17249c90c/ruff-0.15.18-py3-none-macosx_11_0_arm64.whl", hash = "sha256:08d4c86a68f2c3ec2c9d56380a71fb4a4f65373055cbb8caabd645e9102f38d4", size = 10641215, upload-time = "2026-06-18T18:25:15.802Z" },
|
||||
{ url = "https://files.pythonhosted.org/packages/6c/42/56926d17120db2c208d76bf60a1a019644dd9e91dc27f0f95c9caddb1366/ruff-0.15.18-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:37e5108745c2c0705da916d7d4de533ddf547051ef45f62888c31bae73f66318", size = 10957224, upload-time = "2026-06-18T18:25:36.955Z" },
|
||||
{ url = "https://files.pythonhosted.org/packages/22/4f/d43fab8d8189afde803103022d000a8ef9f230616d436d52a8b2b8d63b50/ruff-0.15.18-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:56949a6ce8b3abde54c0bcb22cebfe57e8771cadc84b407ae8b8eaf67ebdcd43", size = 10699024, upload-time = "2026-06-18T18:25:05.707Z" },
|
||||
{ url = "https://files.pythonhosted.org/packages/63/42/1e3e4c68bd408b9768cf3e439acbe2c78245225faef253f7028a0cdb63e0/ruff-0.15.18-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:01a754cd6a1b630d3f97e33eb452cf7a98040482318e870f8bc52a5a30e62657", size = 11491458, upload-time = "2026-06-18T18:25:20.275Z" },
|
||||
{ url = "https://files.pythonhosted.org/packages/20/77/47a3484bea8521e14a203d98c389c5c97846675e4f02734672da4a69b52a/ruff-0.15.18-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:6ba7a07e03a44dbf10bb086ee06705b173625014ec99f73a7e6836a5e5590a0c", size = 12383752, upload-time = "2026-06-18T18:25:22.535Z" },
|
||||
{ url = "https://files.pythonhosted.org/packages/0a/ca/054159590787023d83b658a1a1819c4c8910114e7015069340b71c0961cb/ruff-0.15.18-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:5a2c40a41a4cadbcf5897b548ab29dfe248b20c540961c0247d98a3973c70403", size = 11577923, upload-time = "2026-06-18T18:25:10.702Z" },
|
||||
{ url = "https://files.pythonhosted.org/packages/6d/ff/d353d6b7bbd73cc0ec37f4463d7540e45e894338abdd9964eee0de332708/ruff-0.15.18-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:5f0480ce690cbb6c4db6e5d08f19fce98e10ba131a8b60c1bcdac42771e3ae2d", size = 11583925, upload-time = "2026-06-18T18:25:32.391Z" },
|
||||
{ url = "https://files.pythonhosted.org/packages/c1/4a/891f89b9c296ed3e5f3ece1a5629badc989d9a8fdaa30431aaf4774bc1c2/ruff-0.15.18-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:2330215f1f393fa8733f55edce04fcf94c36a2c460fcde31f78cc84e4951e9b1", size = 11582834, upload-time = "2026-06-18T18:25:27.309Z" },
|
||||
{ url = "https://files.pythonhosted.org/packages/32/a3/ed9e370154bf85de360b93c03026157f02d4943b2d01ff4945f4429f8e8a/ruff-0.15.18-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:a6aa6a3d979e48ae617578183674bf264fbe7d0114a796a26bd678d67963c7ff", size = 10927328, upload-time = "2026-06-18T18:25:34.676Z" },
|
||||
{ url = "https://files.pythonhosted.org/packages/f5/d1/5cf5909329fedb5d39d555ee818ba5cf4638e1a301b89785d34f2905bfcb/ruff-0.15.18-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:a81beadbbff2c9c245561ae3f77b16709d87f35eec650d0501679239d3449b22", size = 10693187, upload-time = "2026-06-18T18:25:08.245Z" },
|
||||
{ url = "https://files.pythonhosted.org/packages/fd/44/ff6c635cf2c4f4e7b618b6640da057376baa36014695487d88aed4794268/ruff-0.15.18-py3-none-musllinux_1_2_i686.whl", hash = "sha256:2186d9e940ae332ab293623a75b5f4fe49565f449954d50a72a046683aa6b809", size = 11208721, upload-time = "2026-06-18T18:25:41.327Z" },
|
||||
{ url = "https://files.pythonhosted.org/packages/88/d9/5baa2a30861adfb7022cf33c1e35b2fc18085b08c16f83eff4c7b99a5f48/ruff-0.15.18-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:5c2abf140438032bc77b2284a6c9944ecd8a19e5f1c7b52b1b8e4a0a80d19a7a", size = 11678599, upload-time = "2026-06-18T18:25:13.607Z" },
|
||||
{ url = "https://files.pythonhosted.org/packages/c3/1a/0725a7cfdc32ff769efb96ee782bec882e16448c5d9e3be947ec4c04ce27/ruff-0.15.18-py3-none-win32.whl", hash = "sha256:02299e6e9fa5b297a3f6d5d10d7bcd655c925b028bb8b9d4588214549c6b9ec4", size = 10901903, upload-time = "2026-06-18T18:25:24.755Z" },
|
||||
{ url = "https://files.pythonhosted.org/packages/f3/51/805d9f6fb7970505c3504794a5ec350f605361b807fef4dcf214ebd35e72/ruff-0.15.18-py3-none-win_amd64.whl", hash = "sha256:dac80dc8d26b2257dbefabed62f5d255c3937b4ccb122da1fc634794fa3578b3", size = 12041189, upload-time = "2026-06-18T18:25:17.915Z" },
|
||||
{ url = "https://files.pythonhosted.org/packages/29/4c/67bb45e41609eb4726f1bfeb59e083cf91d14c696d4bd14c234a980be93d/ruff-0.15.18-py3-none-win_arm64.whl", hash = "sha256:b2c9257fcbd4a3e5b977a1904e6facca016bafe2edc17df24db67cfaee03b4e4", size = 11329958, upload-time = "2026-06-18T18:25:43.686Z" },
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "secretstorage"
|
||||
version = "3.5.0"
|
||||
@@ -1430,6 +1541,21 @@ wheels = [
|
||||
{ url = "https://files.pythonhosted.org/packages/e4/16/c1fd27e9549f3c4baf1dc9c20c456cd2f822dbf8de9f463824b0c0357e06/uvloop-0.22.1-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:6cde23eeda1a25c75b2e07d39970f3374105d5eafbaab2a4482be82f272d5a5e", size = 4296730, upload-time = "2025-10-16T22:17:00.744Z" },
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "virtualenv"
|
||||
version = "21.5.1"
|
||||
source = { registry = "https://pypi.org/simple" }
|
||||
dependencies = [
|
||||
{ name = "distlib" },
|
||||
{ name = "filelock" },
|
||||
{ name = "platformdirs" },
|
||||
{ name = "python-discovery" },
|
||||
]
|
||||
sdist = { url = "https://files.pythonhosted.org/packages/f1/a5/81f987504738e6defeed61ec1c47e2aefab3c35d8eeb87e1b3f38cf28254/virtualenv-21.5.1.tar.gz", hash = "sha256:dca3bf98275a59c652b69d68e73433e597d977c2da9198882479d1a7188009c8", size = 4578798, upload-time = "2026-06-16T16:23:58.603Z" }
|
||||
wheels = [
|
||||
{ url = "https://files.pythonhosted.org/packages/2c/02/3623e6169bed617ed1e2d372f7c69f92ec28d54c4dfc997055c8578ec148/virtualenv-21.5.1-py3-none-any.whl", hash = "sha256:55aa670b67bbfb991b03fda39bd3276d92c419d702376e98c5df1c9989a26783", size = 4558820, upload-time = "2026-06-16T16:23:56.963Z" },
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "watchfiles"
|
||||
version = "1.2.0"
|
||||
|
||||
@@ -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" },
|
||||
|
||||
Reference in New Issue
Block a user