tidydraws 0.1.0__tar.gz

tidydraws-0.1.0/.agents/skills/author-skills/SKILL.md

@@ -0,0 +1,400 @@
+---
+name: author-skills
+description: >
+  Author, configure, and distribute Agent Skills for a Great Docs
+  site. Covers the three scenarios: automatic skill generation,
+  adding a single hand-written skill, and distributing multiple
+  named skills with a switcher page. Use when creating, editing,
+  or configuring SKILL.md files for package documentation.
+license: MIT
+compatibility: Requires Great Docs >=0.8, Quarto CLI installed.
+metadata:
+  author: rich-iannone
+  version: "1.0"
+  tags:
+    - skills
+    - agent-skills
+    - distribution
+    - configuration
+---
+
+# Author Skills
+
+Skill for creating and distributing Agent Skills through a Great
+Docs documentation site. An Agent Skill is a structured Markdown
+file (`SKILL.md`) that gives AI coding agents context about a
+package, its API, and best practices.
+
+Great Docs supports three scenarios for skills, each with a
+different level of effort and control.
+
+## The three scenarios
+
+### Scenario 1: Automatic generation
+
+Great Docs generates a `skill.md` automatically from your
+package metadata, API reference sections, and `great-docs.yml`
+config. This is the zero-effort default.
+
+**How it works**: during `great-docs build`, the tool reads your
+`pyproject.toml` (for name, description, license, Python version),
+your API reference sections, and any `skill.*` config keys. It
+produces a skill file with installation instructions, an API
+overview, gotchas, best practices, and resource links.
+
+**Config options that enrich the auto-generated skill:**
+
+```yaml
+# great-docs.yml
+skill:
+  enabled: true # default; set false to skip
+  well_known: true # publish to .well-known/agent-skills/
+  gotchas:
+    - "Column expressions are lazy; call .collect() to materialize."
+    - "Method chaining returns a new object; the original is not mutated."
+  best_practices:
+    - "Prefer method chaining over intermediate variables."
+  decision_table:
+    - need: "Create a table from a dict"
+      use: "GT(data)"
+    - need: "Format currency values"
+      use: "fmt_currency()"
+  extra_body: "skills/extra-skill-content.md"
+```
+
+**When to use this scenario**: you want a skill page with minimal
+effort and are satisfied with auto-generated content derived from
+your API reference.
+
+### Scenario 2: Single hand-written skill
+
+Write a `SKILL.md` by hand (or with LLM assistance) and point
+`great-docs.yml` at it. Great Docs copies it into the build and
+generates the Skills page from it.
+
+**Directory layout:**
+
+```
+project-root/
+├── skills/
+│   └── my-package/
+│       ├── SKILL.md
+│       └── references/
+│           ├── api-patterns.md
+│           └── gotchas.md
+└── great-docs.yml
+```
+
+**Config:**
+
+```yaml
+# great-docs.yml
+skill:
+  file: skills/my-package/SKILL.md
+```
+
+Great Docs copies the file to `<docs>/skill.md`, places it
+under `.well-known/agent-skills/<name>/SKILL.md`, and generates
+the Skills page with install instructions and the full skill
+content.
+
+**When to use this scenario**: you want full editorial control
+over the skill content, including custom sections, curated
+examples, and reference files that go beyond what automatic
+generation can produce.
+
+### Scenario 3: Multiple named skills
+
+Distribute several focused skills from a single site. Each skill
+gets its own panel on the Skills page (with a switcher bar) and
+its own entry in `.well-known/agent-skills/index.json` for
+`npx skills add` discovery.
+
+**Directory layout:**
+
+```
+project-root/
+├── skills/
+│   ├── my-package/
+│   │   ├── SKILL.md
+│   │   └── references/
+│   ├── write-guides/
+│   │   ├── SKILL.md
+│   │   └── references/
+│   └── review-code/
+│       ├── SKILL.md
+│       └── references/
+└── great-docs.yml
+```
+
+**Config:**
+
+```yaml
+# great-docs.yml
+skill:
+  skills:
+    - name: my-package
+      file: skills/my-package/SKILL.md
+    - name: write-guides
+      file: skills/write-guides/SKILL.md
+    - name: review-code
+      file: skills/review-code/SKILL.md
+```
+
+The first entry becomes the primary `skill.md` at the site root.
+All entries appear in the switcher bar and are individually
+installable via `npx skills add`.
+
+**When to use this scenario**: your project has distinct
+focus-area skills (e.g., one for general usage, one for
+contributing, one for configuration) and you want users to
+install exactly what they need.
+
+## Quick start
+
+Create a hand-written skill in three steps:
+
+````bash
+mkdir -p skills/my-package/references
+
+cat > skills/my-package/SKILL.md << 'SKILL_EOF'
+---
+name: my-package
+description: >
+  Use the my-package Python library. Covers installation, core API,
+  and common patterns.
+license: MIT
+compatibility: Requires Python >=3.11.
+metadata:
+  author: your-name
+  version: "1.0"
+  tags:
+    - python
+    - my-package
+---
+
+# my-package
+
+Short description of what the package does and when to use it.
+
+## Installation
+
+```bash
+pip install my-package
+````
+
+## When to use what
+
+| Need            | Use              |
+| --------------- | ---------------- |
+| Create a widget | `Widget()`       |
+| Style a widget  | `widget.style()` |
+
+## API overview
+
+### Core
+
+- `Widget()`: Create a new widget.
+- `Widget.style()`: Apply styling to a widget.
+
+## Gotchas
+
+1. **Immutable by default.** Methods return new objects.
+2. **Lazy evaluation.** Call `.render()` to produce output.
+
+## Best practices
+
+- Prefer method chaining over intermediate variables.
+- Use type hints in all public API calls.
+  SKILL_EOF
+
+````
+
+Then add one line to `great-docs.yml`:
+
+```yaml
+skill:
+  file: skills/my-package/SKILL.md
+````
+
+Run `great-docs build` and verify the Skills page.
+
+## Skill directory structure
+
+```
+skills/author-skills/
+├── SKILL.md
+└── references/
+    ├── skill-anatomy.md
+    └── config-reference.md
+```
+
+## Writing a SKILL.md
+
+### Frontmatter
+
+Every SKILL.md starts with YAML frontmatter:
+
+```yaml
+---
+name: my-package
+description: >
+  One-paragraph description of the skill (max 1024 characters).
+license: MIT
+compatibility: Requires Python >=3.11.
+metadata:
+  author: your-github-handle
+  version: "1.0"
+  tags:
+    - python
+    - relevant-topic
+---
+```
+
+The required and optional keys are documented in the
+`references/skill-anatomy.md` companion file.
+
+### Body structure
+
+A well-structured skill follows this outline:
+
+```
+# Package Name
+Opening paragraph (what, when, why).
+
+## Installation
+pip install command.
+
+## When to use what
+Decision table mapping needs to API calls.
+
+## API overview
+Sections matching your API reference, with one-line summaries.
+
+## Gotchas
+Numbered list of common pitfalls.
+
+## Best practices
+Bullet list of recommended patterns.
+
+## Resources
+Links to docs, llms.txt, and source code.
+```
+
+### Reference files
+
+Place companion Markdown files in a `references/` subdirectory
+alongside the SKILL.md. These files are copied into
+`.well-known/agent-skills/<name>/references/` and are available
+to agents that install the skill.
+
+Use reference files for content that is too detailed for the
+main SKILL.md: style guides, checklists, pattern libraries,
+and decision matrices.
+
+### Writing tips
+
+Follow these guidelines when writing skill content:
+
+- Write for an LLM reader, not a human. Be explicit about
+  distinctions that a model might confuse (e.g., `{python}` vs
+  `{.python}`).
+- Use concrete examples over abstract descriptions.
+- Keep the decision table ("When to use what") actionable:
+  each row should map a task to a specific function or method.
+- Avoid emoji, em dashes, and starting a list without
+  introductory text.
+- Keep the SKILL.md under 2000 lines. Move detailed reference
+  material into companion files.
+
+## Workflows
+
+### Adding a skill to an existing site
+
+1. Create the `skills/<name>/` directory with a `SKILL.md`.
+2. Optionally add a `references/` subdirectory with companion
+   files.
+3. Set `skill.file` in `great-docs.yml` to point at the SKILL.md.
+4. Run `great-docs build` and check the Skills page.
+
+### Converting from automatic to hand-written
+
+1. Run `great-docs build` to generate the automatic `skill.md`.
+2. Copy the generated file from `<docs>/skill.md` into
+   `skills/<name>/SKILL.md`.
+3. Edit the content: add custom sections, rewrite descriptions,
+   curate the decision table.
+4. Set `skill.file` in `great-docs.yml`.
+5. Rebuild.
+
+### Adding a second skill (switching to multi-skill mode)
+
+1. Create a second `skills/<name>/` directory with its SKILL.md.
+2. Replace the `skill.file` key with `skill.skills` in
+   `great-docs.yml`:
+
+   ```yaml
+   skill:
+     skills:
+       - name: original-skill
+         file: skills/original-skill/SKILL.md
+       - name: new-skill
+         file: skills/new-skill/SKILL.md
+   ```
+
+3. Rebuild. The Skills page now shows a switcher bar with both
+   skills.
+
+### Testing skill installation
+
+Verify your skill is discoverable:
+
+```bash
+# Check the published skill
+great-docs check-skill
+
+# List all skills in the .well-known manifest
+great-docs list-skills
+
+# Test npx installation (after deploying)
+npx skills add <site-url>
+```
+
+## Discovery and distribution
+
+Great Docs publishes skills at two well-known paths for
+auto-discovery by `npx skills add` and other agent tooling:
+
+```
+<site>/.well-known/agent-skills/<name>/SKILL.md
+<site>/.well-known/agent-skills/index.json
+```
+
+The `index.json` manifest lists all skills with their name,
+description, and relative path. In multi-skill mode, each skill
+gets its own entry.
+
+The root-level `<site>/skill.md` always contains the primary
+skill (the first entry in `skill.skills`, or the only skill).
+
+## Gotchas
+
+1. **`skill.skills` overrides `skill.file`.** If both are set,
+   `skill.skills` takes precedence and `skill.file` is ignored.
+2. **The `name` field must be unique.** Each skill in
+   `skill.skills` needs a distinct `name`. Duplicates cause the
+   later entry to overwrite the earlier one in `.well-known/`.
+3. **Reference files must be in `references/`.** Only files under
+   the `references/` subdirectory (relative to the SKILL.md) are
+   copied into `.well-known/`. Files elsewhere are ignored.
+4. **Use hyphens in skill names, not underscores.** The `name`
+   field becomes a URL path segment
+   (`.well-known/agent-skills/<name>/`), and hyphens are the
+   standard web convention for URL slugs. Match the directory
+   name: `skills/my-skill/` with `name: my-skill`.
+5. **The first skill in `skill.skills` is special.** It becomes
+   the primary `skill.md` at the site root and is the default
+   panel shown on the Skills page.
+6. **Set `skill.enabled: false` to disable entirely.** This
+   suppresses both automatic generation and hand-written skill
+   processing.

