agentskills-io

Create, validate, and publish Agent Skills following the official open standard from agentskills.io. Use when (1) creating new skills for AI agents, (2) validating skill structure and metadata, (3) understanding the Agent Skills specification, (4) converting existing documentation into portable skills, or (5) ensuring cross-platform compatibility with Claude Code, Cursor, GitHub Copilot, and other tools.

Security Scan

The skill's requirements, files, and runtime instructions match its stated purpose of authoring/validating Agent Skills; nothing appears to request unrelated credentials or hidden installs, but you should inspect the included shell scripts before running them.

Purpose & Capability

Name/description align with the files and instructions: the SKILL.md teaches how to author and validate skills and references a validator repo. The two provided scripts (validate & bump) are reasonable for a skills repo toolset. No unrelated credentials, binaries, or config paths are requested.

Instruction Scope

Instructions direct use of the agentskills validator (via uv/uvx) and the included shell scripts (validate-skills-repo.sh, bump-changed-plugins.sh). Those actions are consistent with the stated purpose, but the instructions do tell the user/agent to run shell scripts and to create symlinks (ln -s). Running the scripts could modify files or perform git operations — the SKILL.md does not show their contents, so inspect them before execution.

Install Mechanism

No install spec is bundled with the skill; SKILL.md suggests installing the validator from its GitHub repo using uv or uvx (git+https URL). This is a standard, traceable approach and not an arbitrary binary download or obscure URL.

Credentials

The skill declares no required environment variables, no primary credential, and no config paths. That is proportional for a documentation/validation tool. The SKILL.md does not ask for unrelated secrets.

Persistence & Privilege

The skill does not set always:true and has no explicit install that grants persistent privileges. Model invocation flags are left at defaults (disable-model-invocation not set), so the skill could be invoked by the agent if platform policy allows — this is typical for utility skills but worth knowing.

Assessment

This skill appears to do what it says: authoring/validating Agent Skills. Before you run anything: (1) review the two shell scripts (scripts/validate-skills-repo.sh and scripts/bump-changed-plugins.sh) to confirm they only validate or update local metadata (and do not, for example, push commits or exfiltrate data), (2) verify the referenced validator repository (https://github.com/agentskills/agentskills) is the expected upstream, and (3) run validation steps in a sandbox or non-critical clone of your repo. If you are uncomfortable with model-initiated runs, check your platform's skill invocation settings because disable-model-invocation is not set by this skill.

Agent Skills (agentskills.io)

Create portable skills for AI agents. Works with Claude Code, Cursor, GitHub Copilot, OpenAI integrations, VS Code (symlinks enable sharing across tools).

Resources

• Specification: https://agentskills.io/specification | Validator: https://github.com/agentskills/agentskills

Structure

skill-name/
├── SKILL.md          # Required (frontmatter + instructions, <5000 tokens activation)
├── scripts/          # Optional: executable code
├── references/       # Optional: detailed docs
└── assets/           # Optional: templates, static files

Rules: Dir name = frontmatter name:. Only 3 subdirs. SKILL.md <500 lines. ~100 tokens for discovery (name+desc).

Frontmatter

Required

• name: 1-64 chars, lowercase alphanumeric-hyphens (^[a-z0-9]+(-[a-z0-9]+)*$)
• description: 1-1024 chars, include "Use when..." (discovery budget: ~100 tokens)

Optional

• license: SPDX identifier (Apache-2.0, MIT) | compatibility: Environment reqs (<500 chars)
• metadata: Key-value pairs (author, version, tags) | allowed-tools: Space-delimited tool list

Validation

# Install permanently (vs ephemeral uvx)
uv tool install git+https://github.com/agentskills/agentskills#subdirectory=skills-ref
# Or use uvx for one-shot validation
uvx --from git+https://github.com/agentskills/agentskills#subdirectory=skills-ref skills-ref validate ./skill

Command	Description
skills-ref validate <path>	Check structure, frontmatter, token budgets
skills-ref read-properties <path>	Extract metadata
skills-ref to-prompt <path>	Generate prompt format

Writing Rules

• Imperative language: "Check: command" not "You might want to..."
• Concrete examples with expected output; handle common errors with solutions
• Progressive disclosure: core in SKILL.md (<5000 tokens), details in references/

Common Errors

Error	Fix
Invalid name	Lowercase alphanumeric-hyphens only
Missing description	Add description: field with "Use when..."
Description too long	<1024 chars, move details to body
Invalid YAML	Check indentation, quote special chars
Missing SKILL.md	Filename must be exactly SKILL.md
Dir name mismatch	Directory name must match name: field

Quick Workflow

1. Create: mkdir skill-name && touch skill-name/SKILL.md
2. Add frontmatter (name, description with "Use when...")
3. Write instructions (bullets, not prose); validate: skills-ref validate ./skill-name
4. Test with AI agent, iterate; add LICENSE, push to repository

Plugin Structure (Claude Code)

plugin-name/
├── .claude-plugin/plugin.json
├── README.md, LICENSE, CHANGELOG.md  # CHANGELOG.md tracks versions
├── skills/skill-name/SKILL.md
├── agents/     # Optional: subagents (.md files)
└── examples/   # Optional: full demo projects

Distinctions: Plugin examples/ = runnable projects. Skill assets/ = static resources only.

Batch Validation & Versioning

bash scripts/validate-skills-repo.sh     # Validate all skills in repo
bash scripts/bump-changed-plugins.sh     # Auto-bump only changed plugins (semver)

Minimal Example

---
name: example-skill
description: Brief description. Use when doing X.
---
# Example Skill
## Prerequisites
- Required tools
## Instructions
1. First step: `command`
2. Second step with example
## Troubleshooting
**Error**: Message → **Fix**: Solution

Symlink Sharing

Share skills across Claude Code, Cursor, VS Code: ln -s /path/to/skills ~/.cursor/skills

References

• specification.md - Full YAML schema, token budgets
• examples.md - Complete examples across platforms
• validation.md - Error troubleshooting
• best-practices.md - Advanced patterns, symlink setup