[SPEC] Agent Skills Integration (agentskills.io Standard)

Goal

Implement the agentskills.io standard into the project's Phased Spec-Driven Development (SDD) protocol. This enables modular, pull-on-demand expertise discovery and activation, ensuring context economy while providing specialized agent capabilities using a universal root .skills directory.

Context

• Current State: The project is transitioning skills from prompts/skills/ to a root .skills/ directory for better cross-system compatibility.
• Constraints: Must work with non-native skill loaders (Android Studio Gemini/Otter), Claude Code, OpenHands, and Opencode.
• Memory Path: prompts/plans/agent_skills_integration/memory/
• Files:
  • prompts/plans/sdd_implementation_v1.md (Target for update)
  • AGENTS.md (System prompt entry point)
  • prompts/agents/SPEC_WRITER.md (Persona definition)

Standards Compliance

• Architecture: SDD Protocol v3.0, persistent context management via /memory.
• Discovery: Automated via list_files or equivalent tool on .skills/.
• Native Preference: Native skill ability, if it exists, MUST be preferred when using skills. Fall back to manual emulation only if native support is unavailable.
• Context Economy: Read only YAML frontmatter during discovery; body content is "Pull-on-Demand".
• Metadata: Mandatory name, description, compatibility, and version fields.
• Activation: Explicit "Activating Skill" announcement before loading full content.
• Universal Access: Symbolic links from .claude/skills, .agents/skills, and .opencode/skills to .skills.

Impact Surface

• Dependencies: sdd_implementation_v1.md is the master protocol. Updating it affects all future spec-writing and execution.
• Consumers: All AI agents (Claude, OpenHands, Opencode, Gemini) interacting with the project.

Risk & Rollback

• Potential Risks: Complexity in renumbering might lead to broken links in other docs. Over-segmentation of skills could make discovery slow.
• Rollback Strategy: Revert changes via Git.

Phase 1: Infrastructure & Compatibility Setup

Tasks

• Task 1.1: Initialize Persistent Memory
  • Action: Create the prompts/plans/agent_skills_integration/memory/ directory.
  • Action: Create memory/discovered_artifacts.md to track all new and migrated files.
• Task 1.2: Multi-Agent Compatibility Check (Symbolic Links)
  • Requirement: You must ask if the following symbolic link directories are to be created from .skills to:
    1. For compatibility with Claude Code: .claude/skills
    2. For compatibility with OpenHands: .agents/skills
    3. For compatibility with Opencode: .opencode/skills
  • Action: If approved, create the links. If terminal access is restricted, provide instructions to the user.
• Task 1.3: Create Universal Skills Directory
  • Action: Create .skills/.gitkeep if it doesn't exist.
• Task 1.4: Update Artifact Log
  • Action: Record created links and directory structures in memory/discovered_artifacts.md.

Verification

• memory/discovered_artifacts.md exists and is populated.
• .skills/ exists as the primary repository.
• User has been consulted regarding symbolic links.
• STOP: Wait for Human Approval.

Phase 2: Skill Template Formalization & Standard Enforcement

Tasks

• Task 2.1: Integrate Skill Template
  • Action: Verify existence of prompts/templates/SKILL_TEMPLATE.md. If missing, create it using the content in the Appendix.
  • Action: Add a "Skill Development" section to SPEC_WRITER.md requiring all new skills to start by copying this template.
• Task 2.2: Compliance Audit
  • Action: Create a brief checklist in memory/discovered_artifacts.md to verify that migrated skills have the mandatory metadata fields (name, description, compatibility, version).

Verification

• SKILL_TEMPLATE.md is confirmed as the source of truth for new skills.
• SPEC_WRITER.md mandates template usage.
• STOP: Wait for Human Approval.

Phase 3: Migration & Global Path Updates

Tasks

• Task 3.1: Migrate Legacy Skills
  • Action: Move all sub-directories from prompts/skills/ to .skills/ if they don't already exist.
  • Action: Record migrated paths in memory/discovered_artifacts.md.
• Task 3.2: Update Global Discovery Paths
  • Action: Update AGENTS.md, sdd_implementation_v1.md, and sdd_validation_suite.md (if exists) to point to .skills/ instead of prompts/skills/.
  • Action: Update SPEC_WRITER.md (if exists) to require Skill Discovery before drafting.
  • Action: Ensure the "Native Preference" rule is documented in AGENTS.md and SPEC_WRITER.md (if exists), explicitly stating that if native skill ability is unavailable, agents must fall back to manual emulation of skill instructions.
• Task 3.3: Memory Sync
  • Action: Document any migration conflicts or path resolution logic in memory/discovery_log.md.

Verification

• prompts/skills/ is empty or removed.
• AGENTS.md reflects the new .skills/ path and Native Preference rule.
• STOP: Wait for Human Approval.

Phase 4: Validation & Simulation

Tasks

• Task 4.1: Discovery Simulation
  • Action: Ask the agent to list all available skills and describe one without reading its body.
• Task 4.2: Activation Simulation
  • Action: Trigger the activation of a skill and verify the persona shift and native tool usage (if applicable).
• Task 4.3: Final Memory Audit
  • Action: Finalize memory/discovered_artifacts.md and memory/discovery_log.md.

Verification

• Agent successfully identifies the skill from metadata only.
• Agent prefers native capabilities where available.
• All final deliverables are tracked in memory.

Final Deliverables

• Updated prompts/plans/sdd_implementation_v1.md
• Updated AGENTS.md
• Updated prompts/agents/SPEC_WRITER.md
• Root .skills/ repository with migrated content.
• Symbolic links (or manual instructions) for Claude, OpenHands, and Opencode.
• prompts/plans/agent_skills_integration/memory/discovered_artifacts.md
• prompts/plans/agent_skills_integration/memory/discovery_log.md

Discovery & Learning Log

• Record any unexpected behavior, hidden dependencies, or architectural discoveries here during execution.

Appendix: Skill Template

If /prompts/templates/SKILL_TEMPLATE.md is missing, use this content:

---
name: "[Skill Name]"
description: "[Brief description of when to use this skill for Task Matching]"
compatibility: [gemini-1.5-pro, claude-3.5-sonnet]
version: "1.0.0"
---

# Skill: [Skill Name]

## Purpose
[Detailed explanation of the expertise provided by this skill.]

## Guidelines & Constraints
- [Constraint 1]
- [Constraint 2]

## Trigger Logic
- This skill is activated when [Condition].

## Instructions
[Specific system instructions for the agent to adopt.]

## References
- [Link to local reference files or documentation]