Upgrade SKILL.md from spec prose to runtime-usable agent skill

[commrelayunit]

Problem

The current SKILL.md reads more like a human-facing spec than a production runtime skill. That is not enough once the file is actually exposed to agents during runtime.

Right now, the repo is still spec-first and implementation-pending, but the SKILL.md should still be shaped like a real agent skill so that:

• agents know when to use it
• agents know when not to use it
• agents know how to execute supported workflows step by step
• agents do not invent auth patterns, endpoint behavior, or unsupported operations

User notes to incorporate

1. Frontmatter block

Every production skill should start with a YAML header including at least:

• name
• description
• compatibility / license metadata if applicable

The description field is especially important because registries and agents use it to decide when the skill should trigger.

2. Trigger / when-to-use logic

Add explicit:

• Use this skill when ...
• Do NOT use this skill when ...

Without this, agents either over-apply the skill or fail to trigger it when they should.

3. Authentication pattern

Document clearly:

• how to obtain/pass auth
• session JWT vs API-key auth split
• expected header shapes
• vault-scoped auth behavior
• what the agent should do when credentials are missing or insufficient

Agents should not be left to infer the auth model.

4. Workflow protocol with ordered steps

The spec currently describes what workflows should exist, but a real skill needs procedural execution guidance.

Example shape:

• to add a publication:
  1. resolve vault_id
  2. confirm the target vault exists
  3. POST to the items endpoint with required fields
  4. handle duplicate/conflict responses explicitly
  5. report the created/updated result clearly

5. Endpoint reference with actual shapes

Include compact operational reference for each supported route:

• auth mode
• URL pattern
• required vs optional fields
• representative success response

Even a small table is better than prose-only descriptions.

6. Error handling section

Spell out how agents should respond to common failures:

• 401
• 403
• 404
• 409
• 422
• 429
• 5xx

Without this, agents either retry forever or fail opaquely.

7. Guardrails / anti-patterns

Include explicit “do not do this” rules, e.g.:

• do not infer vault_id from name without listing/confirming first
• do not attempt tag creation before confirming API support
• do not mix up JWT management routes and API-key data routes
• do not assume frontend capabilities imply public backend support

8. Scope boundary

Document what the skill explicitly does not handle.
This belongs in SKILL.md itself, not just in the README, because agents see the skill file at runtime.

Examples:

• frontend-only Supabase flows
• unsupported admin/database actions
• capabilities that exist in the UI but not in the public API
• speculative workflows not yet implemented

Additional recommendations

Reframe SKILL.md around runtime execution

The file should be optimized for agent behavior, not just design discussion.

Recommended structure:

1. YAML frontmatter
2. What this skill is for
3. Use when / Do not use when
4. Authentication model
5. Supported workflows
6. Ordered execution protocols
7. Endpoint quick reference
8. Error handling
9. Guardrails
10. Scope boundary
11. References to detailed docs

Keep SKILL.md lean; move detailed reference material out

Use SKILL.md for:

• trigger logic
• execution protocol
• guardrails
• scope limits

Move detailed endpoint examples and longer API docs into references/ files so the runtime skill stays concise.

Make current repo status explicit inside the skill too

The README already notes this, but SKILL.md should also make clear that:

• the repo is currently spec-first
• the implementation is still pending
• current backend coverage is partial
• many desired workflows depend on future API expansion

Desired outcome

A SKILL.md that behaves like a real production agent skill:

• sharp trigger description
• clear scope boundaries
• procedural workflow guidance
• explicit auth and error-handling behavior
• compact runtime instructions with deeper references split out cleanly

Why this matters

This repo will be read by agents at runtime. If the skill is vague, agents will improvise. That usually ends badly.

[velitchko]

Addressed in 3e88b8a