tidydraws-0.1.0/.agents/skills/author-skills/references/config-reference.md

@@ -0,0 +1,122 @@
+# Config Reference -- Skill Settings
+
+All skill-related settings live under the `skill:` key in
+`great-docs.yml`. This reference covers every option.
+
+## Top-level skill keys
+
+```yaml
+skill:
+  enabled: true
+  file: skills/my-package/SKILL.md
+  well_known: true
+  gotchas: []
+  best_practices: []
+  decision_table: []
+  extra_body: null
+  skills: []
+```
+
+### Key reference
+
+| Key              | Type          | Default | Description                                             |
+| ---------------- | ------------- | ------- | ------------------------------------------------------- |
+| `enabled`        | `bool`        | `true`  | Enable or disable skill generation entirely             |
+| `file`           | `str \| null` | `null`  | Path to a hand-written SKILL.md (relative to project root) |
+| `well_known`     | `bool`        | `true`  | Publish skills to `.well-known/agent-skills/` for discovery |
+| `gotchas`        | `list[str]`   | `[]`    | Gotcha strings appended to auto-generated skill         |
+| `best_practices` | `list[str]`   | `[]`    | Best-practice strings appended to auto-generated skill  |
+| `decision_table` | `list[dict]`  | `[]`    | Manual "When to use what" rows for auto-generated skill |
+| `extra_body`     | `str \| null` | `null`  | Path to extra Markdown appended to auto-generated body  |
+| `skills`         | `list[dict]`  | `[]`    | Multi-skill entries (overrides `file` when non-empty)   |
+
+## Scenario configs
+
+### Scenario 1: Automatic generation (default)
+
+No `skill:` config needed. Great Docs generates a skill from
+package metadata and API sections.
+
+To enrich the auto-generated skill, add optional keys:
+
+```yaml
+skill:
+  gotchas:
+    - "Column selectors are strings, not bare identifiers."
+  best_practices:
+    - "Prefer method chaining over intermediate variables."
+  decision_table:
+    - need: "Create a table"
+      use: "GT(data)"
+    - need: "Format numbers"
+      use: "fmt_number()"
+  extra_body: "skills/extra-content.md"
+```
+
+### Scenario 2: Single hand-written skill
+
+```yaml
+skill:
+  file: skills/my-package/SKILL.md
+```
+
+When `file` is set, automatic generation is skipped. The
+referenced SKILL.md is copied verbatim to `<docs>/skill.md`.
+
+### Scenario 3: Multiple named skills
+
+```yaml
+skill:
+  skills:
+    - name: my-package
+      file: skills/my-package/SKILL.md
+    - name: write-guides
+      file: skills/write-guides/SKILL.md
+    - name: review-code
+      file: skills/review-code/SKILL.md
+```
+
+Each entry requires two keys:
+
+| Key    | Type  | Description                                      |
+| ------ | ----- | ------------------------------------------------ |
+| `name` | `str` | Unique skill identifier (used in URLs and paths) |
+| `file` | `str` | Path to the SKILL.md (relative to project root)  |
+
+## Precedence rules
+
+Great Docs evaluates skill config in this order:
+
+1. If `skill.enabled` is `false`, no skill is generated.
+2. If `skill.skills` is non-empty, multi-skill mode is used.
+   The `skill.file` key is ignored.
+3. If `skill.file` is set, the hand-written file is used.
+4. If a curated skill exists at `skills/<package-name>/SKILL.md`,
+   it is used automatically (no config needed).
+5. Otherwise, a skill is auto-generated from package metadata.
+
+## Discovery output
+
+After a build, skills are published at these paths:
+
+```
+<docs>/
+├── skill.md                                    # primary skill
+├── skills.qmd                                  # rendered Skills page
+└── .well-known/
+    └── agent-skills/
+        ├── index.json                          # discovery manifest
+        ├── my-package/
+        │   ├── SKILL.md
+        │   └── references/
+        │       └── ...
+        └── write-guides/
+            ├── SKILL.md
+            └── references/
+                └── ...
+```
+
+The `index.json` manifest lists each skill with its `name`,
+`description`, and relative path to the SKILL.md. Agent tooling
+like `npx skills add` reads this manifest to offer skill
+installation.

