| name | agent-skills-framework |
| description | Create, update, audit, install, and use portable Agent Skills/Claude Skills with SKILL.md folders for Claude Code, Gemini CLI, Codex, and compatible AI agents. Use when the user asks about skills, skill discovery paths, cross-tool symlinks, frontmatter, bundled scripts/references/assets, progressive disclosure, or making an AI agent understand a repeatable framework or workflow. |
Agent Skills Framework
Use this skill to build portable Agent Skills: self-contained directories that teach an AI agent repeatable workflows, domain knowledge, or tool procedures without loading all details into context up front.
Core Workflow
- Identify the job the skill should make repeatable. Keep one skill focused on one capability or closely related workflow.
- Choose a canonical source folder. Prefer
.agents/skills/<skill-name> for repo-scoped team skills, or $HOME/.agents/skills/<skill-name> for personal skills shared across tools.
- Make the folder name, frontmatter
name, and invocation name identical: lowercase letters, digits, and hyphens only.
- Create
SKILL.md with YAML frontmatter and concise Markdown instructions.
- Add only useful bundled resources:
references/ for detailed docs the agent should load only when needed.scripts/ for deterministic helpers the agent can run.assets/ for templates, examples, images, schemas, boilerplate, or other output resources.agents/openai.yaml for optional Codex UI metadata.
- If multiple AI CLI tools should discover the same skill, symlink their tool-specific skill paths to the canonical folder. Do not copy the skill.
- Validate the structure, referenced files, and symlinks before finishing.
Authoring Rules
Use only name and description in frontmatter unless a product-specific or open-standard optional field is clearly required. Portability is highest when frontmatter stays minimal.
Write description as the trigger surface. Include what the skill does and when to use it. Front-load important keywords because some clients shorten descriptions in the initial skill list.
Keep SKILL.md under 500 lines. Put long explanations, specs, examples, and path matrices in references/, and link them from SKILL.md with clear "read this when..." guidance.
Write instructions for an AI agent, not for a human reader. Prefer imperative steps, decision rules, validation checks, and examples of successful behavior.
Do not add README, changelog, installation guide, or unrelated docs inside a skill folder. Those files dilute discovery and make agents load or inspect noise.
Teaching A Framework
When a skill must explain an entire framework, cover the operational surface an agent needs to act correctly:
- Purpose: what the framework is for and what problems it solves.
- Entry points: files, commands, APIs, CLIs, or directories the agent should inspect first.
- Core model: the entities, lifecycle, invariants, and how pieces connect.
- Common workflows: create, update, install, run, test, debug, publish.
- Extension points: how to add new modules, adapters, resources, or integrations.
- Failure modes: common mistakes, unsafe shortcuts, and how to recover.
- Validation: concrete commands or checks the agent must run.
Put the framework map in SKILL.md only if it is short. Move deeper API details, examples, command matrices, and troubleshooting into references/.
Repository Skills
When creating skills for a repository, also check for repo-level instructions such as AGENTS.md and user-facing docs such as README.md. If the skill describes how to work in that repo, require agents to keep those files and any architecture/workflow diagrams current with implementation changes.
Prefer one repo-specific skill for the project workflow instead of expanding a generic skill until it becomes project-specific.
Cross-Tool Discovery
Use .agents/skills/<skill-name> as the canonical repo path when possible. Then symlink compatibility paths:
mkdir -p .claude/skills .gemini/skills
ln -s ../../.agents/skills/<skill-name> .claude/skills/<skill-name>
ln -s ../../.agents/skills/<skill-name> .gemini/skills/<skill-name>
For exact Claude Code, Gemini CLI, and Codex discovery locations, plus safe symlink commands, read references/discovery-and-symlinks.md.
Validation
After creating or changing a skill, run:
python3 .agents/skills/agent-skills-framework/scripts/validate_skill.py .agents/skills/<skill-name>
If validating this skill from another current working directory, resolve the script path from the skill root.
Also inspect symlinks:
find .agents .claude .gemini -maxdepth 4 \( -type l -o -type f \) -print
References
