Skip to content

Instantly share code, notes, and snippets.

@kingargyle

kingargyle/skills_protocol.md

Created March 15, 2026 22:00
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save kingargyle/6bc7e4d3b37705348fd8c29d37e91d8d to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save kingargyle/6bc7e4d3b37705348fd8c29d37e91d8d to your computer and use it in GitHub Desktop.
Download ZIP
Agent SKILLS Protocol that helps implement the agentskills.io specification to Agents that Don't support it
Raw
skills_protocol.md

[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.

Context

  • Current State: The project uses a Phased GSD protocol defined in prompts/plans/sdd_implementation_v1.md. All agent instructions are currently static and centralized.
  • Constraints: Must work with non-native skill loaders (Android Studio Gemini/Otter). Must preserve the "Memory Protocol" and subdirectory structure for plans.
  • 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

  • Discovery: Automated via list_files on prompts/skills/.
  • 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.

Impact Surface

  • Dependencies: sdd_implementation_v1.md is the master protocol. Updating it affects all future spec-writing and execution.
  • Consumers: All AI agents 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 sdd_implementation_v1.md using Git.

Phase 1: Infrastructure & Standard Setup

Tasks

  • Task 1.1: Create Skills Directory
    • Action: Create prompts/skills/.gitkeep.
  • Task 1.2: Define metadata schema
    • Action: Create a template prompts/templates/SKILL_TEMPLATE.md with the required YAML frontmatter.
  • Task 1.3: Create "Example" Skill
    • Action: Create prompts/skills/ui-refactor/SKILL.md as a reference implementation.

Verification

  • prompts/skills/ directory exists.
  • SKILL_TEMPLATE.md contains the mandatory fields.

[WAIT FOR APPROVAL]

Phase 2: Protocol Migration & Renumbering

Tasks

  • Task 2.1: Update sdd_implementation_v1.md Structure
    • Action: Insert "Phase 1: Agent Skills Integration" at the start of the "Phases" section.
    • Action: Renumber existing Phase 1 to Phase 2, Phase 2 to Phase 3, etc.
  • Task 2.2: Formalize Discovery Protocol
    • Action: Add the requirement for agents to execute list_files on prompts/skills/ at session start.
  • Task 2.3: Define "Pull-on-Demand" & Activation Workflow
    • Action: Add the mandatory announcement and persona shift logic.

Verification

  • sdd_implementation_v1.md contains the 5 mandatory architectural changes for agentskills.io.
  • All phase numbers are sequential and consistent.

[WAIT FOR APPROVAL]

Phase 3: Agent & Persona Updates

Tasks

  • Task 3.1: Update SPEC_WRITER.md
    • Action: Instruct the Spec Writer persona to check for applicable skills before drafting a spec.
  • Task 3.2: Update AGENTS.md
    • Action: Add the "Manual Skill Emulation" section for IDE-integrated assistants.
  • Task 3.3: Context Economy Enforcement
    • Action: Add explicit prohibition for reading skill bodies during discovery.

Verification

  • AGENTS.md mentions agentskills.io standard.
  • SPEC_WRITER.md includes the skill discovery step.

[WAIT FOR APPROVAL]

Phase 4: Validation

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 the example skill and verify the persona shift.

Verification

  • Agent successfully identifies the skill from metadata only.
  • Agent announces activation before reading the full skill file.

Final Deliverables

  • Updated prompts/plans/sdd_implementation_v1.md
  • Updated AGENTS.md
  • Updated prompts/agents/SPEC_WRITER.md
  • New prompts/templates/SKILL_TEMPLATE.md
  • New prompts/skills/ui-refactor/SKILL.md (Reference)

Discovery & Learning Log

  • Record any challenges with list_files or YAML parsing in the IDE environment.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment