Add AI Skills MVP for va-text-input

[humancompanion-usds]

Summary

• Create skills directory structure

  • Add va-text-input skill (markdown + JSON)
  • Document architectural decision to locate skills in docs repo
  • Add README, testing guide, and demo documentation
  • Skills leverage existing component-docs.json sync mechanism

  Refs Initiative: AI Skills & Agent Enablement #5155

Related Issue

Open Preview Environment

[Copilot]

Pull Request Overview

This PR introduces the AI Skills MVP for the VA Design System, creating comprehensive, machine-readable documentation for the va-text-input component to enable AI coding assistants like Claude Code to generate correct, accessible, and compliant code. The skills are strategically placed in the vets-design-system-documentation repository (rather than component-library) to enable faster iteration and leverage existing documentation workflows.

Key changes:

• Created comprehensive skill documentation for va-text-input component in both human-readable (Markdown) and machine-readable (JSON) formats
• Established skills directory structure with architectural decision documentation
• Provided testing scenarios and demonstration guides for validating skill effectiveness

Reviewed Changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
skills/components/va-text-input.skill.md	Comprehensive 840-line component guide covering props, accessibility, examples, and anti-patterns
skills/components/va-text-input.skill.json	Machine-readable 525-line JSON structure with typed prop definitions and event structures
skills/README.md	Overview documentation explaining skill structure, usage, versioning, and sync strategy
skills/TESTING.md	Test scenarios with verification checklists for validating skill effectiveness with Claude Code
skills/SKILL_DEMO.md	Live demonstration guide showing how to use skills with expected behaviors and success metrics
skills/ARCHITECTURE_DECISION.md	Architecture decision record documenting rationale for placing skills in docs repo
skills/MIGRATION_SUMMARY.md	Summary of migration from component-library to vets-design-system-documentation repo

[humancompanion-usds]

PR Update Summary - va-button Skill + AGENTS.md

Date: 2025-11-13
Added to PR: va-button component skill and AGENTS.md orchestration guide

---

📦 New Files Added

1. va-button Component Skill

Files:

• skills/components/va-button.skill.md (20KB)
• skills/components/va-button.skill.json (16KB)

Content:

• 13 props fully documented
• 1 event (component-library-analytics)
• 8 complete code examples (Web Components + React)
• 5 anti-patterns with fixes
• Comprehensive accessibility guidance (WCAG 2.2)
• Content guidelines (sentence case, clear verbs, under 35 chars)
• Critical guidance: Never use disabled buttons without justification
• Button vs. Link decision tree

Key Features:

• Variants: primary, secondary, big, continue, back
• States: loading, disabled (with accessibility warnings)
• Form integration: submit prop with prevent/skip options
• Analytics: disableAnalytics for PII protection

2. AGENTS.md Orchestration Guide

File: skills/AGENTS.md (16KB)

Content:

• Decision trees for component selection
• Skill catalog with intent classifiers
• Trigger pattern matching (high-confidence + context-dependent)
• Orchestration rules and guardrails
• Multi-skill scenario examples
• Skill combination patterns
• Example orchestration flows

Key Decision Trees:

1. Text Input vs. Other Input Types - Guides selection among va-text-input, va-select, va-radio, etc.
2. Button vs. Link - Critical decision logic for when to use buttons vs. links

Orchestration Rules:

1. Component Selection Priority (explicit mention → intent → functionality → clarification)
2. Skill Loading Strategy (single vs. multi-component requests)
3. Guardrails (anti-pattern prevention)
4. Accessibility Non-Negotiable (always applied from skills)

---

🎯 PRD Completion Status

Section 21: Implementation Task Breakdown

Task	Status	Notes
1. Scaffold directories & metadata format (MVP)	✅	Completed in initial commit
2. Create va-text-input Skill (MD + JSON)	✅	Completed in initial commit
3. Author minimal AGENTS.md and decision logic	✅	This PR update
4. Add AI issue template referencing Skill IDs	⏳	Future
5. Prototype run in Codespace (documentation)	⏳	Future
6. Copilot agent test issue & PR	⏳	Future
7. Add README/docs usage snippet	✅	Completed in initial commit
8. Baseline metrics collection approach (manual)	⏳	Future
9. Plan generation script (spec) for Phase 1	⏳	Future
10. Pattern skill (form respondent) draft	⏳	Phase 1

---

✅ Testing Results

va-button Skill Test

Scenario: Profile form with save/cancel buttons and loading state

Generated code demonstrated:

• ✅ Correct button variants (primary + secondary)
• ✅ Loading state for async actions
• ✅ Content guidance followed (sentence case, descriptive text)
• ✅ No disabled button (validates on submit)
• ✅ Proper form integration (submit prop)
• ✅ Integration with va-text-input skill
• ✅ All anti-patterns avoided

