Create Agent Skill

Purpose

Standardize the creation of new Agent Skills to ensure they are consistent, discoverable, and follow best practices.

When to Create a Skill

• Complex Tooling: When an agent needs to run a sequence of scripts or commands that are too long for the main agent prompt.
• Shared Capabilities: When multiple agents need the same capability (e.g., "Run UAT" used by UAT Tester and Quality Engineer).
• Strict Procedures: When a process requires exact adherence to a checklist or script (e.g., Release process).

Hard Rules

Must

• Create the skill in .agents/skills/<skill-name>/.
• Use kebab-case for the skill name.
• Ensure the skill name matches the parent directory name exactly.
• Ensure name is 1–64 characters, lowercase letters/numbers/hyphens only.
• Ensure name does not start or end with - and does not contain consecutive hyphens (--).
• Include a SKILL.md with valid YAML frontmatter.
• Include a description in the frontmatter (max 1024 chars).
• Create scripts/ and templates/ subdirectories only if needed.
• Use the provided template for SKILL.md.
• Update docs/workflow.md to register the new skill in the "Available Skills" table.

Must Not

• Create skills in the root .github/ directory.
• Use spaces or special characters in the skill name.
• Leave the description empty.

Best Practices

• Self-Contained: A skill should include all necessary scripts and templates within its folder.
• Progressive Disclosure: the harness only loads the skill body when the description matches the user's intent. Keep descriptions specific.
• Verification: Confirm the skill loads by asking for the task it covers in a fresh session and checking that the skill is invoked.
• Approval Minimization: Design skills to reduce the number of Maintainer approval prompts (terminal command approvals) so agents can execute workflows with minimal interruptions.
  • Prefer a small number of stable wrapper commands over many one-off commands.
  • Batch related operations into a single command where practical (and safe).
  • Prefer tool-based reads (editor tools) over shell commands for read-only actions when available.
  • Reuse existing repo scripts (e.g., scripts/uat-*.sh) instead of duplicating multi-step command sequences.
  • If a workflow is inherently risky (force-push, merge, deleting branches), keep it explicit and gated, but still consolidate the surrounding steps.

Actions

1. Gather Information

Ask the user for:

• Skill Name: Short, descriptive, kebab-case (e.g., run-uat, deploy-docs).
• Description: One sentence explaining what the skill does and when an agent should load it.
• Purpose: Detailed explanation of the skill's goal.
• Approval Plan: Which commands will run, and how to structure them to minimize approvals (prefer a small number of stable wrappers).

2. Create Directory Structure

Run the following command to create the skill directory:

mkdir -p .agents/skills/`<skill-name>`

If your skill includes scripts or templates, add those directories explicitly:

mkdir -p .agents/skills/`<skill-name>`/scripts
mkdir -p .agents/skills/`<skill-name>`/templates

3. Create SKILL.md

Read the template from .agents/skills/create-agent-skill/templates/SKILL.md and create the new SKILL.md file:

cp .agents/skills/create-agent-skill/templates/SKILL.md .agents/skills/`<skill-name>`/SKILL.md

Then, edit the file to replace the placeholders ({{skill-name}}, {{description}}, {{purpose}}) with the gathered information.

4. Update Documentation

Add the new skill to the "Available Skills" table in docs/workflow.md.

5. Verify

Check that the file structure looks like this:

.agents/skills/`<skill-name>`/
├── SKILL.md
├── scripts/
└── templates/

References

Specifications & Documentation

Example Repositories

Practical Guides