From c4cd14b5b1befc1f03b7f2bc552c5759f6b1c96a Mon Sep 17 00:00:00 2001 From: Magnus Hedemark Date: Fri, 10 Jul 2026 21:50:56 -0400 Subject: [PATCH] fix(skills): repair audited format and resource defects --- agent-skills/SKILL.md | 6 +- .../skills/headscale-backup/README.md | 23 + .../skills/headscale-deploy/README.md | 23 + .../tailscale/skills/headscale-derp/README.md | 23 + .../skills/headscale-node-lifecycle/README.md | 23 + .../skills/headscale-routing/README.md | 23 + .../tailscale/skills/tailnet-policy/README.md | 23 + .../skills/tailscale-client/README.md | 23 + .../skills/bundle-builder/README.md | 23 + .../skills/bundle-builder/SKILL.md | 675 ++++++++---------- .../skills/interviewer/README.md | 23 + .../skills/interviewer/SKILL.md | 2 +- .../skills/observer/README.md | 23 + cli-builder/SKILL.md | 18 +- .../references/agent-readiness-checklist.md | 16 + crowdsec/SKILL.md | 55 +- crowdsec/references/operations-checklist.md | 31 + forgejo-cli/SKILL.md | 32 +- hugo-theme/references/cover-images.md | 66 ++ llamaindex/templates/agentic-rag.py | 17 +- raleigh/SKILL.md | 8 +- 21 files changed, 699 insertions(+), 457 deletions(-) create mode 100644 bundles/tailscale/skills/headscale-backup/README.md create mode 100644 bundles/tailscale/skills/headscale-deploy/README.md create mode 100644 bundles/tailscale/skills/headscale-derp/README.md create mode 100644 bundles/tailscale/skills/headscale-node-lifecycle/README.md create mode 100644 bundles/tailscale/skills/headscale-routing/README.md create mode 100644 bundles/tailscale/skills/tailnet-policy/README.md create mode 100644 bundles/tailscale/skills/tailscale-client/README.md create mode 100644 bundles/workflow-architect/skills/bundle-builder/README.md create mode 100644 bundles/workflow-architect/skills/interviewer/README.md create mode 100644 bundles/workflow-architect/skills/observer/README.md create mode 100644 cli-builder/references/agent-readiness-checklist.md create mode 100644 crowdsec/references/operations-checklist.md create mode 100644 hugo-theme/references/cover-images.md diff --git a/agent-skills/SKILL.md b/agent-skills/SKILL.md index 2ad5697..d457cda 100644 --- a/agent-skills/SKILL.md +++ b/agent-skills/SKILL.md @@ -99,10 +99,10 @@ Static resources: templates, images, data files, schemas. Use **relative paths from the skill root** when referencing other files: ```markdown -See [the reference guide](references/REFERENCE.md) for details. +See [the specification](references/specification.md) for details. -Run the extraction script: -scripts/extract.py +Run a bundled script: +scripts/ ``` Keep file references one level deep from `SKILL.md`. Avoid deeply nested reference chains. diff --git a/bundles/tailscale/skills/headscale-backup/README.md b/bundles/tailscale/skills/headscale-backup/README.md new file mode 100644 index 0000000..8392b31 --- /dev/null +++ b/bundles/tailscale/skills/headscale-backup/README.md @@ -0,0 +1,23 @@ +# Headscale Backup + +## Why Install This Skill + +Provides a repeatable backup, restore, and migration workflow for Headscale state before upgrades or recovery work. + +## What You Get + +| Content | Purpose | +|---|---| +| `SKILL.md` and `scripts/` | Backup, restore, and migration guidance | + +## Quick Start + +Read `SKILL.md` before running a backup or restore script. + +## Triggers + +Use before Headscale upgrades, migrations, or disaster recovery. + +## Requirements + +Access to the Headscale host, database, configuration, and certificates. diff --git a/bundles/tailscale/skills/headscale-deploy/README.md b/bundles/tailscale/skills/headscale-deploy/README.md new file mode 100644 index 0000000..a9ec55f --- /dev/null +++ b/bundles/tailscale/skills/headscale-deploy/README.md @@ -0,0 +1,23 @@ +# Headscale Deploy + +## Why Install This Skill + +Helps set up and maintain a self-hosted Headscale control server. + +## What You Get + +| Content | Purpose | +|---|---| +| `SKILL.md` and `scripts/` | Deployment and maintenance workflow | + +## Quick Start + +Follow the deployment sequence in `SKILL.md` for Linux or Docker. + +## Triggers + +Use when deploying, configuring, or troubleshooting Headscale. + +## Requirements + +Linux or Docker host access and a Headscale-compatible network setup. diff --git a/bundles/tailscale/skills/headscale-derp/README.md b/bundles/tailscale/skills/headscale-derp/README.md new file mode 100644 index 0000000..af15823 --- /dev/null +++ b/bundles/tailscale/skills/headscale-derp/README.md @@ -0,0 +1,23 @@ +# Headscale DERP + +## Why Install This Skill + +Explains how to deploy and diagnose DERP relays when direct peer connections are unavailable. + +## What You Get + +| Content | Purpose | +|---|---| +| `SKILL.md` and `scripts/` | Relay deployment and latency diagnostics | + +## Quick Start + +Use the diagnostic guidance in `SKILL.md` before adding a custom relay. + +## Triggers + +Use when peers rely on DERP or direct connectivity fails. + +## Requirements + +Headscale administration and a reachable relay host. diff --git a/bundles/tailscale/skills/headscale-node-lifecycle/README.md b/bundles/tailscale/skills/headscale-node-lifecycle/README.md new file mode 100644 index 0000000..cebfaa8 --- /dev/null +++ b/bundles/tailscale/skills/headscale-node-lifecycle/README.md @@ -0,0 +1,23 @@ +# Headscale Node Lifecycle + +## Why Install This Skill + +Manages device registration, auth keys, tags, inventory, and decommissioning in a Headscale tailnet. + +## What You Get + +| Content | Purpose | +|---|---| +| `SKILL.md` and `scripts/` | Node lifecycle procedures | + +## Quick Start + +Follow `SKILL.md` to choose personal-node or tagged-node registration. + +## Triggers + +Use when adding, approving, tagging, or retiring devices. + +## Requirements + +Headscale administrator access. diff --git a/bundles/tailscale/skills/headscale-routing/README.md b/bundles/tailscale/skills/headscale-routing/README.md new file mode 100644 index 0000000..ad0d011 --- /dev/null +++ b/bundles/tailscale/skills/headscale-routing/README.md @@ -0,0 +1,23 @@ +# Headscale Routing + +## Why Install This Skill + +Configures subnet routers and exit nodes so a tailnet can reach LAN devices or route internet traffic. + +## What You Get + +| Content | Purpose | +|---|---| +| `SKILL.md` and `scripts/` | Route advertising and approval guidance | + +## Quick Start + +Use `SKILL.md` to advertise routes, then approve them centrally. + +## Triggers + +Use when adding LAN routes or an exit node. + +## Requirements + +Headscale administration and a gateway node with routing enabled. diff --git a/bundles/tailscale/skills/tailnet-policy/README.md b/bundles/tailscale/skills/tailnet-policy/README.md new file mode 100644 index 0000000..dbe2490 --- /dev/null +++ b/bundles/tailscale/skills/tailnet-policy/README.md @@ -0,0 +1,23 @@ +# Tailnet Policy + +## Why Install This Skill + +Helps author and validate Headscale-compatible huJSON access policies. + +## What You Get + +| Content | Purpose | +|---|---| +| `SKILL.md` and `scripts/` | Policy authoring, validation, and deployment guidance | + +## Quick Start + +Use `SKILL.md` to validate a policy before deploying it. + +## Triggers + +Use when changing ACLs, grants, tags, or Tailscale SSH rules. + +## Requirements + +Headscale policy access and huJSON-compatible tooling. diff --git a/bundles/tailscale/skills/tailscale-client/README.md b/bundles/tailscale/skills/tailscale-client/README.md new file mode 100644 index 0000000..97b4343 --- /dev/null +++ b/bundles/tailscale/skills/tailscale-client/README.md @@ -0,0 +1,23 @@ +# Tailscale Client for Headscale + +## Why Install This Skill + +Connects and troubleshoots official Tailscale clients against a self-hosted Headscale server. + +## What You Get + +| Content | Purpose | +|---|---| +| `SKILL.md` and `scripts/` | Client setup and diagnostics | + +## Quick Start + +Follow `SKILL.md` to connect with the appropriate `--login-server` value. + +## Triggers + +Use when enrolling a device or diagnosing tailnet connectivity. + +## Requirements + +The official Tailscale client and access to the Headscale control server. diff --git a/bundles/workflow-architect/skills/bundle-builder/README.md b/bundles/workflow-architect/skills/bundle-builder/README.md new file mode 100644 index 0000000..94badb8 --- /dev/null +++ b/bundles/workflow-architect/skills/bundle-builder/README.md @@ -0,0 +1,23 @@ +# Bundle Builder + +## Why Install This Skill + +Turns a discovered workflow into a reusable skill bundle with a manifest, decision map, and phase skills. + +## What You Get + +| Content | Purpose | +|---|---| +| `SKILL.md` | Bundle synthesis instructions | + +## Quick Start + +Run workflow-architect’s active or passive mode, then load this step after the workflow converges. + +## Triggers + +Use after workflow discovery is complete and a reusable bundle is needed. + +## Requirements + +Hermes memory and file-writing tools. diff --git a/bundles/workflow-architect/skills/bundle-builder/SKILL.md b/bundles/workflow-architect/skills/bundle-builder/SKILL.md index 7cbf0d3..152e2ad 100644 --- a/bundles/workflow-architect/skills/bundle-builder/SKILL.md +++ b/bundles/workflow-architect/skills/bundle-builder/SKILL.md @@ -1,86 +1,86 @@ -1|--- -2|name: bundle-builder -3|description: >- -4| The synthesis engine for workflow-architect. Reads accumulated workflow -5| state from memory and renders it into a valid Agent Skills bundle directory -6| with sub-skills, manifest, decision map, and optional kanban board. Loaded -7| after the interviewer or observer achieves convergence. -8|license: MIT -9|compatibility: Hermes Agent — uses write_file for bundle output, shell_quote -10|metadata: -11| tags: [workflow, generation, bundle, synthesis] -12| spec-version: "1.0" -13|--- -14| -15|# Bundle Builder — Workflow Synthesis Engine -16| -17|This sub-skill is loaded after the interviewer (active mode) or observer -18|(passive mode) achieves convergence. It reads the accumulated workflow -19|state from memory and generates an output bundle directory. -20| -21|## Input -22| -23|All `workflow-architect:state:*` memory entries. Read them all at once: -24| -25|``` -26|Read: workflow-architect:state:entry_points -27|Read: workflow-architect:state:phases -28|Read: workflow-architect:state:branching -29|Read: workflow-architect:state:pain_points -30|Read: workflow-architect:state:exit_criteria -31|``` -32| -33|If any required fields are missing (entry_points, phases, branching, exit_criteria), -34|abort with a clear message about what's missing. -35| -36|## Output Structure -37| -38|The bundle is written to `~/.hermes/skills///` with this layout: -39| -40|``` -41|/ +--- +name: bundle-builder +description: >- + The synthesis engine for workflow-architect. Reads accumulated workflow + state from memory and renders it into a valid Agent Skills bundle directory + with sub-skills, manifest, decision map, and optional kanban board. Loaded + after the interviewer or observer achieves convergence. +license: MIT +compatibility: Hermes Agent — uses write_file for bundle output, shell_quote +metadata: + tags: [workflow, generation, bundle, synthesis] + spec-version: "1.0" +--- + +# Bundle Builder — Workflow Synthesis Engine + +This sub-skill is loaded after the interviewer (active mode) or observer +(passive mode) achieves convergence. It reads the accumulated workflow +state from memory and generates an output bundle directory. + +## Input + +All `workflow-architect:state:*` memory entries. Read them all at once: + +``` +Read: workflow-architect:state:entry_points +Read: workflow-architect:state:phases +Read: workflow-architect:state:branching +Read: workflow-architect:state:pain_points +Read: workflow-architect:state:exit_criteria +``` + +If any required fields are missing (entry_points, phases, branching, exit_criteria), +abort with a clear message about what's missing. + +## Output Structure + +The bundle is written to `~/.hermes/skills///` with this layout: + +``` +/ ├── SKILL.md # *** UMBRELLA ENTRY POINT *** — makes the bundle │ # loadable via skill_view() and discoverable by │ # the agent's skill scanner on trigger keywords. │ # CRITICAL: without this, the bundle is invisible. -50|├── README.md # Summary of this bundle -51|├── manifest.yaml # Skill-to-trigger mapping -52|├── skills/ -53|│ ├── entry-skill.md # One per discovered phase -54|│ ├── phase-two.md -55|│ └── ... -56|├── decision-map.md # Mermaid flowchart -57|├── AGENTS.md # Agent loading instructions for this bundle -58|├── kanban/ -59|│ └── board-definition.yaml # Only if kanban is appropriate -60|└── references/ -61| └── generated-from.md # Metadata about how this bundle was created -62|``` -63| +├── README.md # Summary of this bundle +├── manifest.yaml # Skill-to-trigger mapping +├── skills/ +│ ├── entry-skill.md # One per discovered phase +│ ├── phase-two.md +│ └── ... +├── decision-map.md # Mermaid flowchart +├── AGENTS.md # Agent loading instructions for this bundle +├── kanban/ +│ └── board-definition.yaml # Only if kanban is appropriate +└── references/ + └── generated-from.md # Metadata about how this bundle was created +``` + **The `SKILL.md` umbrella is not optional.** Without it, individual sub-skills may exist on disk but the agent's skill scanner has no entry point to match trigger keywords against. The umbrella is how the agent discovers and enters the bundle. -74| -75|### Bundle naming -76| -77|Ask the user for a bundle name at the start of synthesis: -78| -79|``` -80|"Before I generate the bundle — what should I call it? -81|Something short, lowercase with hyphens, like 'my-triage-workflow' -82|or 'dev-sprint-routine'." -83|``` -84| -85|Fallback if user doesn't provide one: `my-workflow--`. -86| -87|### Writing the files -88| -89|For each file in the output bundle, use the templates in `templates/` as -90|starting points. Render them by substituting the state values. -91| -92|**Step-by-step file creation order:** -93| + +### Bundle naming + +Ask the user for a bundle name at the start of synthesis: + +``` +"Before I generate the bundle — what should I call it? +Something short, lowercase with hyphens, like 'my-triage-workflow' +or 'dev-sprint-routine'." +``` + +Fallback if user doesn't provide one: `my-workflow--`. + +### Writing the files + +For each file in the output bundle, use the shared templates in `../../templates/` as +starting points. Render them by substituting the state values. + +**Step-by-step file creation order:** + 0. **Umbrella SKILL.md** — **MANDATORY FIRST STEP.** This is the entry point that makes the bundle discoverable. Write it directly to the bundle directory as `SKILL.md`, then register it via `skill_manage(action='create')`. @@ -124,290 +124,246 @@ the bundle. ## Pipeline Heuristics - Can the user enter at any phase, or must they start at Phase 1? -138| - Are any phases automatic (e.g., refine always follows draft)? -139| - What's the relationship between phases (sequential, branching, optional)? -140| ``` -141| -142| **Category choice:** Place the bundle in a category that matches where its -143| sub-skills live (e.g., `content` for blogging pipelines, `devops` for -144| deployment workflows). Ask the user if unsure. -145|======= -146|0. **umbrella SKILL.md** — Create the bundle's entry point. This is the -147| first file because the umbrella must be registered and discoverable -148| before any sub-skill can be loaded. -149| -150| a. Generate an umbrella SKILL.md with: -151| -152| **Frontmatter:** -153| - `name: ` -154| - `description:` — Craft this carefully. Include broad trigger -155| phrases that cover all phases of the workflow, so the agent can -156| auto-detect this bundle in future sessions. Pattern: -157| "Use when [trigger summary]. Covers: [phase list]." -158| - `tags: [workflow, bundle:generated, ]` -159| - `spec-version: "1.0"` -160| -161| **Body:** -162| - H1: `# ` (user-friendly title) -163| - **Phase table** — Markdown table mapping each sub-skill -164| name to its trigger condition and typical entry signal. -165| Columns: | Phase | Load this skill | When | -166| - **Workflow flowchart** — Mermaid `graph LR` or `graph TD` -167| showing entry → phases (with decision diamonds for -168| branching) → exit. Entry condition links to the description. -169| - **Navigation instructions** — Explain the two-entry model: -170| (1) auto-detect via trigger conditions, (2) `skill_view(name='')` -171| to inspect the pipeline. Tell the agent: identify the user's -172| current phase, load that sub-skill, follow its instructions. -173| - **Heuristics** — Phase ordering notes (sequential vs. flexible), -174| entry points (can start at any phase), transition signals. -175| -176| b. Write to `/SKILL.md` via `write_file`. -177| -178| c. Register with: -179| ``` -180| skill_manage(action='create', name='', content='...') -181| ``` -182| -183| > **Why step 0?** The umbrella SKILL.md is the agent's entry point to -184| > the entire bundle. It must exist and be registered first so that any -185| > subsequent sub-skill loading instructions reference a discoverable -186| > parent. Without it, the bundle is invisible to the agent. -187|>>>>>>> 77f9d16 (fix(bundle-builder): generate umbrella SKILL.md as discoverable entry point) -188| -189|1. **manifest.yaml** — Use `templates/manifest.yaml.tmpl`. Substitute: -190| - `{{BUNDLE_NAME}}` — the bundle name -191| - `{{PHASES}}` — each phase with its trigger keywords, entry signals, -192| typical tools, and exit signals -193| - `{{HAS_KANBAN}}` — true/false based on kanban decision -194| -195|2. **README.md** — Write from scratch (no template needed, it's prose). -196| Structure: -197| -198| ```markdown -199| # -200| -201| Generated by workflow-architect on . -202| -203| This bundle covers a -style workflow with phases. -204| -205| ## Skills -206| -207| | Skill | Trigger | When it fires | -208| |-------|---------|---------------| -209| | | | | -210| -211| ## Loading -212| -213| Skills in this bundle are loaded automatically by trigger conditions. -214| To load a specific skill: `skill_view(name='/')` -215| -216| ## Kanban -217| -218| (Only if kanban exists) This workflow maps to a kanban board with lanes. -219| ``` -220| -221|3. **Sub-skills** — For each phase in `workflow-architect:state:phases`, -222| generate a `.md` file in `skills/` using `templates/skill-skeleton.md`. -223| -224| Naming convention: `kebab-case-phase-name.md` (e.g., `morning-triage.md`). -225| -226| Each sub-skill file is a valid Agent Skills SKILL.md with: -227| - `name` matching the filename (without .md) -228| - `description` that includes trigger keywords from the phase's typical -229| openers and tools -230| - `compatibility: Compatible with any agent supporting the Agent Skills format` -231| - Body sections: -232| - **When to use** — the trigger condition in natural language -233| - **What to do** — step-by-step instructions for the agent in this phase -234| - **Transition signals** — what the user typically says or does that -235| transitions out of this phase -236| - **What to tell the user** — guidance on how the agent should communicate -237| during this phase -238| -239|4. **decision-map.md** — Use `templates/decision-map.md.tmpl`. Substitute: -240| - `{{WORKFLOW_NAME}}` — bundle name -241| - `{{PHASE_NODES}}` — phase names -242| - `{{BRANCHING}}` — decision diamonds -243| - `{{ENTRY}}` — how sessions start -244| - `{{EXITS}}` — how sessions end -245| -246|5. **AGENTS.md** — Standard agent loading instructions for this bundle. -247| Short — just says which skills exist and when to load them. -248| -249|6. **kanban/ directory** — Only if the kanban-decision-criteria.md reference -250| indicates kanban is appropriate. Generates three files: -251| -252| a) **kanban/board-setup.sh** — Use `templates/kanban-board-setup.sh.tmpl`. -253| Substitutes: -254| - `{{BOARD_SLUG}}` — bundle name (kebab-case) -255| - `{{BOARD_NAME}}` — title-case version or user-provided name -256| - `{{FIRST_PHASE_SKILL}}` — skill file for the first phase -257| - `{{FIRST_PHASE_PRIORITY}}` — priority for first-phase tasks -258| - `{{GENERATION_DATE}}` — current date -259| -260| The setup script creates the board via `hermes kanban boards create` -261| and prints instructions for adding work. -262| -263| b) **kanban/task-blueprints.yaml** — Use `templates/kanban-task-blueprints.yaml.tmpl`. -264| Substitutes: -265| - `{{BLUEPRINT_ENTRIES}}` — one blueprint entry per phase, each with: -266| - `phase:` — phase name (kebab-case) -267| - `title_template:` — e.g. "Build: {{feature}}" -268| - `skill:` — path to the sub-skill file (e.g. `my-workflow/build`) -269| - `default_priority:` — descending from first phase (highest) to last -270| - `initial_status:` — first phase = `todo`, rest = `ready` -271| - `body:` — instructions for the worker: what skill to load, -272| definition of done, and transition to next phase -273| -274| c) **kanban/README.md** — Brief usage guide explaining how to set up and -275| use the board. Structure: -276| -277| ```markdown -278| # Kanban Board: -279| -280| This workflow maps to a Hermes Kanban board with phases in sequence. -281| -282| ## Setup -283| -284| Run `kanban/board-setup.sh` to create the board: -285| ```bash -286| bash kanban/board-setup.sh -287| ``` -288| -289| The script creates the board and switches to it. If you prefer to set -290| it up manually: -291| ```bash -292| hermes kanban boards create --name "" -293| ``` -294| -295| ## Task Lifecycle -296| -297| → → -298| -299| Each phase's task depends on the previous phase's task completing. -300| When a task is done, the next phase's task auto-promotes to "ready" -301| and the dispatcher picks it up. -302| -303| ## Adding Work -304| -305| Create a task for the first phase: -306| ```bash -307| hermes kanban create "Build: " \\ -308| --skill / \\ -309| --priority 3 -310| ``` -311| -312| Then create subsequent-phase tasks with `--parent` pointing to the -313| first task's ID: -314| ```bash -315| hermes kanban create "Review: " \\ -316| --parent \\ -317| --skill / \\ -318| --priority 2 -319| ``` -320| -321| ## Task Blueprints -322| -323| See `kanban/task-blueprints.yaml` for template definitions of each -324| phase's task, including default priorities, skill mappings, and -325| worker instructions. -326| ``` -327| -328|7. **references/generated-from.md** — Metadata about the generation process: -329| -330| ```markdown -331| # Generated From -332| -333| - **Skill:** workflow-architect -334| - **Mode:** active | passive -335| - **Date:** -336| - **Archetype:** -337| - **Convergence Score:** -338| ``` -339| -340|8. **Register sub-skills with Hermes skill system** — For each sub-skill `.md` -341| file written in step 3, register it so it appears in `skills_list()` and -342| can be loaded with `skill_view()`. This is the critical step that makes -343| generated skills actually usable by the agent. -344| -345| For each sub-skill file in `skills/.md`: -346| -347| ```python -348| skill_manage(action='create', -349| name='-', -350| content=read_file('/skills/.md')['content'], -351| category='generated') -352| ``` -353| -354| This creates a proper skill directory with `SKILL.md` entry point, making -355| the sub-skill discoverable and loadable. The sub-skill's existing valid -356| Agent Skills frontmatter (name, description, license, tags) is used as-is. -357| -358| **Why separate registration is needed:** The `skill_manage()` call also -359| handles the skill directory structure (`SKILL.md` at root, not `.md` -360| in a `skills/` subdirectory). Without this step, the sub-skill files exist -361| on disk but no Hermes mechanism discovers them. Only the umbrella SKILL.md -362| (registered in step 0) would be loadable. -363| -364| **Verification:** After registering all sub-skills, verify at least one: -365| ```python -366| skill_view(name='-') -367| ``` -368| -369| If it errors, the registration failed — check that the sub-skill file's -370| frontmatter `name` field matches and the content has valid YAML. -371| -372|## Kanban Decision -373| -374|Before generating kanban files, consult `references/kanban-decision-criteria.md` -375|to decide whether a board is appropriate. The decision depends on the phases -376|and branching structure discovered: -377| -378|- If phases form a clear linear sequence (A → B → C → D), kanban adds value -379|- If branching is emergent (session depends on context), kanban is likely inappropriate -380|- If the user mentioned waiting on others, hand-offs, or status tracking, kanban is a strong fit -381| -382|Present the decision to the user: -383| -384|``` -385|"Your workflow has a [linear/emergent] structure. A kanban board [would/wouldn't] -386|add much value here because [reason]. [If yes: I'll add one to the bundle.]" -387|``` -388| -389|8. **Register sub-skills** — For each generated sub-skill `.md` file in -390| `skills/`, register it so Hermes can discover it via `skill_view()` and -391| `skills_list()`: -392| -393| ``` -394| For each sub-skill file `skills/.md`: -395| Read the file content -396| skill_manage( -397| action='create', -398| name='/', -399| content=file_content -400| ) -401| ``` -402| -403| This makes each sub-skill loadable as `skill_view('/')`. -404| The bundle name prefix prevents naming collisions with other skills. -405| -406| If `skill_manage` is not available in the agent's toolset, note this for -407| the user and suggest they run the registration manually. -408| -409|## Cleanup -410| -411|After writing all files: -412| -413|1. Verify the umbrella registered successfully: -414| ``` -415| skill_view(name='') -416| ``` -417| If it returns `status: available`, proceed. If not found, re-run the -418| `skill_manage(action='create')` call. -419| -420|2. Remove all `workflow-architect:state:*` memory entries -421| (`memory(action='remove', target='memory', old_text='workflow-architect:state:')`) + - Are any phases automatic (e.g., refine always follows draft)? + - What's the relationship between phases (sequential, branching, optional)? + ``` + + **Category choice:** Place the bundle in a category that matches where its + sub-skills live (e.g., `content` for blogging pipelines, `devops` for + deployment workflows). Ask the user if unsure. +1. **manifest.yaml** — Use `../../templates/manifest.yaml.tmpl`. Substitute: + - `{{BUNDLE_NAME}}` — the bundle name + - `{{PHASES}}` — each phase with its trigger keywords, entry signals, + typical tools, and exit signals + - `{{HAS_KANBAN}}` — true/false based on kanban decision + +2. **README.md** — Write from scratch (no template needed, it's prose). + Structure: + + ```markdown + # + + Generated by workflow-architect on . + + This bundle covers a -style workflow with phases. + + ## Skills + + | Skill | Trigger | When it fires | + |-------|---------|---------------| + | | | | + + ## Loading + + Skills in this bundle are loaded automatically by trigger conditions. + To load a specific skill: `skill_view(name='/')` + + ## Kanban + + (Only if kanban exists) This workflow maps to a kanban board with lanes. + ``` + +3. **Sub-skills** — For each phase in `workflow-architect:state:phases`, + generate a `.md` file in `skills/` using `../../templates/skill-skeleton.md`. + + Naming convention: `kebab-case-phase-name.md` (e.g., `morning-triage.md`). + + Each sub-skill file is a valid Agent Skills SKILL.md with: + - `name` matching the filename (without .md) + - `description` that includes trigger keywords from the phase's typical + openers and tools + - `compatibility: Compatible with any agent supporting the Agent Skills format` + - Body sections: + - **When to use** — the trigger condition in natural language + - **What to do** — step-by-step instructions for the agent in this phase + - **Transition signals** — what the user typically says or does that + transitions out of this phase + - **What to tell the user** — guidance on how the agent should communicate + during this phase + +4. **decision-map.md** — Use `../../templates/decision-map.md.tmpl`. Substitute: + - `{{WORKFLOW_NAME}}` — bundle name + - `{{PHASE_NODES}}` — phase names + - `{{BRANCHING}}` — decision diamonds + - `{{ENTRY}}` — how sessions start + - `{{EXITS}}` — how sessions end + +5. **AGENTS.md** — Standard agent loading instructions for this bundle. + Short — just says which skills exist and when to load them. + +6. **kanban/ directory** — Only if the kanban-decision-criteria.md reference + indicates kanban is appropriate. Generates three files: + + a) **kanban/board-setup.sh** — Use `../../templates/kanban-board-setup.sh.tmpl`. + Substitutes: + - `{{BOARD_SLUG}}` — bundle name (kebab-case) + - `{{BOARD_NAME}}` — title-case version or user-provided name + - `{{FIRST_PHASE_SKILL}}` — skill file for the first phase + - `{{FIRST_PHASE_PRIORITY}}` — priority for first-phase tasks + - `{{GENERATION_DATE}}` — current date + + The setup script creates the board via `hermes kanban boards create` + and prints instructions for adding work. + + b) **kanban/task-blueprints.yaml** — Use `../../templates/kanban-task-blueprints.yaml.tmpl`. + Substitutes: + - `{{BLUEPRINT_ENTRIES}}` — one blueprint entry per phase, each with: + - `phase:` — phase name (kebab-case) + - `title_template:` — e.g. "Build: {{feature}}" + - `skill:` — path to the sub-skill file (e.g. `my-workflow/build`) + - `default_priority:` — descending from first phase (highest) to last + - `initial_status:` — first phase = `todo`, rest = `ready` + - `body:` — instructions for the worker: what skill to load, + definition of done, and transition to next phase + + c) **kanban/README.md** — Brief usage guide explaining how to set up and + use the board. Structure: + + ```markdown + # Kanban Board: + + This workflow maps to a Hermes Kanban board with phases in sequence. + + ## Setup + + Run `kanban/board-setup.sh` to create the board: + ```bash + bash kanban/board-setup.sh + ``` + + The script creates the board and switches to it. If you prefer to set + it up manually: + ```bash + hermes kanban boards create --name "" + ``` + + ## Task Lifecycle + + → → + + Each phase's task depends on the previous phase's task completing. + When a task is done, the next phase's task auto-promotes to "ready" + and the dispatcher picks it up. + + ## Adding Work + + Create a task for the first phase: + ```bash + hermes kanban create "Build: " \\ + --skill / \\ + --priority 3 + ``` + + Then create subsequent-phase tasks with `--parent` pointing to the + first task's ID: + ```bash + hermes kanban create "Review: " \\ + --parent \\ + --skill / \\ + --priority 2 + ``` + + ## Task Blueprints + + See `kanban/task-blueprints.yaml` for template definitions of each + phase's task, including default priorities, skill mappings, and + worker instructions. + ``` + +7. **references/generated-from.md** — Metadata about the generation process: + + ```markdown + # Generated From + + - **Skill:** workflow-architect + - **Mode:** active | passive + - **Date:** + - **Archetype:** + - **Convergence Score:** + ``` + +8. **Register sub-skills with Hermes skill system** — For each sub-skill `.md` + file written in step 3, register it so it appears in `skills_list()` and + can be loaded with `skill_view()`. This is the critical step that makes + generated skills actually usable by the agent. + + For each sub-skill file in `skills/.md`: + + ```python + skill_manage(action='create', + name='-', + content=read_file('/skills/.md')['content'], + category='generated') + ``` + + This creates a proper skill directory with `SKILL.md` entry point, making + the sub-skill discoverable and loadable. The sub-skill's existing valid + Agent Skills frontmatter (name, description, license, tags) is used as-is. + + **Why separate registration is needed:** The `skill_manage()` call also + handles the skill directory structure (`SKILL.md` at root, not `.md` + in a `skills/` subdirectory). Without this step, the sub-skill files exist + on disk but no Hermes mechanism discovers them. Only the umbrella SKILL.md + (registered in step 0) would be loadable. + + **Verification:** After registering all sub-skills, verify at least one: + ```python + skill_view(name='-') + ``` + + If it errors, the registration failed — check that the sub-skill file's + frontmatter `name` field matches and the content has valid YAML. + +## Kanban Decision + +Before generating kanban files, consult `../../references/kanban-decision-criteria.md` +to decide whether a board is appropriate. The decision depends on the phases +and branching structure discovered: + +- If phases form a clear linear sequence (A → B → C → D), kanban adds value +- If branching is emergent (session depends on context), kanban is likely inappropriate +- If the user mentioned waiting on others, hand-offs, or status tracking, kanban is a strong fit + +Present the decision to the user: + +``` +"Your workflow has a [linear/emergent] structure. A kanban board [would/wouldn't] +add much value here because [reason]. [If yes: I'll add one to the bundle.]" +``` + +8. **Register sub-skills** — For each generated sub-skill `.md` file in + `skills/`, register it so Hermes can discover it via `skill_view()` and + `skills_list()`: + + ``` + For each sub-skill file `skills/.md`: + Read the file content + skill_manage( + action='create', + name='/', + content=file_content + ) + ``` + + This makes each sub-skill loadable as `skill_view('/')`. + The bundle name prefix prevents naming collisions with other skills. + + If `skill_manage` is not available in the agent's toolset, note this for + the user and suggest they run the registration manually. + +## Cleanup + +After writing all files: + +1. Verify the umbrella registered successfully: + ``` + skill_view(name='') + ``` + If it returns `status: available`, proceed. If not found, re-run the + `skill_manage(action='create')` call. + +2. Remove all `workflow-architect:state:*` memory entries + (`memory(action='remove', target='memory', old_text='workflow-architect:state:')`) 2. Remove all `workflow-architect:state:*` memory entries (`memory(action='remove', target='memory', old_text='workflow-architect:state:')`) 2. Tell the user where the bundle was written and what it contains @@ -418,4 +374,3 @@ the bundle. `skill_view(name='-')` 5. Suggest they enter the workflow via any trigger phrase covered by the umbrella's description, or by manually loading the umbrella skill -438| \ No newline at end of file diff --git a/bundles/workflow-architect/skills/interviewer/README.md b/bundles/workflow-architect/skills/interviewer/README.md new file mode 100644 index 0000000..6fd3dcd --- /dev/null +++ b/bundles/workflow-architect/skills/interviewer/README.md @@ -0,0 +1,23 @@ +# Workflow Interviewer + +## Why Install This Skill + +Guides a structured conversation that turns an informal work process into clear phases and transition signals. + +## What You Get + +| Content | Purpose | +|---|---| +| `SKILL.md` | Adaptive workflow-discovery interview | + +## Quick Start + +Load it through workflow-architect’s active mode and answer the prompts naturally. + +## Triggers + +Use when someone wants to describe, map, or formalize their workflow. + +## Requirements + +Hermes memory tools for multi-turn state. diff --git a/bundles/workflow-architect/skills/interviewer/SKILL.md b/bundles/workflow-architect/skills/interviewer/SKILL.md index ed06154..f732f93 100644 --- a/bundles/workflow-architect/skills/interviewer/SKILL.md +++ b/bundles/workflow-architect/skills/interviewer/SKILL.md @@ -188,7 +188,7 @@ entries from memory and writing the output bundle files. ## Archetype Matching -After each answer, check the `references/workflow-archetypes.md` file to see +After each answer, check the shared `../../references/workflow-archetypes.md` file to see if the user's answers match a known archetype. If they do, note it in state and use it to seed better follow-up questions (e.g., "For a morning triage workflow, people often have a 'stale items bucket' — do you have something diff --git a/bundles/workflow-architect/skills/observer/README.md b/bundles/workflow-architect/skills/observer/README.md new file mode 100644 index 0000000..b98567b --- /dev/null +++ b/bundles/workflow-architect/skills/observer/README.md @@ -0,0 +1,23 @@ +# Workflow Observer + +## Why Install This Skill + +Infers a workflow from a substantive session without interrupting the work with an interview. + +## What You Get + +| Content | Purpose | +|---|---| +| `SKILL.md` | Passive workflow-analysis instructions | + +## Quick Start + +Load it through workflow-architect’s passive mode after a session with meaningful work history. + +## Triggers + +Use when someone asks to infer or catalogue the process they just followed. + +## Requirements + +Hermes session-search and context-scanning tools. diff --git a/cli-builder/SKILL.md b/cli-builder/SKILL.md index a5c82bc..53b21fc 100644 --- a/cli-builder/SKILL.md +++ b/cli-builder/SKILL.md @@ -15,11 +15,8 @@ metadata: - https://github.com/ComposioHQ/awesome-agent-clis - https://ronnierocha.dev/blog/dont-build-mcps-build-cli-tools --- - # CLI Builder — Agent-Friendly Tool Design - ## Overview - A CLI tool is a **contract** between your code and the agent that calls it. Every design decision is part of that contract: | CLI Element | Contract Purpose | @@ -491,20 +488,7 @@ See [references/skill-wrapper-example.md](references/skill-wrapper-example.md) f ## Agent-Readiness Checklist -- [ ] No interactive prompts (`read`, `select`, `dialog`) -- [ ] All inputs via flags or env vars -- [ ] `--help` on every subcommand with examples -- [ ] `--json` output is valid parseable JSON -- [ ] `--dry-run` on every destructive command -- [ ] `--force` / `--yes` to skip confirmations -- [ ] Idempotent: second call returns no-op, not error -- [ ] Consistent `resource verb` structure -- [ ] Errors go to stderr (`>&2` or `die()`) -- [ ] `--json` mode suppresses all non-JSON stdout -- [ ] Lazy auth: `--help` and `--dry-run` work without credentials -- [ ] Exit codes: 0=success, 1=usage error, 2=runtime failure -- [ ] Live-server verified for every read endpoint -- [ ] Dry-run verified for every chained-API path +Use [the agent-readiness checklist](references/agent-readiness-checklist.md) before shipping a CLI. ## References diff --git a/cli-builder/references/agent-readiness-checklist.md b/cli-builder/references/agent-readiness-checklist.md new file mode 100644 index 0000000..3c5816e --- /dev/null +++ b/cli-builder/references/agent-readiness-checklist.md @@ -0,0 +1,16 @@ +# Agent-Readiness Checklist + +- [ ] No interactive prompts (`read`, `select`, `dialog`) +- [ ] All inputs arrive through flags or environment variables +- [ ] Every subcommand has `--help` examples +- [ ] `--json` output parses as JSON +- [ ] Every destructive operation supports `--dry-run` +- [ ] `--force` or `--yes` skips confirmation +- [ ] Repeating an operation produces a no-op rather than an error +- [ ] Commands use a consistent `resource verb` structure +- [ ] Errors go to stderr +- [ ] JSON mode emits no non-JSON stdout +- [ ] `--help` and `--dry-run` work without credentials +- [ ] Exit codes distinguish success, usage errors, and runtime failures +- [ ] Each read endpoint has a live-server verification +- [ ] Each chained API path has a dry-run verification diff --git a/crowdsec/SKILL.md b/crowdsec/SKILL.md index dbed15e..4760a3e 100644 --- a/crowdsec/SKILL.md +++ b/crowdsec/SKILL.md @@ -11,15 +11,10 @@ compatibility: Any agent supporting Agent Skills format — commands use standar metadata: source: https://docs.crowdsec.net --- - # CrowdSec Skill - CrowdSec is an open-source, collaborative security engine that detects and blocks malicious actors. It analyzes logs and HTTP requests using behavior-based patterns (scenarios) and enforces blocks through remediation components (bouncers). - ## Architecture Overview - CrowdSec has a modular, API-centric architecture. The main components: - | Component | Role | |-----------|------| | **Security Engine** (crowdsec) | Reads logs, parses them, evaluates scenarios, and produces alerts/decisions. Runs the Log Processor and Local API (LAPI). | @@ -28,9 +23,7 @@ CrowdSec has a modular, API-centric architecture. The main components: | **Remediation Components** (formerly "bouncers") | Connect to LAPI to fetch decisions and enforce blocks at various levels (firewall, reverse proxy, web server). | | **AppSec Component** | WAF subsystem that inspects HTTP requests in real-time. Lives in the Security Engine. | | **cscli** | Command-line tool to manage the entire CrowdSec stack. | - **Data flow:** Logs → Parsers (s00-raw, s01-parse, s02-enrich) → Scenarios → Alerts → LAPI → Decisions → Remediation Components → Block - > **Important:** The Security Engine alone only *detects* — it does NOT block. You must add at least one remediation component to enforce decisions. ## Quick Reference @@ -488,26 +481,7 @@ api: Client auth types: `NoClientCert`, `VerifyClientCertIfGiven` (default), `RequireAndVerifyClientCert` -## Production Best Practices - -### Gotchas - -- **Always install `crowdsecurity/whitelist-good-actors`** to prevent blocking search engines and CDNs. -- **Set `use_time_machine: true`** for any source that buffers logs before writing (S3, IIS, cloud services). -- **Persist `/var/lib/crowdsec/data`** in Docker — since v1.7.0 this is mandatory. -- **After installing collections, reload crowdsec:** `sudo systemctl reload crowdsec` -- **The `labels.type` field is mandatory** in acquisition config — without it, no parser handles the logs. -- **Bouncer API keys are shown once** — save them immediately after creation. -- **Firewall bouncers protect all services; reverse-proxy bouncers protect only proxied services.** For full protection, use both. -- **CrowdSec uses `4h` as the default ban duration** — configure profiles for longer/shorter bans. -- **The `--all` flag on `cscli list` shows available (not just installed) items.** -- **On Docker, enroll with `docker exec crowdsec cscli console enroll -e context `** since the bash command is for bare metal. -- **CrowdSec renamed "bouncers" to "remediation components"** in newer docs. You'll see both terms — they're the same thing. -- **Local override files (`config.yaml.local`) merge mappings but replace sequences** — you cannot remove a mapping key via .local. -- **profiles.yaml.local files are NOT merged** — they're read sequentially as multi-document YAML. -- **Restart CrowdSec after config changes** — `sudo systemctl restart crowdsec` (or reload). - -### See the References +## References Load the following reference files for deeper coverage of specific topics: @@ -523,29 +497,4 @@ Load the following reference files for deeper coverage of specific topics: | Production hardening | Security, TLS, performance tuning | `references/production-hardening.md` | | Hub collections list | You need to know which collection protects what | `references/hub-collections.md` | | Troubleshooting guide | Something isn't working | `references/troubleshooting.md` | - -## Verification - -After setup, verify: - -```bash -# 1. Service is running -sudo systemctl status crowdsec - -# 2. Collections are installed -sudo cscli collections list - -# 3. Bouncers are registered -sudo cscli bouncers list - -# 4. Logs are being read (check acquisition metrics) -sudo cscli metrics | grep -A5 "Acquisition" - -# 5. Test manual ban -sudo cscli decisions add --ip 198.51.100.1 --duration 5m -sudo cscli decisions list | grep 198.51.100.1 -sudo cscli decisions delete --ip 198.51.100.1 - -# 6. Confirm AppSec if enabled -sudo cscli metrics show appsec -``` +| Production operations checklist | Verifying or operating a deployment | `references/operations-checklist.md` | diff --git a/crowdsec/references/operations-checklist.md b/crowdsec/references/operations-checklist.md new file mode 100644 index 0000000..360a116 --- /dev/null +++ b/crowdsec/references/operations-checklist.md @@ -0,0 +1,31 @@ +# Production Operations Checklist + +## Gotchas + +- Install `crowdsecurity/whitelist-good-actors` to avoid blocking search engines and CDNs. +- Set `use_time_machine: true` for log sources that buffer before writing. +- Persist `/var/lib/crowdsec/data` in Docker deployments. +- Reload CrowdSec after installing collections or changing configuration. +- Set `labels.type` in acquisition configuration so parsers can handle logs. +- Save bouncer API keys when created; they are shown once. +- Use firewall and reverse-proxy remediation components where their coverage differs. +- Configure profiles deliberately instead of relying on the default four-hour decision duration. +- Treat `cscli list --all` as available items, not only installed items. +- Enroll Docker deployments from inside the CrowdSec container. +- "Bouncer" and "remediation component" refer to the same role in newer documentation. +- Local YAML overrides merge mappings but replace sequences; `profiles.yaml.local` is read as multi-document YAML. + +## Verification + +After setup, verify the service, collections, remediation components, acquisition metrics, and AppSec when enabled: + +```bash +sudo systemctl status crowdsec +sudo cscli collections list +sudo cscli bouncers list +sudo cscli metrics | grep -A5 "Acquisition" +sudo cscli decisions add --ip 198.51.100.1 --duration 5m +sudo cscli decisions list | grep 198.51.100.1 +sudo cscli decisions delete --ip 198.51.100.1 +sudo cscli metrics show appsec +``` diff --git a/forgejo-cli/SKILL.md b/forgejo-cli/SKILL.md index ebbc3a6..3c9ac53 100644 --- a/forgejo-cli/SKILL.md +++ b/forgejo-cli/SKILL.md @@ -60,8 +60,8 @@ forgejo-cli pr review --owner magnus --repo myrepo --index 1 --body "LGTM" --eve forgejo-cli pr merge --owner magnus --repo myrepo --index 3 --dry-run # Preview first forgejo-cli pr merge --owner magnus --repo myrepo --index 3 --force # Execute merge -# Merge via API (when CLI returns 405 or PR has conflicts to resolve first) -# See references/pr-merge-via-api.md for full workflow +# Merge via API (when CLI returns 405 or PR has conflicts to resolve first). +# Consult the official Forgejo API usage guide for the current request schema. # Create a PR forgejo-cli pr create --owner magnus --repo myrepo --title "feat: add auth" --head feat/add-auth --base main --body "Closes #42" @@ -73,7 +73,7 @@ forgejo-cli issue create --owner magnus --repo myrepo --title "Bug: login fails" # List repos forgejo-cli repo list --json -# Create a repo (NOT YET IMPLEMENTED in CLI — use API directly, see references/repo-creation-via-api.md) +# Create a repo (NOT YET IMPLEMENTED in CLI — use the REST API directly) # Documentation says `repo create` but the method isn't coded yet # List labels @@ -86,7 +86,7 @@ forgejo-cli --user user show ## Server Setup -The Forgejo instance runs via Docker on `phatalbert`. See `references/server-setup.md` for the docker-compose.yml, SSH port mapping details (rootless gotcha), volume strategy, and admin accounts. +The Forgejo instance runs via Docker on `phatalbert`. Consult the instance runbook for its deployment-specific details; use the official Forgejo Docker guide for supported container configuration. ## Test Suite @@ -97,7 +97,7 @@ bash ~/.hermes/scripts/forgejo-cli-test.sh ## Forgejo Docker Deployment -See `references/fj-deployment.md` for Forgejo-specific Docker patterns: rootless image quirks, SSH port config, entrypoint config generation, `INSTALL_LOCK` requirements, database setup, and the `***` secrets masking pitfall. +Use the official Forgejo Docker installation guide for supported image, volume, UID/GID, port, and upgrade practices. ## Forgejo Actions (CI/CD) @@ -200,11 +200,11 @@ curl -s -X PATCH "https://git.brandyapple.com/api/v1/repos/{owner}/{repo}/releas PATCH by tag (`/releases/tag/{tag}`) returns 404 — you must use the numeric release ID. -📄 **`references/release-workflow.md`** — Full worked example with rollback instructions, the complete API sequence, and recovery steps for release mistakes. +For the current release API schema and recovery process, consult the official Forgejo API usage guide. ## PR Review Workflow -The `references/pr-review-workflow.md` file covers the end-to-end automated code review workflow triggered by forgejo-prs webhooks: fetching diffs, composing review bodies with complex JSON, submitting reviews via API, and handling inline comments vs summary reviews. +For review endpoints and payloads, consult the official Forgejo API usage guide before automating a review workflow. ## Pitfalls @@ -286,15 +286,21 @@ with urllib.request.urlopen(req) as resp: print(f"Created #{r['number']}: {r['title']}") ``` -The same pattern works for PR creation — POST to `/pulls` instead of `/issues` with `head` and `base` fields. See `references/pr-creation-via-api.md`. +The same pattern works for PR creation — POST to `/pulls` instead of `/issues` with `head` and `base` fields. Verify the current schema in the official Forgejo API usage guide. ## Known Gaps ⚠️ | Claimed Feature | Actual Status | Workaround | |---|---|---| -| `repo create` | Not implemented (only `list`, `show`, `search` exist) | Use raw API — see `references/repo-creation-via-api.md` | +| `repo create` | Not implemented (only `list`, `show`, `search` exist) | Use the raw REST API | | `repo show` | Accepts `--owner --repo` | `repo get` in code; `repo show` alias may not exist — try `--json` on `repo list` filtered by name | -| `pr merge` | Requires `--force` or `--dry-run` flag (not obvious from help output). Returns 405 when PR isn't mergeable (branch divergence, conflicts) | API-based merge — see `references/pr-merge-via-api.md` | -| `release create` | Not implemented (no release commands exist at all) | Use raw API — see `references/release-workflow.md` | -| Standalone PR comment (merged PR) | No subcommand for commenting on already-merged PRs | Use `POST /issues/{id}/comments` — see `references/pr-review-workflow.md` | -When a CLI subcommand is missing, the Forgejo REST API at `git.brandyapple.com/api/v1` is the backup. The `references/repo-creation-via-api.md` file has the exact curl incantation for repo creation, and `references/pr-creation-via-api.md` covers PR creation. +| `pr merge` | Requires `--force` or `--dry-run` flag (not obvious from help output). Returns 405 when PR isn't mergeable (branch divergence, conflicts) | Use the REST API after resolving mergeability | +| `release create` | Not implemented (no release commands exist at all) | Use the raw REST API | +| Standalone PR comment (merged PR) | No subcommand for commenting on already-merged PRs | Use `POST /issues/{id}/comments` | +When a CLI subcommand is missing, the Forgejo REST API at `git.brandyapple.com/api/v1` is the backup. Consult the official API guide before composing a request. + +## Authoritative References + +- [Forgejo API usage](https://forgejo.org/docs/latest/user/api-usage/) +- [Forgejo Docker installation](https://forgejo.org/docs/latest/admin/installation/docker/) +- [Forgejo Actions](https://forgejo.org/docs/latest/user/actions/) diff --git a/hugo-theme/references/cover-images.md b/hugo-theme/references/cover-images.md new file mode 100644 index 0000000..6fbaa1d --- /dev/null +++ b/hugo-theme/references/cover-images.md @@ -0,0 +1,66 @@ +# Cover Images + +Use a page resource for a per-article cover image. Page resources live inside a +page bundle, alongside its `index.md` or `_index.md` file. Hugo can process +those images at build time. + +```text +content/ +└── posts/ + └── my-post/ + ├── index.md + └── cover.jpg +``` + +## Template Pattern + +Use `GetMatch` so a missing cover does not break the page. Resize the image for +the rendered width, and include intrinsic dimensions to avoid layout shift. + +```go-html-template +{{ with .Resources.GetMatch "cover.*" }} + {{ $cover := .Resize "1200x webp" }} + +{{ end }} +``` + +Use meaningful alternative text when the image conveys content; leave `alt` empty +only when it is decorative. For a hero image near the page title, omit lazy +loading when it is likely to be in the initial viewport. + +## Front Matter Path Fallback + +When a theme supports an explicit front matter path, resolve it as a page +resource first. If the image instead belongs to the global asset pipeline, use +`resources.Get` for paths below `assets/`. + +```go-html-template +{{ $path := .Params.cover | default "cover.jpg" }} +{{ with .Resources.GetMatch $path }} + {{ $cover := .Fill "1200x630 center webp" }} + +{{ end }} +``` + +## Responsive Variants + +Generate a small set of widths and use `srcset` when the same cover appears in +both card and article layouts. Keep the source image in the page bundle; Hugo +caches generated derivatives between builds. + +```go-html-template +{{ with .Resources.GetMatch "cover.*" }} + {{ $small := .Resize "640x webp" }} + {{ $large := .Resize "1200x webp" }} + +{{ end }} +``` + +Sources: [Hugo page resources](https://gohugo.io/content-management/page-resources/) and [Hugo image processing](https://gohugo.io/content-management/image-processing/). diff --git a/llamaindex/templates/agentic-rag.py b/llamaindex/templates/agentic-rag.py index b7698ea..e84c94f 100644 --- a/llamaindex/templates/agentic-rag.py +++ b/llamaindex/templates/agentic-rag.py @@ -4,6 +4,8 @@ Multi-source RAG with agent orchestration. Demonstrates pattern 2: orchestrator agent with sub-agents as tools. """ +import asyncio + from llama_index.core import VectorStoreIndex, SimpleDirectoryReader from llama_index.llms.openai import OpenAI from llama_index.core.agent.workflow import AgentWorkflow, FunctionAgent @@ -44,8 +46,13 @@ agent = FunctionAgent( tools=[product_tool, support_tool], ) -# --- Run --- -response = await agent.run( - user_msg="What are the known issues with the API rate limiting feature?" -) -print(f"Answer: {response}") +async def main() -> None: + """Run the agent from a regular Python script.""" + response = await agent.run( + user_msg="What are the known issues with the API rate limiting feature?" + ) + print(f"Answer: {response}") + + +if __name__ == "__main__": + asyncio.run(main()) diff --git a/raleigh/SKILL.md b/raleigh/SKILL.md index 1b33e93..47f19d7 100644 --- a/raleigh/SKILL.md +++ b/raleigh/SKILL.md @@ -46,14 +46,12 @@ raleigh download "Raleigh Dog Parks" -f csv -o dog_parks.csv | `download` | Export to a file | `raleigh download "Parcels" -f geojson -o parcels.geojson` | | `categories` | List data categories | `raleigh categories` | -## Global Flags +## Output Flags | Flag | Effect | |------|--------| -| `--json` | JSON output instead of table | -| `--csv` | CSV output | -| `--quiet` | Suppress extra messages | -| `--server URL` | Override API server | +| `--json` | JSON output for `catalog`, `search`, `info`, `query`, and `categories` | +| `--csv` | CSV output for `query` only | ## References