New: 98,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Tailnet Policy

by magnus919 in magnus919/agent-skills

Author, test, and deploy Tailscale-compatible huJSON policy files for Headscale tailnets — ACLs, Grants, Tags, Auto Approvers, Tailscale SSH rules.

MITAuto-check passedBackend & APIs

Install Tailnet Policy

skills CLI
$ npx skills add magnus919/agent-skills --skill tailnet-policy -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install magnus919/agent-skills tailnet-policy --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/magnus919/agent-skills.git skills-src && mkdir -p .claude/skills && cp -r skills-src/tailscale/skills/tailnet-policy .claude/skills/tailnet-policy && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
tailnet-policy
GitHub stars
115
Token cost
~2k tokens
SKILL.md length
532 words
Files
6 (incl. scripts)
Skills in repo
131
Repo updated
First seen
Licence
MIT

At a glance

Author, test, and deploy Tailscale-compatible huJSON policy files for Headscale tailnets — ACLs, Grants, Tags, Auto Approvers, Tailscale SSH rules.

  • Configuring access control
  • SKILL.md covers Overview, Policy Location, Writing Policy and Grants Syntax, plus 7 more sections
  • Runs Python and Shell scripts from its folder
  • Writing policy files

What it does

Tailnet Policy is an agent skill from magnus919/agent-skills. Author, test, and deploy Tailscale-compatible huJSON policy files for Headscale tailnets — ACLs, Grants, Tags, Auto Approvers, Tailscale SSH rules. Use when configuring access control, writing policy files, or troubleshooting connectivity issues caused by ACLs.

Its SKILL.md is about 2k tokens, which your agent loads only when the skill is triggered. The skill folder holds 7 other files, including scripts (for example `README.md`, `evals/evals.json` and `scripts/migrate-acls-to-grants.py`).

It sits in Backend & APIs, covering Authorization and RBAC. The repository describes itself as: Curated collection of AI agent skills for Hermes and other agent frameworks. The licence is MIT.

When your agent uses it

  • Configuring access control
  • Writing policy files
  • Troubleshooting connectivity issues caused by ACLs

Example prompts

  • “/tailnet-policy”

Requirements

  • Python 3
  • A Bash shell

What it can do on your machine

Read from SKILL.md and the folder at commit 22b4723. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Ships 3 files in scripts/ (Python and Shell), which the agent can run.

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Tailnet Policy loads about 2k tokens when it runs. Until then it costs about 69 tokens; SKILL.md has 532 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~69
When it runs · the whole SKILL.md, loaded when a task matches
~2k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from magnus919/agent-skills at commit 22b4723, republished under its MIT licence (© magnus919). 532 words, ~1,958 tokens.

