| name | gaia-skills |
| description | Use this skill to create, revise, audit, and rationalize Gaia skills when procedural guidance, naming, descriptions, references, or ownership boundaries need maintenance. Use it when a repeated pattern deserves a reusable skill, when an existing skill has drifted from the workflow contract, when frontmatter descriptions need better invocation quality, or when the skill set should be simplified instead of expanded. Do not use it to solve a missing architecture decision or to move global workflow policy out of AGENTS.md into scattered skill files. Its output is a coherent skill set with clear procedural ownership, valid metadata, strong descriptions, and minimal duplication. |
| license | MIT |
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
- Read the skills specification and the current Gaia skill set.
- Decide whether the change belongs in a skill, a reference, or the contract layer.
- Write or revise the skill with clear use-when, decision-tree, procedure, and recovery guidance.
- Keep descriptions specific enough to help discovery while staying within spec limits.
- 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 frontmatter 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
