Guides the design and structuring of AI agent skills for the Argus repository with multi-step phases, progressive disclosure, and dual-platform compatibility (GitHub Copilot and Claude Code / OpenCode). Use when creating new skills, reviewing existing skills, restructuring AI guidance into modular skill directories, editing SKILL.md files, or improving agent instructions.
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Um comando direto ignora o prompt de revisão. Verifique a origem antes de executá-lo.
Instruções da origem · Visualização somente leitura
name
designing-skills
description
Guides the design and structuring of AI agent skills for the Argus repository with multi-step phases, progressive disclosure, and dual-platform compatibility (GitHub Copilot and Claude Code / OpenCode). Use when creating new skills, reviewing existing skills, restructuring AI guidance into modular skill directories, editing SKILL.md files, or improving agent instructions.
Designing Skills for Argus
Build modular, task-specific AI agent skills that work across GitHub Copilot, Claude Code, and OpenCode.
Essential Principles
Capture Intent Before Writing
Interview first, write second.
Before drafting any skill files, gather concrete information about the task domain:
What specific user requests should trigger this skill? Collect 5-10 example prompts.
What does a good output look like? Get example inputs and expected outputs.
What are the failure modes? What would "bad" output look like?
Are there edge cases or ambiguous scenarios?
This front-loads the hardest design decisions. A skill written without intent capture produces generic guidance that doesn't match real usage patterns.
Description Is the Trigger
The description field controls when Claude Code / OpenCode activates the skill.
Claude decides whether to load a skill based solely on its frontmatter description. The body of SKILL.md — including "When to Use" and "When NOT to Use" sections — is only read AFTER the skill is already active. Put trigger keywords, use cases, and exclusions in the description. A bad description means wrong activations or missed activations regardless of what the body says.
GitHub Copilot discovers skills through explicit references in AGENTS.md — the description field still helps Copilot agents understand the skill's purpose.
Description constraints:
Maximum 1024 characters
No angle brackets (<, >) — they break YAML parsing in some tools
Use third-person voice: "Guides..." not "I help with..."
List triggering conditions, not workflow steps
Test the Description
Write trigger eval queries and verify activation.
A description you haven't tested is a description that doesn't work. For every skill, write 5-10 test queries:
Should-trigger queries: User prompts where this skill MUST activate (e.g., "Create a new skill for code review")
Should-NOT-trigger queries: User prompts where this skill must stay silent (e.g., "Fix the unit test for config parsing")
Read the description in isolation (without the skill body) and ask: would each query activate this skill correctly? If not, revise the description before writing the rest of the skill.
Explain the Why
Every instruction must explain WHY, not just WHAT.
LLMs follow instructions better when they understand the reasoning. "Use numbered phases" is weaker than "Use numbered phases because unnumbered prose produces unreliable execution order." The WHY gives the LLM judgment to handle cases the instruction didn't explicitly cover.
Numbered Phases
Phases must be numbered with entry and exit criteria.
Unnumbered prose instructions produce unreliable execution order. Every phase needs:
A number (Phase 1, Phase 2, ...)
Entry criteria (what must be true before starting)
Numbered actions (what to do)
Exit criteria (how to know it's done)
Progressive Disclosure
Progressive disclosure is structural, not optional.
SKILL.md stays under 500 lines. It contains only what the LLM needs for every invocation: principles, routing, quick references, and links. Detailed patterns go in references/. Step-by-step processes go in workflows/. One level deep — no reference chains.
Keep It Lean
Remove instructions that don't improve outcomes.
After testing a skill, review every instruction. If removing an instruction doesn't degrade the output quality, delete it. Bloated skills dilute LLM attention — every line competes for context. Prefer 10 precise instructions over 30 vague ones.
When to Use
Creating a new skill directory under skills/
Reviewing or refactoring an existing skill for quality
Deciding how to split content between SKILL.md, references/, and workflows/
Structuring a skill that covers a specific Argus task domain (testing, planning, coding, reviewing)
Adding platform discovery configuration for a new skill
Testing whether a skill's description triggers correctly
When NOT to Use
Writing the actual domain content of a skill (this teaches structure, not domain expertise)
Simple one-off documentation updates — edit the relevant file directly
Updating AGENTS.md without creating a skill
Debugging skill logic that's domain-specific (use the domain skill itself)
Capture intent — Interview for 5-10 example prompts, expected outputs, and failure modes
Draft description — Write trigger-focused frontmatter description; test against eval queries
Write SKILL.md — Essential principles, When to Use / When NOT to Use, quick references
Split content — Move detailed patterns to references/, step-by-step processes to workflows/
Register — Add entries to AGENTS.md skills table
Validate — Verify all links resolve, run linting, test trigger accuracy
Skill Directory Structure
Every skill follows this structure:
skills/
└── <skill-name>/ # kebab-case directory name
├── SKILL.md # Main skill definition with YAML frontmatter
├── references/ # Deep-dive reference documents
│ ├── <topic>.md # Detailed guidance on a specific topic
│ └── ...
└── workflows/ # Step-by-step processes
├── <process>.md # Numbered phases with entry/exit criteria
└── ...
SKILL.md Template
---
name: <skill-name>
description: >-
<Third-person description with trigger keywords.
Use when <specific scenarios>. Applies to <specific domains>.>
---
# <SkillTitle><One-linepurposestatement.>## Essential Principles
<3-5 non-negotiable rules, each explaining WHY>
## When to Use
<4-6 specific scenarios>
## When NOT to Use
<3-5 scenarios naming alternatives>
## <Domain-SpecificSections><Quickreferences, routingtables, decisiontrees>## Reference Index<Linkstoallsupportingfilesinreferences/ andworkflows/>## Success Criteria<Checklistforoutputvalidation>
Platform Discovery Configuration
When adding a new skill, update the platform reference file:
AGENTS.md
Add an entry to the "Skills" section in AGENTS.md:
