Skip to content

sergeyklay/.agents / .agents/skills/make-skill

make-skill

Verified

Use 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.

FileKindSize
SKILL.mdskill md16.7 KB
references/anti-patterns.mdmarkdown3.6 KB
references/frontmatter-fields.mdmarkdown25.3 KB
references/platform-targeting.mdmarkdown5.2 KB
references/reviewing-skills.mdmarkdown2.0 KB
references/skills-ecosystem.mdmarkdown6.2 KB
references/writing-patterns.mdmarkdown13.8 KB
scripts/init_skill.pyexecutablescript3.8 KB
scripts/validate_skill.pyexecutablescript27.5 KB

references/reviewing-skills.md

View on GitHub
# Reviewing an existing skill

The five-step audit for reviewing or improving a skill that already exists.

When the user asks to review or improve a skill, run all of these in addition to mechanical validation. Each step has a fix path, not just a diagnosis.

1. **Parse intent.** Read the frontmatter for `disable-model-invocation`, `user-invocable`, and (for Codex) `agents/openai.yaml` `policy.allow_implicit_invocation`. The intended invocation model determines what counts as a problem in the description and elsewhere.
2. **Description audit.**
   - User-invoked only? Flag any "Use when ..." trigger phrases as dead tokens — propose a terse user-facing label instead.
   - Model-invoked? Flag missing triggers, vagueness, first/second person, marketing fluff that crowds out actionable triggers, and over-broad scope without negative triggers.
3. **Platform audit.** Confirm whether the skill is single-vendor or cross-platform.
   - Single-vendor skill missing vendor extensions that would help (e.g., a Claude-only `commit` skill without `disable-model-invocation` or `argument-hint`)? Propose adding them.
   - Cross-platform skill using vendor-only fields? Propose removing them or splitting the skill.
4. **Density audit.** Scan the body and references for the patterns in `references/writing-patterns.md` § Density: hard wraps that imply meaning, blockquote-wrapped examples, ladders of nested indented bullets, "why this works" paragraphs after every example, redundant restatements of a rule already stated by a code block, single-sentence `Tip:`/`Note:` wrappers, decorative external-spec citations, intra-document anchor links (use plain "see § X below" instead), bare citation URLs that the agent will never fetch. Flag and propose tighter alternatives. Lead by example: do not write the review report itself in the style being criticized.
5. **Structural audit.** Run `scripts/validate_skill.py` for body length, reference depth, forward slashes, frontmatter validity.

The order matters. Step 1 reframes Step 2; without it, you will give bad advice about the description.
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: 472kUpdated Claude CodeCodexVerifiedInstall
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: 323kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 323kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 323kUpdated Claude CodeCodexVerifiedInstall