Agent skill
smith-xml
XML tag standards for AI prompts and documentation. Use when writing prompts, documentation, or AGENTS.md files. Covers approved tags for Claude, GPT-5, Gemini, and Harmony formats with markdown rendering rules.
Install this agent skill to your Project
npx add-skill https://github.com/tianjianjiang/smith/tree/main/smith-xml
SKILL.md
XML Tag Standards
- Load if: Writing prompts, documentation, AGENTS.md files
- Prerequisites: None
CRITICAL: Approved Tags Only (Primacy Zone)
Only use well-established XML tags. Do NOT invent placeholder-style tags.
Universal Tags (All Platforms)
<instructions>- Step-by-step guidance<task>- Specific user request<context>- Background information<examples>- Few-shot examples<constraints>- Behavioral limitations
Claude-Specific Tags
<metadata>- File/component metadata<forbidden>- Prohibited actions<required>- Mandatory requirements<related>- Cross-references<formatting>- Output format specs<thinking>- Chain-of-thought reasoning<answer>- Final output
Tag Selection Criteria
<required> = "DO this" (imperative, mandatory behavior)
- Agent MUST follow; failure causes incorrect behavior
- Use for: MUST/ALWAYS/NEVER statements, mandatory behaviors, action directives
<context> = "KNOW this" (informational, may deprioritize)
- Agent uses to inform decisions; not mandatory
- Use for: Explanations, methodologies, background, reference material
GPT-5.x Tags (Updated Dec 2025)
GPT-5/5.1 Tags:
<plan_tool_usage>- Planning and task management<context_gathering>- Search depth strategy<exploration>- Codebase investigation<verification>- Testing requirements<code_editing_rules>- Coding standards<guiding_principles>- Foundational philosophies<final_instructions>- Critical closing directives
GPT-5.2 Tags (Dec 2025):
<planning>- Scaffolds reasoning before execution<response>- Contains output after planning phase<solution_persistence>- Maintains global context across agent turns<user_updates_spec>- Defines scope boundaries<tool_preambles>- Tool usage instructions<output_verbosity_spec>- Output length/format constraints
Pattern: GPT-5.2 favors _spec suffix for instruction categories
Gemini 3 Tags (Updated Nov 2025)
<role>- Assistant identity<rules>- Behavioral guidelines<planning_process>- Analysis workflow<error_handling>- Error management<context>- Background info (universal)<instructions>- Step-by-step guidance (universal)<constraints>- Parameters (universal)<output_format>- Response structure<task>- User request (universal)<final_instruction>- Closing directive (recency zone)
Pattern: Gemini 3 uses snake_case, prefers direct/concise prompts
Harmony Format (gpt-oss-120b)
Harmony uses special tokens, NOT XML tags. Do not mix formats.
Essential tokens: <|start|>, <|end|>, <|message|>, <|channel|>, <|return|>
agentskills.io Tags
<available_skills>- Container for skill index in AGENTS.md<skill name="..." description="...">- Individual skill entry
Quick Reference
- Claude:
<required>,<forbidden>,<context>- Instructions, constraints - GPT-5.2:
<planning>,<response>,*_spectags - Agentic workflows - Gemini 3:
<rules>,<planning_process>,<output_format>- Structured output - Harmony:
<|start|>,<|end|>- Special tokens only - agentskills.io:
<available_skills>,<skill>- Skill discovery
Naming Conventions
Platform-specific patterns:
- Claude: lowercase concepts (e.g.,
<required>,<forbidden>,<context>) - GPT-5.2: snake_case with
_specsuffix (e.g.,<user_updates_spec>,<output_verbosity_spec>) - Gemini 3: snake_case (e.g.,
<planning_process>,<error_handling>)
Universal tags (work across platforms):
<context>,<instructions>,<task>,<examples>,<constraints>
Markdown Rendering
Blank lines required after opening and before closing XML tags:
<required>
- List item renders as bullet
- Another item
</required>
Without blank lines, markdown renders as literal text.
Content Organization
- Good examples →
<examples>only - Bad examples →
<forbidden>only - NEVER mix good and bad in same tag
Placeholders
Use: Backticks `placeholder` or brackets [placeholder]
Avoid: <placeholder>, {{placeholder}}
@smith-prompts/SKILL.md- Prompt engineering- @smith-guidance/SKILL.md - Agent behavior
ACTION (Recency Zone)
Before using XML tags:
- Is it a documented tag? → Use it
- Is it model-specific? → Check compatibility
- Need markdown inside? → Add blank lines
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
tianjianjiang/smith
smith-style
File naming, path standards, and conventional commits. Use when naming files, creating branches, writing commit messages, or setting up new projects. Covers underscore vs hyphen conventions, commit format, and branch naming patterns.
tianjianjiang/smith
smith-stacks
Stacked pull request workflows for large features. Use when creating stacked PRs, managing dependent PRs, or rebasing after parent merges. Covers stack creation, merge order, and squash merge handling.
tianjianjiang/smith
smith-python
Python development with uv, pytest, ruff, and type hints. Use when writing Python code, running tests, managing Python packages, or working with virtual environments. Covers import organization, type hints, pytest patterns, and environment variables.
tianjianjiang/smith
smith-principles
Fundamental coding principles (DRY, KISS, YAGNI, SOLID, HHH). Use when starting any development task, evaluating implementation approaches, or reviewing code quality. Always active as foundation for all development decisions.
tianjianjiang/smith
smith-nuxt
Nuxt 3 development patterns including auto-import stubbing for tests, environment variable conventions, and middleware testing. Use when working with Nuxt projects, testing Nuxt components/middleware, or configuring Nuxt environment variables.
tianjianjiang/smith
smith-plan
Plan tracking protocol (portable). Progress tracking with checkboxes, iteration workflow, completion/blocker signals. Use when executing multi-step plans, tracking task progress, or working from plan files. IMPORTANT - Always update the plan file after completing tasks.
Didn't find tool you were looking for?