archagent-build-skill

ArchAstro Skill Builder

Create, edit, and publish skills — reusable instruction packages that agents invoke at runtime.

This skill assumes the ArchAgent CLI is already installed and authenticated. Install or upgrade archagent if missing, and run archagent auth login <email> if not authenticated.

What is a Skill?

A skill is a file-backed bundle anchored by a SKILL.md root file with optional supporting files. Skills use the same managed virtual-path model as scripts and workflows: skills live under skills/<slug>/..., scripts under scripts/..., and workflows under workflows/.... Agents invoke skills at runtime via the get_skill tool to load instructions on demand.

Always Start with State

Every invocation must begin by understanding the current context:

archagent auth status
archagent list skills

Determine whether the user wants to:

• create a brand-new skill,
• edit an existing skill,
• or inspect a skill before modifying it.

Routing

User wants to create a new skill

Walk through the authoring flow step by step.

1. Gather requirements:

   • What should the skill do? (purpose and scope)
   • What trigger phrases should activate it? (for the description field)
   • Does it need supporting files (templates, schemas, reference docs)?
   • Which agent(s) will use it?

2. Choose a slug: Short, lowercase, hyphen-separated identifier (e.g., order-lookup, weekly-report). This becomes the skill's permanent key.

3. Author the SKILL.md file locally:

   Create a directory structure:

   skills/<slug>/
   ├── SKILL.md              # Root file (required)
   └── references/            # Optional supporting files
       └── example.md
   

   The SKILL.md must have YAML frontmatter:

   ---
   name: <skill-name>
   description: <One-line description with trigger phrases. Be specific — this is how
     the agent decides when to invoke the skill. Include phrases like "use when...",
     "trigger phrases include...">
   ---
   
   # Skill Title
   
   Detailed instructions for the agent...