Result: PASSED - Skill generates correct, accessible code

---

📊 File Size Analysis

File	Size	PRD Target	Status
va-text-input.skill.md	28KB	<15KB	⚠️ Exceeds (comprehensive content)
va-text-input.skill.json	24KB	<8KB	⚠️ Exceeds (comprehensive content)
va-button.skill.md	20KB	<15KB	⚠️ Exceeds (comprehensive content)
va-button.skill.json	16KB	<8KB	⚠️ Exceeds (comprehensive content)
AGENTS.md	16KB	N/A	✅ Reasonable for orchestration guide

Note: Files exceed PRD size targets but contain high-value content:

• Comprehensive examples (8 per skill)
• Detailed anti-patterns with fixes
• Full accessibility guidance
• Decision trees and integration patterns
• This is acceptable for MVP; can optimize in Phase 1 if needed

---

🔑 Key Capabilities Unlocked

With These 2 Skills + AGENTS.md, AI Can Now:

1. Generate forms with validation

   • va-text-input for fields
   • va-button for submission
   • Proper error handling
   • Accessible markup

2. Build multi-step form flows

   • continue/back buttons
   • Proper progression logic
   • No disabled buttons

3. Handle async actions correctly

   • Loading states
   • Prevent double-clicks
   • Screen reader announcements

4. Make component decisions

   • Button vs. Link decision tree
   • Input type selection
   • Variant selection (primary/secondary)

5. Avoid common anti-patterns

   • No buttons for navigation
   • No disabled buttons without justification
   • No placeholder-only labels
   • No vague button text
   • No missing loading states

---

🚀 What's Next

Ready for Testing

• Designer prototype in Codespace
• Copilot agent with skill-referenced issues
• Real-world form building scenarios

Phase 1 Expansion (Next 3 Components)

Based on PRD priorities:

1. va-select - Dropdown selections
2. va-alert - Notifications and messages
3. va-modal - Dialog patterns

Plus:

• 1 pattern skill (form respondent)
• 2 cross-cutting skills (accessibility, content-style)

Immediate Opportunities

With 2 component skills + AGENTS.md, we can already test:

• Form generation from prompts
• Multi-component coordination
• Skill orchestration logic
• Anti-pattern prevention

---

💡 Usage Examples

Example 1: AI Prompt Using Skills

User:

Create a login form with email and password inputs, plus a submit button
that shows a loading spinner during authentication

AGENTS.md orchestrates:

1. Detects "email input" → loads component.va-text-input
2. Detects "password input" → loads component.va-text-input
3. Detects "submit button" + "loading spinner" → loads component.va-button

Generated code uses:

• va-text-input with type="email" and type="password"
• va-button with submit and loading props
• Proper validation on submit (no disabled button)
• All accessibility features from skills

---

Example 2: Decision Tree in Action

User:

Add a clickable element that takes users to the help page

AGENTS.md decision tree:

Is purpose navigation? YES → Use link, not button

Generated code:

<a href="/help">Get help</a>

Not:

<!-- WRONG: Button for navigation -->
<va-button text="Get help" onClick={...}></va-button>

---

📝 Commit Message

Add va-button skill and AGENTS.md orchestration guide

Component Skill:
- va-button.skill.md with 13 props, 8 examples, 5 anti-patterns
- va-button.skill.json with structured data for AI ingestion
- Comprehensive guidance on button variants, states, accessibility
- Critical anti-pattern: never use disabled buttons without justification
- Button vs. Link decision tree

Orchestration:
- AGENTS.md with decision trees for component selection
- Trigger pattern matching for va-text-input and va-button
- Multi-skill orchestration rules and guardrails
- Example flows demonstrating skill coordination
- Accessibility non-negotiable rules

Testing:
- Profile form with save/cancel buttons passes skill validation
- Loading state, proper variants, no disabled buttons
- Integration between va-text-input and va-button works correctly

Completes PRD #5155 task 3: "Author minimal AGENTS.md and decision logic"

Refs #5155

---

✅ Ready to Commit

All files are in place and tested. The PR now contains:

Initial Commit:

• va-text-input skill (MD + JSON)
• README, TESTING, SKILL_DEMO, ARCHITECTURE_DECISION, MIGRATION_SUMMARY

This Update:

• va-button skill (MD + JSON)
• AGENTS.md orchestration guide
• PR_UPDATE_SUMMARY.md (this file)

Total Skills: 2 component skills with full orchestration guide
PRD Progress: Task 3 complete (AGENTS.md), ready for Phase 1 expansion

---

Created: 2025-11-13
Status: ✅ Ready for commit and PR update

[Copilot]

Pull Request Overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 6 comments.