diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 1fff3d0..053a1c0 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -1101,7 +1101,7 @@ "./tailscale" ], "strict": false, - "description": "Self-hosted Tailscale/Headscale ecosystem: deploy and manage a Headscale control server, configure tailscale clients, manage ACL policies, node lifecycle, subnet routing, DERP relays, and backup/migration. Use when the user mentions Tailscale, Headscale, tailnet, mesh VPN, WireGuard mesh, or self-hosted VPN infrastructure." + "description": "Deploy and manage the self-hosted Tailscale/Headscale ecosystem: a Headscale control server, tailscale clients, ACL policies, node lifecycle, subnet routing, DERP relays, and backup/migration. Use when the user mentions Tailscale, Headscale, tailnet, mesh VPN, WireGuard mesh, or self-hosted VPN infrastructure." }, { "name": "technical-documentation", diff --git a/llms.txt b/llms.txt index 9156caf..6553505 100644 --- a/llms.txt +++ b/llms.txt @@ -123,7 +123,7 @@ - [stripe](stripe/SKILL.md): Read Stripe account state from a terminal or agent: balance, payment intents, and subscriptions — and perform guarded mutations like canceling a subscription — backed by a bundled stripe-cli script that is read-only first and gates every state-changing command behind a --dry-run/--yes confirmation. Use when an agent needs to answer questions about account balance, recent payments, active subscriptions, or apply a confirmed subscription cancellation. Do not use for building Stripe payments into an application (that is Stripe integration development), managing Stripe dashboard settings, or other payment processors (that is their own tooling). - [supabase](supabase/SKILL.md): Use this skill when developing applications with Supabase, running the Supabase CLI, designing migrations and RLS policies, testing database behavior, generating client types, deploying the official self-hosted Docker stack, or administering its Postgres, Auth, Storage, Realtime, Functions, API gateway, backups, upgrades, and security. Use it for managed and self-hosted projects. Do not use for generic PostgreSQL work with no Supabase services or conventions. - [systematic-debugging](systematic-debugging/SKILL.md): 4-phase root cause debugging protocol: understand bugs before fixing. Use for ANY technical issue — test failures, production bugs, unexpected behavior, performance problems, build failures, or integration issues. ESPECIALLY when under time pressure, when "one quick fix" seems obvious, or when previous fix attempts have failed. -- [tailscale](tailscale/SKILL.md): Self-hosted Tailscale/Headscale ecosystem: deploy and manage a Headscale control server, configure tailscale clients, manage ACL policies, node lifecycle, subnet routing, DERP relays, and backup/migration. Use when the user mentions Tailscale, Headscale, tailnet, mesh VPN, WireGuard mesh, or self-hosted VPN infrastructure. +- [tailscale](tailscale/SKILL.md): Deploy and manage the self-hosted Tailscale/Headscale ecosystem: a Headscale control server, tailscale clients, ACL policies, node lifecycle, subnet routing, DERP relays, and backup/migration. Use when the user mentions Tailscale, Headscale, tailnet, mesh VPN, WireGuard mesh, or self-hosted VPN infrastructure. - [technical-documentation](technical-documentation/SKILL.md): Create and review technical documentation, including READMEs, agent-facing instructions, API references, and CLI help. Use when documentation must help someone complete real work. Do not use for marketing copy, brand messaging, or long-form editorial content. - [technology-radar](technology-radar/SKILL.md): Build and maintain technology radars for adoption, trial, assessment, and hold decisions. Use when governing technology choices, build-versus-buy decisions, or engineering portfolio risk. - [telemetry](telemetry/SKILL.md): Operate the observability stack that deploys as one unit: Prometheus scrape configuration, recording and alerting rules, relabeling, retention, and high availability; OpenTelemetry Collector pipelines (receivers, processors, exporters, sampling, trace/span correlation); and Loki ingest, LogQL, retention, and label design — with a bundled read-only telemetry-check script for Prometheus rule sanity and scrape-target reachability. Use when running, tuning, or troubleshooting a Prometheus, OpenTelemetry Collector, or Loki deployment, or reviewing the collection/ingest/retention layer. Do not use for observability strategy, SLI/SLO design, or paging policy (that is platform-engineering) or Grafana dashboards, panels, and Grafana-side alerting (that is grafana). diff --git a/research-and-vault/SKILL.md b/research-and-vault/SKILL.md index 15de532..661bdaf 100644 --- a/research-and-vault/SKILL.md +++ b/research-and-vault/SKILL.md @@ -18,3 +18,7 @@ Use this thin orchestrator when a task needs the same sequence repeatedly: 5. Report the output path and unresolved gaps. This skill composes existing capabilities; it does not duplicate their methodology. If the task is a single lookup or a single note, load the domain skill directly instead. + +## When not to use + +Do not use this skill for a one-off lookup or a single note — load the domain skill directly instead. It only adds value when the same research-to-notes sequence repeats and needs to be captured durably. diff --git a/tailscale/SKILL.md b/tailscale/SKILL.md index 448d494..57de430 100644 --- a/tailscale/SKILL.md +++ b/tailscale/SKILL.md @@ -1,8 +1,8 @@ --- name: tailscale -description: 'Self-hosted Tailscale/Headscale ecosystem: deploy and manage a Headscale - control server, configure tailscale clients, manage ACL policies, node lifecycle, - subnet routing, DERP relays, and backup/migration. Use when the user mentions Tailscale, +description: 'Deploy and manage the self-hosted Tailscale/Headscale ecosystem: a + Headscale control server, tailscale clients, ACL policies, node lifecycle, subnet + routing, DERP relays, and backup/migration. Use when the user mentions Tailscale, Headscale, tailnet, mesh VPN, WireGuard mesh, or self-hosted VPN infrastructure.' license: MIT compatibility: Requires bash, Python 3.8+, jq, curl, and access to a Headscale server @@ -88,3 +88,7 @@ All scripts use `--json`, `--dry-run`, and have informative `--help` output. Scripts relative to bundle root: `scripts/` or `skills//scripts/`. See the individual sub-skill SKILL.md for detailed usage. + +## When not to use + +Do not load this umbrella when a task maps to a single sub-skill — load the matching sub-skill directly (e.g. `headscale-deploy`, `tailnet-policy`, `tailscale-client`). It assumes a self-hosted Headscale control server; for Tailscale's hosted SaaS control plane, or for non-Tailscale VPN tooling, use the appropriate network skill instead. diff --git a/tailscale/skills/headscale-backup/SKILL.md b/tailscale/skills/headscale-backup/SKILL.md index a29f4df..33304d9 100644 --- a/tailscale/skills/headscale-backup/SKILL.md +++ b/tailscale/skills/headscale-backup/SKILL.md @@ -75,3 +75,7 @@ Set up a daily cron job: - "restore headscale" - "migrate headscale" - "headscale backup" + +## When not to use + +Do not use this skill for deploying or configuring a Headscale server — load `headscale-deploy` instead, or `headscale-node-lifecycle` for node management. It covers backup, restore, and migration of an existing installation only. diff --git a/tailscale/skills/headscale-deploy/SKILL.md b/tailscale/skills/headscale-deploy/SKILL.md index dafccc3..5f43d20 100644 --- a/tailscale/skills/headscale-deploy/SKILL.md +++ b/tailscale/skills/headscale-deploy/SKILL.md @@ -118,3 +118,7 @@ Use this skill when the user says any of: - "headscale derp" - "self-hosted tailscale" - "tailscale control server" + +## When not to use + +Do not use this skill for client-side setup (load `tailscale-client` instead), for ACL/policy authoring (load `tailnet-policy`), or for day-to-day management of an already-running server. It covers initial deployment and server configuration only. diff --git a/tailscale/skills/headscale-derp/SKILL.md b/tailscale/skills/headscale-derp/SKILL.md index 0d287db..58f13c1 100644 --- a/tailscale/skills/headscale-derp/SKILL.md +++ b/tailscale/skills/headscale-derp/SKILL.md @@ -143,3 +143,7 @@ Tailscale clients automatically select the DERP region with the lowest latency. ## Trigger Conditions This skill is activated by keywords: `DERP`, `relay`, `peer relay`, `STUN`, `direct connection failed` + +## When not to use + +Do not use this skill when direct peer connections work — DERP tuning is only needed when NAT traversal fails. For general client connectivity diagnostics, load `tailscale-client` instead. diff --git a/tailscale/skills/headscale-node-lifecycle/SKILL.md b/tailscale/skills/headscale-node-lifecycle/SKILL.md index ee62c61..5771b4f 100644 --- a/tailscale/skills/headscale-node-lifecycle/SKILL.md +++ b/tailscale/skills/headscale-node-lifecycle/SKILL.md @@ -128,3 +128,7 @@ Update tags on an existing node. ``` hs-tag-node.sh --node --tags [--replace | --add] [--dry-run] [--json] ``` + +## When not to use + +Do not use this skill for installing or configuring the Tailscale client (load `tailscale-client` instead) or for ACL/policy authoring (load `tailnet-policy`). It covers node registration, tagging, listing, and decommissioning only. diff --git a/tailscale/skills/headscale-routing/SKILL.md b/tailscale/skills/headscale-routing/SKILL.md index fda9cac..c0c7b98 100644 --- a/tailscale/skills/headscale-routing/SKILL.md +++ b/tailscale/skills/headscale-routing/SKILL.md @@ -154,3 +154,7 @@ Refer to individual script help (`--help`) for usage details: | `hs-advertise-routes.sh`| Advertise subnet routes on a Tailscale node | | `hs-approve-routes.sh` | List and approve/reject routes on Headscale | | `hs-list-routes.sh` | List all routes with detailed status | + +## When not to use + +Do not use this skill for node lifecycle management (load `headscale-node-lifecycle` instead) or for writing ACL policies (load `tailnet-policy`). It covers subnet routers and exit nodes only. diff --git a/tailscale/skills/tailnet-policy/SKILL.md b/tailscale/skills/tailnet-policy/SKILL.md index 9b971dc..76f05e7 100644 --- a/tailscale/skills/tailnet-policy/SKILL.md +++ b/tailscale/skills/tailnet-policy/SKILL.md @@ -290,3 +290,7 @@ This skill is automatically loaded when the user's message contains any of these - migrate acls - /etc/headscale/policy - policy.hujson + +## When not to use + +Do not use this skill for deploying the Headscale server (load `headscale-deploy` instead) or for client connectivity issues unrelated to access control (load `tailscale-client`). It covers huJSON policy authoring and testing only. diff --git a/tailscale/skills/tailscale-client/SKILL.md b/tailscale/skills/tailscale-client/SKILL.md index a942776..751cccb 100644 --- a/tailscale/skills/tailscale-client/SKILL.md +++ b/tailscale/skills/tailscale-client/SKILL.md @@ -162,3 +162,7 @@ This skill should be loaded when the user mentions any of the following: - Tailscale SSH, Serve, MagicDNS, or Taildrop configuration - Troubleshooting "tailscaled not running" or "no connection" - Interpreting `tailscale status`, `tailscale ping`, or `tailscale netcheck` output + +## When not to use + +Do not use this skill for server-side Headscale deployment (load `headscale-deploy` instead) or for ACL/policy authoring (load `tailnet-policy`). It covers client installation, authentication, and diagnostics only. diff --git a/workflow-architect/SKILL.md b/workflow-architect/SKILL.md index afa964d..0e6f413 100644 --- a/workflow-architect/SKILL.md +++ b/workflow-architect/SKILL.md @@ -120,3 +120,7 @@ with these dimensions: No environment variables required. State is stored via memory tool with the prefix `workflow-architect:state:` so it persists across turns during multi-turn interviews. + +## When not to use + +Do not use this skill for one-off task help or when there is no repeatable multi-phase workflow worth capturing — a standalone skill is a better fit. If you already have a well-defined process and only need it packaged, generate the bundle directly rather than re-running an interview. diff --git a/workflow-architect/skills/bundle-builder/SKILL.md b/workflow-architect/skills/bundle-builder/SKILL.md index 0076216..ace2e02 100644 --- a/workflow-architect/skills/bundle-builder/SKILL.md +++ b/workflow-architect/skills/bundle-builder/SKILL.md @@ -1,9 +1,8 @@ --- 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. +description: Render accumulated workflow state from memory into a valid Agent Skills + bundle directory for workflow-architect, 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: @@ -373,3 +372,7 @@ After writing all files: `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 + +## When not to use + +Do not load this skill without a converged workflow model — it requires the `workflow-architect:state:*` entries produced by the interviewer or observer. If the workflow has not been discovered yet, load the interviewer (active) or observer (passive) first. diff --git a/workflow-architect/skills/interviewer/SKILL.md b/workflow-architect/skills/interviewer/SKILL.md index a9a3497..21aa88c 100644 --- a/workflow-architect/skills/interviewer/SKILL.md +++ b/workflow-architect/skills/interviewer/SKILL.md @@ -1,9 +1,8 @@ --- name: interviewer -description: The active interrogation sub-skill for workflow-architect. Guides the - user through 8-15 adaptive questions to discover their workflow phases, branching - signals, tool preferences, and friction points. Loaded by the umbrella workflow-architect - skill when running in active mode. +description: Discover the user's workflow through 8-15 adaptive questions for + workflow-architect, mapping phases, branching signals, tool preferences, and friction + points. Loaded by the umbrella workflow-architect skill when running in active mode. license: MIT compatibility: Hermes Agent — uses memory tool for state persistence metadata: @@ -192,3 +191,7 @@ 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 like that?") + +## When not to use + +Do not use this skill for passive observation (load the observer instead), or when the user prefers you to infer from what they already did rather than be interrogated. It is for active, interactive discovery only. diff --git a/workflow-architect/skills/observer/SKILL.md b/workflow-architect/skills/observer/SKILL.md index a38d6a5..6ac360b 100644 --- a/workflow-architect/skills/observer/SKILL.md +++ b/workflow-architect/skills/observer/SKILL.md @@ -1,8 +1,8 @@ --- name: observer -description: The passive observation sub-skill for workflow-architect. Loaded silently, - it stays dormant until a trigger phrase activates it. On activation, it scans the - current session context to infer the user's workflow from what actually happened. +description: Monitor a session passively to infer the user's workflow from what + actually happened, staying dormant until a trigger phrase activates observation + for workflow-architect. license: MIT compatibility: Hermes Agent — uses session_search and context scanning metadata: @@ -109,3 +109,7 @@ When a trigger phrase is detected: captures richer intentional data. - **Silent mode:** The observer does not announce itself when loading. This is intentional — passive mode is meant to be invisible until triggered. + +## When not to use + +Do not use this skill for interactive discovery (load the interviewer instead), or when the session context is too thin to infer reliable patterns — active interrogation is more effective there. It is for passively observing an existing session only.