tidydraws-0.1.0/.agents/skills/author-skills/references/skill-anatomy.md

@@ -0,0 +1,126 @@
+# Skill Anatomy
+
+A SKILL.md file has two parts: YAML frontmatter and a Markdown
+body. This reference covers every supported field.
+
+## Frontmatter
+
+```yaml
+---
+name: my-package
+description: >
+  One-paragraph description of the skill. Maximum 1024 characters.
+  Should explain what the skill covers and when to use it.
+license: MIT
+compatibility: Requires Python >=3.11.
+metadata:
+  author: github-handle
+  version: "1.0"
+  tags:
+    - python
+    - relevant-topic
+---
+```
+
+### Frontmatter keys
+
+| Key             | Required | Type     | Max length | Description                                        |
+| --------------- | -------- | -------- | ---------- | -------------------------------------------------- |
+| `name`          | yes      | `str`    | 64 chars   | Skill identifier; lowercase with hyphens (e.g., `my-skill`) |
+| `description`   | yes      | `str`    | 1024 chars | What the skill covers and when to use it            |
+| `license`       | no       | `str`    |            | SPDX license identifier (e.g., `MIT`, `Apache-2.0`) |
+| `compatibility` | no       | `str`    |            | Runtime requirements (Python version, CLI tools)    |
+| `metadata`      | no       | `object` |            | Container for `author`, `version`, and `tags`       |
+
+### Metadata sub-keys
+
+| Key       | Type     | Description                                    |
+| --------- | -------- | ---------------------------------------------- |
+| `author`  | `str`    | GitHub handle or name of the skill author      |
+| `version` | `str`    | Semantic version of the skill content          |
+| `tags`    | `list`   | Searchable tags for skill discovery            |
+
+## Body sections
+
+The body is standard Markdown. The following sections are
+conventional for Agent Skills, though none are strictly required.
+
+### Recommended section order
+
+| Section             | Heading level | Purpose                                          |
+| ------------------- | ------------- | ------------------------------------------------ |
+| Package title       | `#`           | Package name as the top-level heading            |
+| Opening paragraph   |               | 2-3 sentences: what, when, why                   |
+| Installation        | `##`          | `pip install` command                            |
+| When to use what    | `##`          | Decision table mapping tasks to API calls        |
+| API overview        | `##`          | Section-by-section API listing with summaries    |
+| Gotchas             | `##`          | Numbered list of common pitfalls                 |
+| Best practices      | `##`          | Bullet list of recommended patterns              |
+| Resources           | `##`          | Links to docs, llms.txt, source code             |
+
+### Decision table format
+
+The "When to use what" table maps user needs to specific API
+calls. Each row should be actionable:
+
+```markdown
+| Need                    | Use                  |
+| ----------------------- | -------------------- |
+| Create a table from CSV | `GT(pd.read_csv())` |
+| Format as percentage    | `fmt_percent()`      |
+| Add a footnote          | `tab_footnote()`     |
+```
+
+### API overview format
+
+List functions with one-line summaries. Group by API reference
+section:
+
+```markdown
+## API overview
+
+### Table creation
+
+- `GT(data)`: Create a display table from a DataFrame.
+- `GT.as_raw_html()`: Render to an HTML string.
+
+### Formatting
+
+- `fmt_number()`: Format numeric columns.
+- `fmt_currency()`: Format as currency values.
+```
+
+### Gotchas format
+
+Use a numbered list. Lead each item with a bold label:
+
+```markdown
+## Gotchas
+
+1. **Immutable objects.** Methods return new GT objects.
+2. **Column selectors are strings.** Pass column names as
+   strings, not bare identifiers.
+```
+
+## Reference files
+
+Companion files live in a `references/` subdirectory alongside
+the SKILL.md:
+
+```
+skills/my-package/
+├── SKILL.md
+└── references/
+    ├── style-guide.md
+    ├── pattern-library.md
+    └── checklist.md
+```
+
+Reference files are plain Markdown (no frontmatter required).
+They are copied into `.well-known/agent-skills/<name>/references/`
+during the build, making them available to agents that install
+the skill.
+
+Use reference files for detailed content that would make the
+main SKILL.md too long: style examples, checklists, decision
+matrices, and extended pattern libraries.