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

scripts/init_skill.py

View on GitHub
#!/usr/bin/env python3
# Copyright 2026 Serghei Iakovlev
# SPDX-License-Identifier: Apache-2.0
"""Initialize a new Agent Skill directory from template."""

import re
import sys
from pathlib import Path

NAME_PATTERN = re.compile(r"^[a-z0-9]+(-[a-z0-9]+)*$")
MAX_NAME_LENGTH = 64
RESERVED_WORDS = ["anthropic", "claude"]


def validate_name(name: str) -> list[str]:
    """Validate skill name against specification. Returns list of errors."""
    errors: list[str] = []
    if len(name) > MAX_NAME_LENGTH:
        errors.append(f"Name exceeds {MAX_NAME_LENGTH} characters ({len(name)})")
    if not NAME_PATTERN.match(name):
        errors.append(
            "Name must be lowercase alphanumeric with single hyphens, no leading/trailing hyphens"
        )
    if "--" in name:
        errors.append("Consecutive hyphens (--) not allowed")

    name_lower = name.lower().strip()
    for word in RESERVED_WORDS:
        if word in name_lower:
            errors.append(f"Reserved word '{word}' not allowed in name")
    return errors


def title_case(name: str) -> str:
    return " ".join(w.capitalize() for w in name.split("-"))


SKILL_MD = """---
name: {name}
description: >
  [TODO: What this skill does AND when to use it.
  Include specific trigger phrases, file types, and task contexts.
  Be slightly pushy - agents tend to under-trigger.
  Max 1024 characters.]
---

# {title}

[TODO: 1-2 sentence overview. What does this skill enable?]

## [First section]

[TODO: Choose a structure that fits your skill:
- Workflow: Step-by-step sequential process
- Task-based: Grouped by operation type
- Reference: Organized by domain
- Conditional: Decision tree with branches

Then delete this guidance block.]
"""


def init_skill(name: str, path: str) -> bool:
    errors = validate_name(name)
    if errors:
        for e in errors:
            print(f"  Error: {e}")
        return False

    skill_dir = Path(path).expanduser().resolve() / name

    if skill_dir.exists():
        print(f"  Error: directory already exists: {skill_dir}")
        return False

    try:
        skill_dir.mkdir(parents=True)
        (skill_dir / "SKILL.md").write_text(
            SKILL_MD.format(name=name, title=title_case(name))
        )

        print(f"  Created: {skill_dir}/")
        print("  Created: SKILL.md")
        print()
        print("Next steps:")
        print("  1. Edit SKILL.md - write the description and instructions")
        print("  2. Add scripts/, references/, or assets/ directories as needed")
        print("     If you add scripts/, include a 'Running scripts bundled with")
        print("     this skill' section in SKILL.md explaining that script paths")
        print("     are relative to SKILL.md (see make-skill/SKILL.md")
        print("     for the canonical wording). Pair each script command with a")
        print("     manual fallback so the skill still works when python3 is")
        print("     missing or the script cannot be located.")
        print("  3. Validate: python3 validate_skill.py " + str(skill_dir))
        return True

    except Exception as e:
        print(f"  Error: {e}")
        return False


if __name__ == "__main__":
    if len(sys.argv) < 4 or sys.argv[2] != "--path":
        print("Usage: init_skill.py <skill-name> --path <output-directory>")
        print()
        print("Name rules: lowercase, hyphens, max 64 chars")
        print("Prefer gerund form: processing-pdfs, analyzing-data")
        print()
        print("Examples:")
        print("  init_skill.py processing-pdfs --path .claude/skills")
        print("  init_skill.py my-workflow --path ~/.codex/skills")
        sys.exit(1)

    name = sys.argv[1]
    path = sys.argv[3]

    print(f"Initializing skill: {name}")
    print(f"Location: {path}")
    print()

    sys.exit(0 if init_skill(name, path) else 1)
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: 471kUpdated 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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated 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: 322kUpdated Claude CodeCodexVerifiedInstall