Agentskills

Agent Skills (Standard)

The Agent Skills open standard provides a framework for structuring and specifying skills to ensure portability across different AI systems and agent hosts. Agent Skills work with GitHub Copilot (Cloud, CLI, and VS Code), Claude Code, OpenCode, and other compliant agents. Agent Skills are self-contained folders with instructions and bundled resources that teach AI agents specialized capabilities, unlike custom instructions which only define coding standards.

Core Principles

• Open Standard: Rely on the open standard for structure and specifications to ensure portability across different AI systems.
• Portability: Keep scripts self-contained within the skill folder to allow sharing and avoid referencing external absolute paths.
• Non-Interactive Execution: Always design skills for non-interactive flow, using specific arguments or flags to avoid stalling the agent.
• Pre-flight Inspection: Always inspect third-party skills before installing to verify content safety and avoid malicious instructions or scripts.
• Supply Chain Integrity: Prefer pinning skills to specific tags or commit SHAs to ensure deterministic behavior.
• Portable Provenance: Skills should include tracking metadata (repository, ref, tree SHA) in the SKILL.md frontmatter to allow tracking even if files are moved.
• Progressive Loading Architecture: Structure skills so detail is loaded only as needed:

1. Discovery (~100 tokens): name and description are loaded at startup.
2. Instructions (`

• Preview: gh skill preview /
• Install: gh skill install /
• Update: gh skill update --all
• Publish: gh skill publish

Runtime and CI/CD Caveats

• Discoverability: In CI/CD environments (like GitHub Actions), agents may run with workspace-scoped tools. If skills are cloned outside the workspace (e.g., ${{ runner.temp }}/.skills), they should be symlinked into the workspace (e.g., .skills/) to be discoverable by the agent.
• Trust Boundaries: When running agent workflows on pull_request_target or issue_comment triggers, the PR branch's .github/skills/ and .github/instructions/ might be checked out by platform tools. Ensure base branch skills are preserved to prevent malicious forks from injecting altered skills.

Validation Checklist

Before publishing a skill, verify:

• [ ] SKILL.md has valid frontmatter with name and description
• [ ] name is lowercase with hyphens, ≤64 characters
• [ ] description clearly states WHAT it does, WHEN to use it, and relevant KEYWORDS
• [ ] Body focuses on information Copilot wouldn't know from training data
• [ ] ## Gotchas section present if skill involves non-obvious behavior, API quirks, or common traps
• [ ] SKILL.md body under 500 lines (consider splitting into references/ at ~200 lines)
• [ ] Large workflows (>5 steps) split into references/ folder with clear links
• [ ] Scripts include help documentation and error handling
• [ ] Relative paths used for all resource references

Locally validate skills using the skills-ref reference library:

skills-ref validate ./my-skill

What to Avoid

• Placing project-specific skills in global directories.
• Referencing external absolute paths in scripts inside a skill folder.
• Hardcoding environment-specific values that break portability.
• Including interactive scripts that require user input.
• Including information the agent already knows from its training data.

References

• About agent skills
• Adding agent skills for GitHub Copilot
• Agent Skills Open Standard
• VS Code Agent Skills Documentation
• OpenCode Skills — OpenCode documentation for skills
• Documentation — Guides and tutorials
• Specification — Format details
• Example Skills — See what's possible
• Awesome Copilot Skills
• skills-ref - Reference library for Agent Skills

Related Skills

• agent-skill-md-writer:

You MUST load this skill when creating or updating specific coding agent skills.

• gh-skill:

See this skill for using the GitHub CLI (gh skill) to manage and publish Agent Skills.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Cogni-AI-OU
• Source: Cogni-AI-OU/cogni-ai-agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.