smith-skills
Agent skills authoring guide for AGENTS.md and SKILL.md files. Use when creating or editing agent instructions, rules, or documentation. Covers progressive disclosure, rule loading, XML tag usage, and token budget guidelines.
When & Why to Use This Skill
This Claude skill provides a comprehensive authoring guide for creating and managing agent instructions using AGENTS.md and SKILL.md files. It optimizes AI performance through progressive disclosure, structured XML tagging, and strategic token budget management, ensuring high-quality agent behavior and efficient context usage according to industry standards.
Use Cases
- Standardizing agent documentation and instruction sets across development teams using the AGENTS.md and SKILL.md framework.
- Optimizing long-context prompts to prevent 'lost-in-the-middle' performance degradation by strategically placing critical rules in the primacy zone.
- Implementing dynamic rule loading and compaction thresholds to maintain complex agent behaviors while staying within token limits.
- Enforcing strict behavioral constraints and anti-patterns using semantic XML tags like <required> and <forbidden> for more reliable AI outputs.
| name | smith-skills |
|---|---|
| description | Agent skills authoring guide for AGENTS.md and SKILL.md files. Use when creating or editing agent instructions, rules, or documentation. Covers progressive disclosure, rule loading, XML tag usage, and token budget guidelines. |
Agent Skills Authoring Guide
- Scope: Writing AGENTS.md, SKILL.md, and steering files
- Load if: Creating or editing agent instructions, rules, or documentation
- Prerequisites:
@smith-xml/SKILL.mdfor approved XML tags - Based on: agentskills.io standards
Progressive Disclosure Philosophy
Skills and rules follow 3-tier loading to minimize token usage:
- Layer 1: AGENTS.md entry point (~500 tokens, always loaded)
- Layer 2: Individual standards (<2000 tokens, on-demand by task)
- Layer 3: Detailed resources (loaded when explicitly needed)
Lost-in-the-Middle research: LLMs have U-shaped attention
- First 20% (primacy zone): CRITICAL rules,
<required>/<forbidden>tags - Middle 60%: Details, examples (weakest attention)
- Last 10% (recency zone): ACTION items, checklists,
<related>refs
Rule Loading Notification
Every AGENTS.md MUST define:
- Which files are always-active vs on-demand
- Notification format: "Loaded @file.md (reason)"
- Deactivation trigger: "Unload after N turns unused"
- Compaction thresholds: warn at 60%, critical at 70%
Enforcement: Reporting proves actual loading, not fake compliance
Critical Rules (Primacy Zone)
- Bullet lists over tables for ALL content (instructions AND reference data)
- LLMs parse bullet lists more reliably than tables
- XML tags for semantic boundaries:
<required>,<forbidden>,<context>,<examples> - Metadata blocks at file start for early loading
- Lines under 80 characters for better parsing
- No nested lists deeper than 2 levels
- Code blocks with language hints for all code examples
- Shell code blocks must be copy-paste ready - no inline comments, move descriptions outside as text or subsection titles
File Structure
AGENTS.md (entry point, <500 tokens):
- Standards index with descriptions
- Core principles summary
- Context thresholds
- Rule loading protocol
SKILL.md (Agent Skills format):
- YAML frontmatter:
name(kebab-case, max 64 chars),description(max 1024 chars) - Optional:
license,compatibility,metadata - Body: <500 lines recommended
Steering files (.md):
- Metadata block at start
- Critical rules in first 20% (primacy zone)
- Action items in last 10% (recency zone)
Skill Reference Convention
Backtick usage for skill references:
- Always-load skills (core): No backticks - @smith-principles/SKILL.md
- Dynamic skills: With backticks -
@smith-python/SKILL.md - Self-reference: Bold without @ - smith-skills
This distinguishes core skills (always in context) from contextual skills (loaded on demand).
Heading Hierarchy
- Use consistent levels (no skipping H2 → H4)
- H1: File title only
- H2: Major sections
- H3: Subsections
- Avoid H4+ (indicates over-nesting)
XML Tag Usage
Universal tags (cross-platform):
<instructions>- Step-by-step guidance<context>- Background information<examples>- Correct patterns only<constraints>- Behavioral limitations
Claude-specific:
<required>- Mandatory rules<forbidden>- Anti-patterns only<metadata>- File metadata<related>- Cross-references
- Mixing good/bad examples in same XML tag
- Inventing placeholder-style tags (
<type>,<scope>) - Markdown tables (use bullet lists for ALL content, even reference data)
- Nested lists deeper than 2 levels
- Skipped heading levels
- Inline comments inside shell code blocks
Token Budget Guidelines
- AGENTS.md entry point: <500 tokens
- Individual standard files: <2000 tokens
- SKILL.md files: <500 lines (~5000 tokens max)
- Session total: <5000 tokens (index + 1-2 active skills)
Good: Bullet list for rules
<required>
- Always use `uv` for Python packages
- Type hints on all public functions
- Run tests before committing
</required>
Good: Reference data (bullet list preferred over table)
**Context thresholds:**
- Claude: 60% warning, 70% critical
- Kiro: 70% warning, 80% critical
@smith-xml/SKILL.md- Approved XML tags and usage- @smith-ctx/SKILL.md - Context management strategies
- @smith-principles/SKILL.md - Core coding principles
ACTION (Recency Zone)
When creating AGENTS.md:
- Keep under 500 tokens
- Declare always-active files
- Define semantic activation triggers
- Add compaction thresholds
When creating skill files:
- Add
<metadata>with Load if condition - Put CRITICAL rules in first 20%
- Put ACTION items in last 10%
- Add
<related>cross-references
- Tables for instructions (use bullet lists)
- Nested lists deeper than 2 levels
- Custom/invented XML tags