Agent-Skills.md

Agent Skills: Gaia Skills

Provides Gaia skill-definition maintenance guidance with clear naming, descriptions, ownership boundaries, references, and reuse decisions. Use it by following the skills-specification reference (naming, formatter shape, scope sections, references) when adding or revising a SKILL.md, and by mirroring changes across both ".claude/skills/" and ".github/skills/" trees. Use it when adding, revising, auditing, or rationalizing skills, improving invocation quality, or consolidating drifting procedural guidance.

UncategorizedID: frostaura/ai.toolkit.gaia/fa-create-skill

Repository

frostaura/ai.toolkit.gaia
frostauraLicense: MIT
3026

Install this agent skill to your local

pnpm dlx add-skill https://github.com/frostaura/ai.toolkit.gaia/tree/HEAD/plugins/foundation/skills/fa-create-skill

Skill Files

Browse the full folder contents for fa-create-skill.

Download Skill

Loading file tree…

plugins/foundation/skills/fa-create-skill/SKILL.md

Skill Metadata

Name
fa-create-skill
Description
Provides Gaia skill-definition maintenance guidance with clear naming, descriptions, ownership boundaries, references, and reuse decisions. Use it by following the skills-specification reference (naming, formatter shape, scope sections, references) when adding or revising a SKILL.md, and by mirroring changes across both ".claude/skills/" and ".github/skills/" trees. Use it when adding, revising, auditing, or rationalizing skills, improving invocation quality, or consolidating drifting procedural guidance.

Gaia Skills

Scope and when to use

Use this skill to keep Gaia's procedural layer reusable, concise, and aligned to the contract and architecture.

Use this skill when:

  • adding or revising a skill
  • auditing duplicated or drifting skill guidance
  • improving skill descriptions, section templates, or references
  • deciding whether repeated work deserves a new skill or a stronger existing one

Do not use this skill when:

  • the change is really a role-definition issue
  • the missing step is still an architecture or contract decision
  • the procedural guidance belongs in a reference file rather than SKILL.md

Required inputs

  • the current skill roster and shared references
  • the procedural gap or maintenance problem being addressed
  • naming, metadata, and specification constraints
  • any repeated patterns, overlaps, or references worth consolidating

Owned outputs

  • valid skill definitions with strong descriptions and clear triggers
  • procedural guidance that tells roles how to do recurring work
  • trimmed duplication between shared references and local skills
  • documented reasoning for adding, merging, or rejecting a skill

Decision tree

  • If the change is global workflow policy, update AGENTS.md or a shared reference.
  • If a reference can hold detailed material better than the main skill body, move it out of SKILL.md.
  • If an existing skill can absorb the new behavior cleanly, revise it instead of adding a new skill.
  • If a new skill is justified, define its scope, outputs, and anti-patterns before finalizing the metadata.

Core workflow

  1. Read the skills specification and the current Gaia skill set.
  2. Decide whether the change belongs in a skill, a reference, or the contract layer.
  3. Write or revise the skill with clear use-when, decision-tree, procedure, and recovery guidance.
  4. Keep descriptions specific enough to help discovery while staying within spec limits.
  5. Keep references focused and use them to avoid bloating the main skill body.

New-skill justification checklist

  • what repeated pattern or maintenance pain requires a reusable procedure
  • why an existing skill cannot absorb the behavior cleanly
  • what artifact or outcome the skill should own
  • what detail belongs in the main skill body versus a reference file

Failure recovery

| Failure mode | Recovery | Owner | Escalation | | ----------------------- | ---------------------------------------------------- | ---------- | -------------------------------------------- | | duplicated guidance | centralize it in shared references or the contract | maintainer | re-audit neighboring skills | | weak description | rewrite it for invocation quality within spec limits | maintainer | compare with neighboring skills | | procedural gap | add or expand the right skill | maintainer | reject if the pattern is too narrow to reuse | | skill-contract mismatch | update the skill after the contract is current | maintainer | involve architecture if the workflow changed |

Anti-patterns

  • do not move global workflow rules into every skill body
  • do not create a new skill for a one-off edge case
  • do not leave references so deep that the main skill becomes unusable
  • do not let formatter descriptions stay generic or vague

Handoff and downstream impact

  • tell maintainers whether the change belongs in the contract, a skill, or a shared reference
  • tell agent maintainers when a role file must change to invoke the revised skill correctly
  • tell architecture when skill maintenance implies a workflow-model change
  • tell engineering when the skill rewrite needs direct file edits in the repo

Examples

  • Good fit: rewrite Gaia's seven skills into a common procedural template after the contract and role layers are clarified.
  • Good fit: decide whether new line-count and description standards belong in each skill or in a shared rule.
  • Not a fit: decide who owns a delivery branch; that is role and planning work, not skill maintenance.

Completion checklist

  • the skill has a clear scope, procedure, and recovery path
  • descriptions stay within spec and still help discovery
  • duplicated guidance has been centralized where appropriate
  • references support the skill without making the main file too thin

References