sergeyklay/.agents / .agents/skills/make-skill
make-skill
VerifiedUse when creating, improving, comparing, evaluating, reviewing or packaging Agent Skills following the agentskills.io specification. Also use when deciding whether a skill is the right solution vs MCP servers, Claude Rules Files, or AGENTS.md. Handles SKILL.md authoring, frontmatter optimization, description writing, progressive disclosure, platform targeting, invocation control, vendor-specific extensions, and distribution.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 16.7 KB |
| references/anti-patterns.md | markdown | 3.6 KB |
| references/frontmatter-fields.md | markdown | 25.3 KB |
| references/platform-targeting.md | markdown | 5.2 KB |
| references/reviewing-skills.md | markdown | 2.0 KB |
| references/skills-ecosystem.md | markdown | 6.2 KB |
| references/writing-patterns.md | markdown | 13.8 KB |
| scripts/init_skill.pyexecutable | script | 3.8 KB |
| scripts/validate_skill.pyexecutable | script | 27.5 KB |
references/anti-patterns.md
View on GitHub# Skill anti-patterns
Failure modes graded by severity: Critical ones stop a skill from activating correctly, High impact ones degrade how it performs, Medium impact ones cost tokens and quality.
**Critical** (skill never activates correctly):
- **Workflow summary in `description`.** The model may skip the body if the description tells the whole story. Description triggers; body teaches. Bad: `"Analyzes git diff, identifies the change type, generates a commit message"`. Good: `"Use when generating commit messages. Handles conventional commits, scope detection, breaking changes."`
- **Vague description.** "Helps with documents" matches nothing.
- **Monolithic skill.** "Handles all dev workflows" loads slowly and triggers imprecisely. Split.
**High impact** (degrade performance):
- **README-style content.** Skills teach how, not what. Procedures with steps, not narrated context.
- **Inlining what belongs in `assets/`.** Templates with placeholders, schemas, and other output-generation patterns go in `assets/<name>.md`, referenced from SKILL.md. Inlining a per-type catalog loads every variant on every invocation and obscures the skill's structural shape. Inline only when the block is small and used unconditionally.
- **External fetch dependencies.** Network downloads at activation time are fragile. Bundle.
- **Command lists without verification.** Add explicit checks and failure handling.
- **First/second person in description.** "I can help" / "You can use" reads wrong from a system prompt.
- **Cross-platform dogma on a single-vendor skill.** Refusing `disable-model-invocation`, `allowed-tools`, or `argument-hint` on a skill that lives only in `~/.claude/skills/` is missed value. Portability is a goal, not a moral rule.
- **"Use when ..." triggers in a user-invoked-only description.** When `disable-model-invocation: true` (Claude Code) or `allow_implicit_invocation: false` (Codex), the model never reads the description. The triggers consume the user-facing label budget for nothing.
**Medium impact** (token bloat, lower quality):
- **User-guide aesthetics.** Hard wraps that imply meaningful line breaks where there are none, blockquotes around examples (use code fences), three-deep ladders of indented bullets where one tight sentence suffices, "why this works" paragraphs after every example, restating a rule in prose immediately after a code block already showing it, `Tip:`/`Note:`/`Important:` wrappers around single sentences. The reader is a model; visual decoration costs tokens with no benefit. See `references/writing-patterns.md` § Density.
- **Decorative links to external specs and intra-document anchors.** `[agentskills.io spec](https://agentskills.io/specification)`, `[Platform targeting](#platform-targeting)`, bare citation URLs at the end of a sentence — these are documentation aesthetics. The agent does not click during normal execution; the whole SKILL.md is already in context. Anchor links break on heading rename and add nothing the model could not get from "see § Platform targeting below". External URLs are noise unless the agent is genuinely expected to `WebFetch` them as part of the procedure (rare). Functional links to bundled files — `[references/foo.md](references/foo.md)` — are different: the path is the operand the agent passes to Read/bash, the link text gives loading context. Keep those.
- Verbose explanations of well-known concepts.
- Multiple equivalent options without a default.
- Windows backslash paths.
- Deep reference chains (SKILL.md → a.md → b.md).
- Time-sensitive notes ("After August 2025 ..."). Move to an "Old patterns" section.
- Inconsistent terminology.
- Heavy `MUST`s without reasoning.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |