Stats
Actions
Tags
From box-factory
How to build Agent Skills — the default format for all new skills. Covers Claude skills, the open AgentSkills spec, cross-platform gotchas, portability decisions, and graceful degradation. Use when creating or reviewing any skill.
How this skill is triggered — by the user, by Claude, or both
Slash command
/box-factory:agent-skillsThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Guidance for building portable skills using the open AgentSkills spec. For the official spec and supported agents list:
Guidance for building portable skills using the open AgentSkills spec. For the official spec and supported agents list:
skill-creator)For Claude-specific components beyond skills (agents, hooks, plugins, marketplaces), see the claude-components skill.
Not every skill should be universal. Use this framework:
Make it universal when:
Keep it Claude-specific when:
Hybrid approach — universal core, Claude extras:
Claude has named tools (Read, Edit, Bash, Grep, Glob). Other agents have different tool names or capabilities. In universal skills:
path/to/file"Agents map natural language to their own tool implementations. Let them.
Two tests for a skill's content:
Include: user-specific preferences and workflows (the user's preferred approach when multiple valid ones exist), edge cases agents would miss, decision frameworks for ambiguous situations, post-training technology, integration patterns specific to this project.
Exclude: basic commands for well-known tools, standard workflows, general best practices, anything expressible as a single sentence (put in CLAUDE.md or equivalent instead), directory structures or file listings discoverable from the filesystem.
Applying the test honestly: Claude has a strong tendency to assume it knows whether something is a real problem rather than actually verifying. When evaluating whether guidance is needed, fetch the relevant official docs and check against real behavior before concluding "the agent already knows this." If you skip verification, you will cut guidance that is actually load-bearing.
When a skill is loaded, it may be the only guidance the agent has. If the skill needs a piece of knowledge to do its job, that knowledge must be in the skill — not in a sibling skill the agent may not have loaded. Duplicate shared guidance across skills rather than cross-referencing it. Referencing another skill to route to it ("for skills, use agent-skills") is fine — that's a handoff, not a dependency.
The AgentSkills spec establishes .agents/skills/ as the cross-client skill discovery path. Skills placed there are discoverable by all supporting agents without client-specific directories:
| Scope | Path | Purpose |
|---|---|---|
| Project | .agents/skills/<skill-name> | Cross-client interoperability |
| Project | .<client>/skills/<skill-name> | Client-specific only |
When creating or updating a plugin that bundles skills, consider whether any skills are purely knowledge-based and could live in .agents/skills/ for broader reach. Claude-specific skills (those using hooks, sub-agents, or plugin infrastructure) should stay in .claude/skills/ or the plugin directory.
name and description Are RequiredThe AgentSkills spec requires name and description; Claude Code treats them as optional. Always include both. Treat them as required regardless of what any individual agent's docs say.
npx claudepluginhub racurry/neat-little-package --plugin box-factoryReference for Agent Skills Open Standard. Guides authoring portable skills for Claude Code, Cursor, VS Code, and 20+ AI agents. Covers frontmatter schema, naming rules, directory structure, validation.
Guides creation of Agent Skills with progressive disclosure, best practices, structure, and categories. Use when building new skills or understanding skill format.
Guides creation of modular Agent Skills with progressive disclosure, covering skill structure, SKILL.md format, and best practices for capability uplift and encoded preference categories.