Create Agent Skills

Create and Maintain Agent Skills

Use YAML frontmatter and Markdown headings. Keep portable instructions in the shared skill and native model/tool configuration in each harness. Resolve tools and paths through RUNTIME_TOOLS.md.

Working Rules

• Use the current request to choose the target and workflow. Ask only for material missing context; preserve existing authorization.
• Search existing skills and native capabilities before adding another owner.
• Read affected files fully before editing. Keep useful constraints and supported behavior when restructuring.
• Verify external contracts against installed/project versions, matching released packages, and current primary documentation. A skill's “latest” label is not evidence.
• Keep SKILL.md under 500 lines and link directly to conditional resources. Instructions in references must agree with the entrypoint.
• Structural validation, semantic review, local execution, and live integration are different checks. State which passed and which remain unverified.

Workflows

Authoring Tools

Resolve these paths from the actual installed skill directory. The configured ~/.agents/skills link is used below. Replace example names and output paths.

uv run python ~/.agents/skills/create-agent-skills/scripts/init_skill.py example-skill --path /chosen/skill-root
uv run --script ~/.agents/skills/create-agent-skills/scripts/quick_validate.py /chosen/skill-root/example-skill
uv run --script ~/.agents/skills/create-agent-skills/scripts/package_skill.py /chosen/skill-root/example-skill /chosen/output

The initializer creates a parseable scaffold, not finished guidance. Replace TODOs and remove unused examples. The validator checks entrypoint metadata, length, and inline local links; it does not prove reference or workflow correctness. Packaging is only needed when distribution is requested. The packager rejects symlinks and excludes its own output, .git, and Python caches; inspect all remaining members before distribution.

Run the tools' isolated regression tests with:

uv run --script ~/.agents/skills/create-agent-skills/scripts/test_skill_tools.py

References and Templates

• Format and runtime extensions
• Structure and layout choices
• Core principles and best practices
• Clear instructions and common patterns
• API credentials
• Executable helpers and script integration
• Templates
• Testing and iteration
• Validation and recovery
• Simple scaffold and router scaffold

Completion

The declared workflows and resources agree, relevant behavior checks pass, and the result works in the environments actually tested. Report remaining project, device, account, or harness checks precisely. Do not commit, push, or publish without authorization.