Download SKILL.mdSave it as .claude/skills/tailnet-policy/SKILL.md (or your agent's skills folder). This skill also uses 5 other files; get the full folder from GitHub.
name
tailnet-policy
description
Author, test, and deploy Tailscale-compatible huJSON policy files for Headscale tailnets — ACLs, Grants, Tags, Auto Approvers, Tailscale SSH rules. Use when configuring access control, writing policy files, or troubleshooting connectivity issues caused by ACLs.
metadata.category
devops

tailnet-policy

Overview

Headscale uses Tailscale-compatible policy files written in huJSON (Human JSON — standard JSON with trailing commas and // comments). Policy files control:

  • ACLs (deprecated legacy syntax) — {action, users, ports} rules
  • Grants (modern syntax) — {src, dst, ip, proto, via} rules
  • Tags — Node identity tags (tag:dev, tag:prod)
  • TagOwners — Which users/groups can apply which tags
  • AutoApprovers — Auto-approval for subnet routers and exit nodes
  • Tailscale SSH — SSH access rules via ssh.users and ssh.action
ACLs vs Grants
FeatureACLs (legacy)Grants (modern)
Format{action: "accept", users: [...], ports: [...]}{src: [...], dst: [...], ip: [...], proto: "tcp"}
Port filteringEmbedded in ports: ["*:*"]Separate ip field for ports
Protocol filteringNot supportedproto field (tcp, udp, icmp)
Destination routingNot supportedvia field for relay/exit nodes
StatusDeprecated by TailscaleCurrent recommended syntax

Use Grants wherever possible. The migrate-acls-to-grants.py script can convert legacy ACL files automatically.

Policy Location

The policy file path is configured in Headscale's config.yaml:

yaml
policy:
  path: /etc/headscale/policy.hujson

After modifying the policy file, reload it on the Headscale server:

bash
# Reload via SIGHUP
kill -HUP $(pgrep headscale)

# Or use the convenience script
./skills/tailnet-policy/reload-headscale-policy.sh

Writing Policy

Allow-All (default-open)
hujson
{
  // Grants that allow all traffic
  "grants": [
    {
      "src": ["autogroup:member"],
      "dst": ["autogroup:member"],
      "ip": ["*:*"]
    }
  ],
  // Tag ownership
  "tagOwners": {
    "tag:dev": ["autogroup:admin"],
    "tag:prod": ["autogroup:admin"]
  }
}
Deny-All (default-closed)
hujson
{
  "grants": [
    // Only allow ICMP (ping) between all members
    {
      "src": ["autogroup:member"],
      "dst": ["autogroup:member"],
      "ip": ["*"],
      "proto": "icmp"
    }
  ],
  // Specific grants added per-service
  "tagOwners": {
    "tag:monitor": ["autogroup:admin"]
  }
}
Segmented (environments)
hujson
{
  "grants": [
    // Dev can reach dev
    {
      "src": ["tag:dev"],
      "dst": ["tag:dev"],
      "ip": ["*:*"]
    },
    // Prod can reach prod
    {
      "src": ["tag:prod"],
      "dst": ["tag:prod"],
      "ip": ["*:*"]
    },
    // Admin access to all
    {
      "src": ["autogroup:admin"],
      "dst": ["tag:dev", "tag:prod"],
      "ip": ["*:*"]
    }
  ],
  "tagOwners": {
    "tag:dev": ["autogroup:admin"],
    "tag:prod": ["autogroup:admin"]
  }
}
Tag-Based Patterns

Tags are node-level identifiers set via tailscale up --advertise-tags=tag:dev. They decouple policy from user identity.

hujson
{
  "tagOwners": {
    "tag:ci-runner":  ["autogroup:admin"],
    "tag:database":   ["autogroup:admin"],
    "tag:webserver":  ["autogroup:admin"],
    "tag:monitoring": ["autogroup:admin"]
  },
  "grants": [
    {
      "src": ["tag:monitoring"],
      "dst": ["tag:webserver", "tag:database"],
      "ip": ["*:*"]
    },
    {
      "src": ["tag:webserver"],
      "dst": ["tag:database"],
      "ip": ["tcp:5432"]
    }
  ]
}

Grants Syntax

Grants are the modern policy primitive:

hujson
{
  "grants": [
    {
      "src": ["tag:source", "user@example.com"],
      "dst": ["tag:destination", "100.64.0.1"],
      "ip": ["*:*"],                    // proto:port — "*:*" means all
      "proto": "tcp",                   // optional protocol filter
      "via": ["tag:exit-node"]          // optional via/routing
    }
  ]
}

Fields:

  • src — Source entities (tags, users, autogroups, IPs)
  • dst — Destination entities
  • ip — Protocol and port filter (e.g. tcp:80, udp:53, *:*, *)
  • proto — Protocol constraint (tcp, udp, icmp)
  • via — Route through a specific exit node or relay

Auto Approvers

Auto-approvers let specific users approve subnet routes and exit nodes without manual intervention:

hujson
{
  "autoApprovers": {
    "routes": {
      "10.0.0.0/8": ["autogroup:admin"],
      "172.16.0.0/12": ["alice@example.com"]
    },
    "exitNode": ["autogroup:admin"]
  }
}
  • routes: Maps CIDR ranges to lists of users who can auto-approve those routes
  • exitNode: Lists users who can advertise exit nodes

Autogroups

Autogroups are dynamic groups resolved by Headscale/Tailscale at runtime:

AutogroupDescription
autogroup:memberAll tailnet members
autogroup:adminTailnet admins
autogroup:taggedAll tagged nodes (any node with at least one tag)
autogroup:internetThe public internet (used for exit node routing)

Tailscale SSH Configuration

Tailscale SSH rules are configured via the ssh section:

hujson
{
  "ssh": [
    {
      "action": "accept",         // "accept" or "check"
      "src": ["autogroup:admin"],
      "dst": ["tag:webserver"],
      "users": ["root", "ubuntu"]
    },
    {
      "action": "check",          // "check" requires node-level SSH authorization
      "src": ["autogroup:member"],
      "dst": ["tag:dev"],
      "users": ["*"]
    }
  ]
}
  • action: "accept" (allow directly) or "check" (require node-level auth)
  • src: Source users/groups
  • dst: Destination tags/users
  • users: Which OS users can be SSH'd into
Show full SKILL.md (198 more words)Show less

Testing Policies

Policy files include test definitions that are validated when loaded:

hujson
{
  "grants": [...],
  "tests": [
    {
      "src": "alice@example.com",
      "dst": "tag:webserver",
      "ip": ["tcp:443"],
      "action": "accept"  // expected result
    },
    {
      "src": "bob@example.com",
      "dst": "tag:database",
      "ip": ["tcp:22"],
      "action": "drop"    // expected result
    }
  ]
}

Validate tests with:

bash
./skills/tailnet-policy/validate-policy.py --policy policy.hujson

Gotchas

  • Headscale does NOT support device posture — rules like devicePosture or device:managed are Tailscale-only
  • Headscale does NOT support IP sets — ipSets and ipprotocol are not supported
  • Headscale does NOT support OIDC groups in ACLs — groups from OIDC claims cannot be used in policy; use autogroup:admin and autogroup:member instead
  • Tag names must start with tag: and contain only lowercase letters, numbers, and hyphens
  • Policy reload via SIGHUP does not return errors on failure — always validate before reloading
  • ACL users field and Grant src field are NOT interchangeable — grants use src/dst, legacy ACLs use users/ports
  • Tests are not enforced at runtime — they only validate during parsing; a passing test does not guarantee runtime behavior

Trigger Conditions

This skill is automatically loaded when the user's message contains any of these keywords:

  • tailnet policy
  • headscale acl
  • hujson policy
  • tailscale grant
  • tagowners
  • autoapprovers
  • tailscale ssh policy
  • policy validation
  • 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.

© magnus919, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 5 other files (scripts) in tailscale/skills/tailnet-policy of magnus919/agent-skills.

  • SKILL.md
  • README.md
  • evals/evals.json
  • scripts/migrate-acls-to-grants.py
  • scripts/reload-headscale-policy.sh
  • scripts/validate-policy.py

Open the folder on GitHubat commit 22b4723

Compare with similar skills

Tailnet Policy next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Tailnet Policy compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Tailnet Policy this skillmagnus919/agent-skills115—~2kAutomated safety check: PassMIT
Configuring Horizoncoollabsio/coolify63k4 repos~898Automated safety check: PassMIT
K8s Security PoliciesCybereason-Public/owLSM28012 repos~2kAutomated safety check: PassGPL-2.0
Payloadpayloadcms/payload45k5 repos~6.2kAutomated safety check: PassMIT
Convex Setup Authspokvulcan/poker-planning1158 repos~1.8kAutomated safety check: PassMIT
Cognitoitsmostafa/aws-agent-skills1.2k1 repos~2.3kAutomated safety check: PassMIT

Similar skills

  • Configuring Horizon

    coollabsio/coolify

    A skill your agent uses whenever the user mentions Horizon by name in a Laravel context.

    63k GitHub starsUsed in 4 repos~898 tokens
    Backend & APIsAuto-check passed

  • K8s Security Policies

    Cybereason-Public/owLSM

    Comprehensive guide for implementing NetworkPolicy, PodSecurityPolicy, RBAC, and Pod Security Standards in Kubernetes.

    280 GitHub starsUsed in 12 repos~2k tokens
    Backend & APIsAuto-check passed

  • Payload

    payloadcms/payload

    A skill your agent uses when working with Payload projects (payload.config.ts, collections, fields, hooks, access control, Payload API).

    45k GitHub starsUsed in 5 repos~6.2k tokens
    Backend & APIsAuto-check passed

  • Convex Setup Auth

    spokvulcan/poker-planning

    Sets up Convex auth, identity mapping, and access control. An agent skill from spokvulcan/poker-planning.

    115 GitHub starsUsed in 8 repos~1.8k tokens
    Backend & APIsAuto-check passed

  • Cognito

    itsmostafa/aws-agent-skills

    AWS Cognito user authentication and authorization service. An agent skill from itsmostafa/aws-agent-skills.

    1.2k GitHub starsUsed in 1 repo~2.3k tokens
    Backend & APIsAuto-check passed

  • Abp Authorization

    abpframework/abp

    ABP permission system - PermissionDefinitionProvider, [Authorize] attribute, CheckPolicyAsync, IsGrantedAsync, ICurrentUser, IPermissionManager, multi-tenancy side.

    14k GitHub stars~1.3k tokensUpdated yesterday
    Backend & APIsAuto-check passed

More from magnus919/agent-skills

All 131 skills in this repo

  • Artifact Pyramids

    magnus919/agent-skills

    Organize durable agent research outputs as summaries, analysis, and evidence dossiers.

    119 GitHub stars~2.7k tokensUpdated today
    Auto-check passed

  • Ascii City Engine

    magnus919/agent-skills

    Build portable, first-person colored ASCII city engines and small GIS-derived city packs.

    119 GitHub stars~1.1k tokensUpdated today
    Auto-check passed

  • Color Management

    magnus919/agent-skills

    Manage color workflows with ICC profiles, working spaces, gamut mapping, and color science.

    119 GitHub stars~2.6k tokensUpdated today
    Auto-check: notes

  • Data Scientist

    magnus919/agent-skills

    A skill your agent uses for PhD-level expertise in data science, statistics, and machine learning: rigorous statistical analysis, experimental design, causal inference, advanced modeling, research…

    119 GitHub stars~4.1k tokensUpdated today
    Auto-check passed

  • Docker Compose

    magnus919/agent-skills

    Use Docker Compose to define, run, debug, and harden multi-container applications.

    119 GitHub stars~2k tokensUpdated today
    Auto-check: notes

  • Fpga Development

    magnus919/agent-skills

    Design, review, simulate, and verify FPGA logic using explicit RTL contracts, clock and reset models, CDC analysis, timing constraints, and reproducible implementation evidence.

    119 GitHub stars~2.7k tokensUpdated today
    Auto-check passed

Categories

Questions about Tailnet Policy

What does Tailnet Policy do?

Author, test, and deploy Tailscale-compatible huJSON policy files for Headscale tailnets — ACLs, Grants, Tags, Auto Approvers, Tailscale SSH rules. Tailnet Policy is an agent skill from magnus919/agent-skills. Author, test, and deploy Tailscale-compatible huJSON policy files for Headscale tailnets — ACLs, Grants, Tags, Auto Approvers, Tailscale SSH rules.

When should I use Tailnet Policy?

Tailnet Policy fits situations like: configuring access control; writing policy files; troubleshooting connectivity issues caused by ACLs.

How do I install Tailnet Policy in Claude Code?

Run `npx skills add magnus919/agent-skills --skill tailnet-policy -a claude-code`. Or copy the skill folder (tailscale/skills/tailnet-policy in magnus919/agent-skills) into .claude/skills/tailnet-policy in your project. Claude Code loads it when a task matches its description.

How do I install Tailnet Policy in Codex?

Run `npx skills add magnus919/agent-skills --skill tailnet-policy -a codex`. Or copy the skill folder (tailscale/skills/tailnet-policy in magnus919/agent-skills) into .agents/skills/tailnet-policy in your project. Codex loads it when a task matches its description.

Can I use Tailnet Policy in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add magnus919/agent-skills --skill tailnet-policy -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/tailnet-policy, .gemini/skills/tailnet-policy, .github/skills/tailnet-policy and .opencode/skills/tailnet-policy in your project.

What does Tailnet Policy need to run?

Going by SKILL.md and its folder, Tailnet Policy needs Python and a shell for the scripts in its folder. Our summary lists: Python 3; A Bash shell.

Does Tailnet Policy access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Tailnet Policy safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does Tailnet Policy use?

Tailnet Policy is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Tailnet Policy use?

About 2k tokens (SKILL.md is roughly 7.8k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Tailnet Policy?

Skills that share tags, products or a category with Tailnet Policy: Configuring Horizon (coollabsio/coolify, 63k stars), K8s Security Policies (Cybereason-Public/owLSM, 280 stars), Payload (payloadcms/payload, 45k stars) and Convex Setup Auth (spokvulcan/poker-planning, 115 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Tailnet Policy?

magnus919 (a GitHub user) maintains it in magnus919/agent-skills, which has 115 GitHub stars. The repository holds 131 skills in this directory. The repository was last updated on October 10, 2026.

Source: magnus919/agent-skills on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.