agent-slack skill format background research (PR #24)

skill-format-claude.md

Agent Skills Format: Deep Research Report

Analysis of PR #24, the Agent Skills specification, and CLI-wrapping skill patterns across the ecosystem.

---

Table of Contents

1. Executive Summary
2. PR #24 Analysis
3. The Agent Skills Specification (Authoritative Source)
4. Anthropic's Official Best Practices
5. Ecosystem Survey: CLI-Wrapping Skills
6. Comparative Analysis: Single-File vs Multi-File
7. Verdict on PR #24 Changes
8. References

---

Executive Summary

PR #24 proposes consolidating agent-slack's skill from 4 files (SKILL.md + 3 reference docs) into a single self-contained SKILL.md with install instructions and a unified command reference. Based on authoritative sources -- the official Agent Skills Specification at agentskills.io and Anthropic's published best practices -- the PR's direction is partially correct but goes too far in consolidation.

Key findings:

Change in PR #24	Verdict	Reasoning
Added install instructions	Correct	Best practices say "don't assume tools are installed"
One big command reference block	Partially wrong	Spec recommends < 500 lines in SKILL.md; detailed refs belong in references/
Removed reference files entirely	Wrong	Spec explicitly defines references/ as a supported directory; progressive disclosure is a core design principle
Split auth by platform	Correct	Clearer for cross-platform users

---

PR #24 Analysis

PR: stablyai/agent-slack#24 - "fix[skill]: consolidate into single self-contained SKILL.md" Author: TimPietrusky

What changed

1. Added install instructions -- curl one-liner + npm i -g so agents can guide users through installation
2. Split auth by platform -- macOS (automatic) vs Linux/Windows (manual) with clear headings
3. Added parse-curl auth guide -- step-by-step DevTools instructions
4. One big command reference block -- every command as a commented one-liner (cites runpodctl skill as precedent)
5. Merged reference docs -- targets, output shapes, and flags all inlined into SKILL.md
6. Removed reference files -- deleted commands.md, targets.md, output.md

PR's stated rationale

"Agents load one file and have everything they need -- no cross-referencing. Easier to maintain -- one place to update."

Current state (before PR)

• SKILL.md: 116 lines (workflow-focused, references 3 external docs)
• references/commands.md: 85 lines (full command map with all flags)
• references/targets.md: 53 lines (URL vs channel targeting)
• references/output.md: 39 lines (JSON output shapes)
• Total: ~293 lines across 4 files

Proposed state (after PR)

• SKILL.md: ~180 lines (everything inlined)
• No reference files
• Total: ~180 lines in 1 file

---

The Agent Skills Specification

Source: agentskills.io/specification (the official open standard, originally developed by Anthropic)

Directory structure

The spec defines skills as a directory with a required SKILL.md and explicitly supports optional directories:

skill-name/
├── SKILL.md          # Required
├── scripts/          # Optional: executable code
├── references/       # Optional: additional documentation
└── assets/           # Optional: static resources

Progressive disclosure (core design principle)

The spec defines a three-tier context loading model:

1. Metadata (~100 tokens): name and description loaded at startup for ALL skills
2. Instructions (< 5000 tokens recommended): Full SKILL.md body loaded when skill activates
3. Resources (as needed): Files in scripts/, references/, assets/ loaded only when required

"Keep your main SKILL.md under 500 lines. Move detailed reference material to separate files." -- agentskills.io/specification

The references/ directory

The spec explicitly describes references/ as an optional directory:

"Contains additional documentation that agents can read when needed:

• REFERENCE.md - Detailed technical reference
• FORMS.md - Form templates or structured data formats
• Domain-specific files (finance.md, legal.md, etc.)

Keep individual reference files focused. Agents load these on demand, so smaller files mean less use of context."

File references

"Keep file references one level deep from SKILL.md. Avoid deeply nested reference chains."

This means SKILL.md -> references/commands.md is fine. SKILL.md -> references/advanced.md -> references/details.md is not.

---

Anthropic's Official Best Practices

Source: platform.claude.com - Skill authoring best practices

Conciseness is key

"The context window is a public good. Your Skill shares the context window with everything else Claude needs to know."

"Default assumption: Claude is already very smart. Only add context Claude doesn't already have."

Progressive disclosure patterns (directly relevant)

Anthropic explicitly recommends Pattern 1: High-level guide with references:

# PDF Processing

## Quick start
[essential content here]

## Advanced features
**Form filling**: See [FORMS.md](FORMS.md) for complete guide
**API reference**: See [REFERENCE.md](REFERENCE.md) for all methods

"Claude loads FORMS.md, REFERENCE.md, or EXAMPLES.md only when needed."

SKILL.md size limit

"Keep SKILL.md body under 500 lines for optimal performance. If your content exceeds this, split it into separate files."

On install instructions

"Don't assume packages are available... Explicit about dependencies."

The best practices include an explicit anti-pattern:

Bad: "Use the pdf library to process the file."

Good: "Install required package: pip install pypdf"

On reference files

"Structure longer reference files with table of contents. For reference files longer than 100 lines, include a table of contents at the top."

This confirms reference files are expected and supported -- they just need good structure.

Checklist (from official docs)

• SKILL.md body is under 500 lines
• Additional details are in separate files (if needed)
• File references are one level deep
• Progressive disclosure used appropriately

---

Ecosystem Survey: CLI-Wrapping Skills

Skills that wrap CLI tools (detailed analysis)

1. runpodctl (RunPod)

• Repo: runpod/skills/runpodctl
• Structure: Single SKILL.md (~80 lines)
• Install instructions: No (assumes CLI already installed)
• Command reference: Concise commented one-liners grouped by category
• Why single-file works: runpodctl has ~25 commands with simple flags. The entire reference fits in ~60 lines.

2. agent-browser (Vercel/Stably)

• Location: ~/.agents/skills/agent-browser/SKILL.md
• Structure: Multi-file (SKILL.md + 6 reference docs + 3 templates)
• SKILL.md: 218 lines (core workflow + essential commands)
• References: commands.md, snapshot-refs.md, session-management.md, authentication.md, video-recording.md, proxy-support.md
• Install instructions: Platform-specific (Appium for iOS)
• Why multi-file works: agent-browser has deep features (sessions, state persistence, iOS, proxies, video recording) that would bloat SKILL.md past 500 lines

3. agent-slack (current, before PR)

• Location: ~/.agents/skills/agent-slack/SKILL.md
• Structure: Multi-file (SKILL.md + 3 reference docs)
• SKILL.md: 116 lines (workflow-focused)
• References: commands.md (85 lines), targets.md (53 lines), output.md (39 lines)
• Install instructions: No (assumes pre-installed)

4. find-skills (Vercel)

• Repo: vercel-labs/skills/find-skills
• Structure: Single SKILL.md (134 lines)
• Install instructions: Describes npx skills add for installing other skills
• Command reference: 4 key commands (find, add, check, update)

5. mcp-builder (Anthropic)

• Repo: anthropics/skills/mcp-builder
• Structure: Multi-file (SKILL.md + reference/ dir + scripts/ dir)
• References: reference/mcp_best_practices.md, reference/node_mcp_server.md, reference/python_mcp_server.md, reference/evaluation.md
• Why multi-file: Complex 4-phase workflow with language-specific docs

Anthropic's official skills (16 total)

From github.com/anthropics/skills:

Skill	Type	Structure
algorithmic-art	Knowledge	Single file
brand-guidelines	Knowledge	Single file
canvas-design	Knowledge	Single file
doc-coauthoring	Workflow	Multi-file
docx	CLI/Tool	Multi-file (scripts + references)
frontend-design	Knowledge	Single file
internal-comms	Knowledge	Single file
mcp-builder	Workflow	Multi-file (reference/ + scripts/)
pdf	CLI/Tool	Multi-file (scripts + references)
pptx	CLI/Tool	Multi-file
skill-creator	Meta	Single file
slack-gif-creator	Workflow	Single file
theme-factory	Knowledge	Single file
web-artifacts-builder	Workflow	Single file
webapp-testing	Workflow	Single file
xlsx	CLI/Tool	Multi-file

Pattern: Knowledge/guideline skills tend to be single-file. Tool-wrapping and complex workflow skills are multi-file.

Agent tools on skills.sh (200+ skills)

skills.sh -- "The Open Agent Skills Ecosystem" by Vercel -- lists 200+ skills. The platform is compatible with 27+ agent products including Claude Code, Cursor, Windsurf, VS Code, GitHub Copilot, Goose, Gemini CLI, OpenAI Codex, Roo Code, Amp, and more.

Compatible agents from the skills.sh homepage: Claude Code, Cursor, Windsurf, VS Code, GitHub Copilot, Goose, Gemini CLI, OpenAI Codex, Roo Code, Amp, Factory, Firebender, Letta, OpenCode, Mux, Piebald, Autohand, TRAE, Spring AI, Qodo, Agentman, Command Code, VT Code, Ona, Databricks, Mistral Vibe, pi

---

Comparative Analysis: Single-File vs Multi-File

When single-file is appropriate

• Simple CLI tools with < 25 commands and minimal flags (e.g., runpodctl)
• Knowledge skills that are purely instructional (e.g., frontend-design)
• Total content fits under 500 lines (the spec's recommended limit)
• No domain-specific reference material that would be loaded conditionally

When multi-file is appropriate

• Complex CLI tools with many commands, modes, and flags
• Content exceeds 500 lines when fully detailed
• Different reference domains that should be loaded independently (e.g., targets vs output shapes vs command flags)
• Progressive disclosure provides real savings -- agent doesn't need ALL reference material for most tasks

The agent-slack case

agent-slack has:

• 8 command groups (auth, message get/list/send/edit/delete, react, search, channel, canvas, user)
• Complex targeting rules (URL vs channel vs channel ID, workspace disambiguation)
• Detailed output shapes (message, thread, search, channel admin)
• Per-command flags (many commands have 5-8 flags each)
• Platform-specific auth flows

Full detail would be 300+ lines. The current 293 lines across 4 files is well-organized. The proposed single-file at ~180 lines achieves brevity by dropping detail, not by being more efficient.

---

Verdict on PR #24 Changes

1. Added install instructions -- ACCEPT

This is correct per Anthropic's best practices:

"Don't assume packages are available... Explicit about dependencies."

agent-slack is a CLI binary that must be installed. The skill should tell agents how to guide users through installation. The curl script + npm i -g approach is appropriate.

Recommendation: Include install instructions, but keep them concise (5-10 lines max).

2. One big command reference block -- REJECT (partially)

The PR cites runpodctl as precedent, but the comparison is flawed:

	runpodctl	agent-slack
Commands	~25, simple flags	15+, complex flags per command
Targeting modes	None	URL vs channel vs ID (complex rules)
Output shapes	Simple	Multiple shapes per command group
Auth flows	API key only	5+ methods, platform-specific
Total reference	~60 lines	~177 lines

runpodctl's entire reference fits in ~60 lines. agent-slack's doesn't.

The spec is clear:

"Keep your main SKILL.md under 500 lines. Move detailed reference material to separate files."

Recommendation: Keep a "quick reference" in SKILL.md (like the current approach) with commented one-liners for common operations. Keep detailed flag documentation in references/commands.md.

3. Merged reference docs / removed reference files -- REJECT

The spec explicitly supports references/:

"Contains additional documentation that agents can read when needed... Agents load these on demand, so smaller files mean less use of context."

The current structure provides real progressive disclosure benefits:

• When an agent needs to send a message, it only needs the SKILL.md workflow section
• When it needs to understand URL vs channel targeting, it loads targets.md
• When it needs output shape details, it loads output.md
• It rarely needs ALL three at once

Inlining everything means the agent always loads everything, wasting context window budget.

Recommendation: Keep the reference files. Improve them if needed (add TOCs per the best practices), but don't delete them.

4. Split auth by platform -- ACCEPT

Clear platform-specific sections (macOS auto-detect vs Linux/Windows manual) are better than the current "fallback" wording.

5. Added parse-curl guide -- ACCEPT (with caveats)

Useful for Linux/Windows users, but consider putting detailed DevTools instructions in a reference file rather than the main SKILL.md, since most macOS users won't need it.

---

Recommended Structure

Based on the spec and best practices, the ideal agent-slack skill structure would be:

agent-slack/
├── SKILL.md              # ~150-200 lines: install, auth, workflows, quick reference
└── references/
    ├── commands.md        # Full command map with all flags
    ├── targets.md         # URL vs channel targeting rules
    └── output.md          # JSON output shapes + download paths

What to change from current state

1. Add install instructions to SKILL.md (from PR #24)
2. Add platform-specific auth sections (from PR #24)
3. Keep reference files (reject PR #24's deletion)
4. Add TOC to each reference file (per best practices)
5. Add a concise "quick command reference" to SKILL.md (commented one-liners for the most common 10 commands)
6. Keep the "References" links section at the bottom of SKILL.md

---

References

Authoritative / Specification

1. Agent Skills Specification (the canonical format spec) https://agentskills.io/specification

2. What Are Skills? (overview from agentskills.io) https://agentskills.io/what-are-skills

3. Anthropic - Skill Authoring Best Practices (official best practices from Anthropic) https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices

4. Anthropic Skills Repository (16 official example skills) https://github.com/anthropics/skills

5. Agent Skills Standard (open standard GitHub repo) https://github.com/agentskills/agentskills

Ecosystem / Examples

6. skills.sh -- The Open Agent Skills Ecosystem (200+ skills directory) https://skills.sh

7. RunPod Skills (CLI-wrapping skill example) https://github.com/runpod/skills/blob/main/runpodctl/SKILL.md

8. Anthropic mcp-builder (multi-file skill with references/) https://github.com/anthropics/skills/blob/main/skills/mcp-builder/SKILL.md

9. Anthropic frontend-design (single-file knowledge skill) https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md

PR Under Review

10. PR #24 -- "fix[skill]: consolidate into single self-contained SKILL.md" stablyai/agent-slack#24

skill-format-from-codex.md

Skill Format Research Report (PR #24)

Date: February 20, 2026

Executive Summary

PR #24 is directionally right on adding install instructions, but materially risky on consolidating everything into one large SKILL.md and deleting references/ docs.

The strongest authority in this ecosystem (Agent Skills spec + Anthropic skill best practices) explicitly recommends progressive disclosure: keep SKILL.md concise and move detailed reference content into references/ files loaded on demand. A single large command block can work for small CLIs, but for a growing CLI like agent-slack, it increases token cost, drift risk, and maintenance burden.

Given current agent-slack scope and ongoing command churn, the best design is:

1. Keep install/setup in SKILL.md.
2. Keep a short “common commands” section in SKILL.md.
3. Keep full flags/output/target edge cases in references/.
4. Auto-generate command reference from CLI help (or source metadata) to avoid drift.

Direct Answer on PR #24

PR under review: stablyai/agent-slack#24

1) Added install instructions

Verdict: Reasonable and correct.

Why:

• Skills that wrap external CLIs need first-time setup clarity; otherwise agents cannot reliably complete tasks for new users.
• Anthropic best practices emphasize practical usability and concise, actionable instructions.
• In sampled CLI-focused skills, install/prereq guidance appears frequently (e.g., browser-use, runpodctl, Azure skills).

Evidence:

• Anthropic best practices: “Concise is key” but practical, tested instructions are expected.
• browser-use skill includes prerequisite/doctor guidance.
• runpodctl skill includes quick-start command flow.

2) One big command reference block

Verdict: Conditionally acceptable, but not ideal here.

When it works:

• Smaller, stable CLIs with limited command surface.
• Skills where a fast copy/paste command catalog is the primary UX.

Why it is risky for agent-slack now:

• Agent Skills spec says full SKILL.md is loaded at activation; large docs compete with active conversation context.
• Spec and best practices recommend splitting longer content and keeping SKILL.md concise.
• agent-slack command set is broad and still evolving; large inline command maps go stale quickly.

Observed ecosystem pattern:

• Some CLI skills do use a large in-file command block (runpodctl, browser-use).
• Other mature collections heavily use references/ (e.g., agent-browser, Microsoft Azure skills) for maintainability and on-demand loading.

3) Merged reference docs / removed reference files

Verdict: Not generally advisable for this repo.

Authority conflict:

• Agent Skills spec explicitly recommends progressive disclosure and references/ for long/detailed material.
• It recommends focused reference files loaded on demand and suggests keeping main SKILL.md under 500 lines.

Repo-specific concern:

• The PR’s merged single-file approach already appears susceptible to drift. Compared with current repo content, the PR version shown in #24 omits newer/important command areas present in current docs/codebase (e.g., message edit/delete, channel operations, reaction filters with --with-reaction / --without-reaction).
• That is exactly the failure mode progressive disclosure + generated reference docs help prevent.

Authority Synthesis

What the spec says (strongest authority)

From Agent Skills specification:

• SKILL.md is loaded at skill activation.
• “Consider splitting longer SKILL.md content into referenced files.”
• references/ is a first-class optional directory for additional docs.
• Progressive disclosure model: metadata at startup, SKILL.md on activation, resources on demand.
• Recommendation: keep SKILL.md under ~500 lines.

Implication:

• Keep activation-critical guidance in SKILL.md.
• Move exhaustive command matrices and flag edge cases to references/.

What Claude’s skill best-practices say

• Prioritize concision; every loaded token competes with user context.
• Use progressive disclosure patterns and split content as complexity grows.
• Keep SKILL body bounded; use references for deeper material.

Implication:

• A giant all-in-one command reference in SKILL.md is usually a scaling anti-pattern.

General docs authority (cross-ecosystem)

Diátaxis reference guidance:

• Reference docs should be consistent, authoritative, and structured around machinery.
• How-to content should stay goal-oriented and link to reference rather than embedding everything.

Implication:

• Keep top-level skill as “how-to / workflow-oriented”; keep full command reference in dedicated reference docs.

Empirical Comparison: CLI-Packaged Skills

Sampled CLI-focused skills:

• runpod/skills/runpodctl/SKILL.md
• browser-use/browser-use/skills/browser-use/SKILL.md
• vercel-labs/agent-browser/skills/agent-browser/SKILL.md
• microsoft/github-copilot-for-azure/plugin/skills/*/SKILL.md

Patterns observed:

• Install/prereq guidance: common in CLI-wrapping skills.
• Large command sections: common in small-to-mid skills.
• References split: more common in larger/enterprise or high-churn skill sets.
• Hybrid pattern (best scaling): short operational core in SKILL.md + deep references.

Repository-level structure signals (sample):

• runpod/skills: minimal, single-file style.
• browser-use/browser-use: single-file CLI-heavy skills.
• vercel-labs/agent-browser: SKILL.md + references/ + templates.
• microsoft/github-copilot-for-azure: extensive references/ per skill.

25-Tool Landscape (Skills-Compatible Agent/CLI Ecosystem)

Method:

• Combined “supported agents” from vercel-labs/skills CLI and “adoption”/logos from Agent Skills docs.
• Popularity is inferred from ecosystem prominence and inclusion in these adoption/support lists (not a strict global ranking metric).

What these 25 tools have down

1. Claude Code

• Clear skill directory conventions; strong docs and frontmatter semantics.
• Good progressive-disclosure guidance.

2. OpenAI Codex

• Participates in shared SKILL.md ecosystem and install adapters.
• Benefits from cross-tool portability.

3. Cursor

• Supports shared skill installation path conventions.
• Works well with reusable team skill packs.

4. Gemini CLI

• Skills-compatible pathing and ecosystem support.
• Strong interoperability signal from Agent Skills adoption.

5. GitHub Copilot

• Skills install support via adapters; enterprise skill ecosystems emerging.

6. OpenCode

• Native inclusion in shared skill install ecosystems.

7. Goose

• Supports skills and benefits from reusable task packs.

8. Roo Code

• Skills-compatible and visible in adoption showcases.

9. Windsurf

• Skills-compatible installation paths and adapters.

10. Amp

• Skills support through shared ecosystem tooling.

11. Cline

• Adapter-backed skills installation support.

12. VS Code (agent workflows)

• Skills appears in adoption ecosystem; useful for workspace-level reuse.

13. Trae

• Skills-compatible and listed in adoption/support matrices.

14. Kiro CLI

• Skills-compatible with explicit extra integration notes in skills tooling.

15. Kilo Code

• Skills-compatible via adapter paths.

16. Mistral Vibe

• Listed in skills adoption ecosystem; supports packageable capability docs.

17. Command Code

• Included in adoption landscape.

18. Qoder

• Adapter-backed skill paths.

19. Qwen Code

• Adapter-backed skill paths.

20. Continue

• Skills-compatible via installer adapters.

21. Augment

• Skills-compatible path conventions.

22. OpenHands

• Skills-compatible path conventions.

23. Replit (agent mode)

• Supported via universal .agents/skills path mode.

24. Antigravity

• Skills-compatible installation path conventions.

25. CodeBuddy

• Included in current skills adapter matrix.

Cross-tool common success pattern:

• Minimal required frontmatter (name, description) + concise activation instructions.
• Optional scripts/, references/, and assets/ for progressive disclosure.
• Shared installer (npx skills) lowers friction and standardizes layout.

Recommendation for agent-slack

Recommended format (balanced)

Use a hybrid doc architecture:

• SKILL.md: install/setup, auth flow, 5-10 common workflows, guardrails.
• references/commands.md: exhaustive command/flags matrix.
• references/targets.md: URL/channel/workspace resolution and ambiguity rules.
• references/output.md: output schemas, truncation/defaults, download paths.

Why this is best

• Aligns with Agent Skills spec and Anthropic best practices.
• Preserves first-run usability (install guidance).
• Controls token cost at activation.
• Reduces drift and improves maintainability.

Practical implementation guardrails

• Keep SKILL.md under ~500 lines.
• Add CI check that compares documented commands vs CLI help/source registrations.
• Consider generating references/commands.md from commander definitions/help output.
• Keep README.md and skill docs synchronized via one source-of-truth command metadata.

Specific Conclusion on PR #24

• Install instructions: keep.
• Single giant command block: reduce to high-frequency commands only.
• Deleting references: reverse; references should stay (or be reintroduced) for scale, token efficiency, and correctness.

In short: PR #24 has a good onboarding fix but a structurally weak documentation consolidation for a growing CLI.

Sources

1. Agent Skills Specification: https://agentskills.io/specification
2. Agent Skills “What are skills?”: https://agentskills.io/what-are-skills
3. Agent Skills docs repo (specification.mdx): https://github.com/agentskills/agentskills/blob/main/docs/specification.mdx
4. Claude Code skills docs: https://code.claude.com/docs/en/skills
5. Anthropic skill best practices: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
6. Diátaxis reference guidance: https://diataxis.fr/reference/
7. Diátaxis how-to guidance: https://diataxis.fr/how-to-guides/
8. skills.sh directory + leaderboard: https://skills.sh
9. vercel-labs/skills supported agents matrix: https://github.com/vercel-labs/skills
10. vercel-labs/agent-skills format notes: https://github.com/vercel-labs/agent-skills
11. runpod/skills runpodctl skill: https://github.com/runpod/skills/blob/main/runpodctl/SKILL.md
12. vercel-labs/agent-browser skill: https://github.com/vercel-labs/agent-browser/blob/main/skills/agent-browser/SKILL.md
13. browser-use/browser-use skill: https://github.com/browser-use/browser-use/blob/main/skills/browser-use/SKILL.md
14. Microsoft Azure skills repo: https://github.com/microsoft/github-copilot-for-azure
15. PR under review: stablyai/agent-slack#24

skill-format-gemini.md

Agent Skill Architecture: Analysis of SKILL.md Consolidation

Executive Summary

This document evaluates the architectural shift proposed in stablyai/agent-slack PR #24, which consolidates multiple reference files (commands.md, targets.md, output.md) into a single, monolithic SKILL.md file, and introduces CLI installation instructions directly into the agent context.

The analysis compares these changes against the official Skill Creator guidelines and empirical data gathered from popular agent CLI skills (such as those following the Vercel skills.sh standard).

1. Analysis of Proposed Changes (PR #24)

Core Modifications

1. Added Installation Instructions: Included a curl script and npm i -g command directly in the SKILL.md to allow agents to guide users through installing the underlying CLI tool.
2. Monolithic Command Reference: Merged three separate reference files into a single, consolidated SKILL.md.
3. Removed Reference Files: Deleted the external reference docs (commands.md, targets.md, output.md) in favor of having all context centralized.

Author's Rationale

The primary motivation was to fix a broken first-time user experience. By consolidating the files, agents load one file and have everything they need without requiring cross-referencing or secondary file reads. The author explicitly cited the runpodctl skill as inspiration for the "one big command reference block" pattern.

2. Evaluation Against Official Guidelines (The Source of Authority)

The absolute authority on this topic is the Skill Creator Guide, which defines the standards for building agent skills for Gemini CLI, Copilot, and Claude via the Vercel skills.sh open standard. According to these guidelines, the changes in PR #24 conflict with core design principles:

Adding CLI Install Instructions: Non-Compliant

The guidelines explicitly forbid including installation material in the agent's core prompt:

"What to Not Include in a Skill: INSTALLATION_GUIDE.md. The skill should only contain the information needed for an AI agent to do the job at hand. It should not contain auxiliary context about the process that went into creating it, setup and testing procedures, user-facing documentation, etc."

The philosophy dictates that an agent assumes the environment is already prepared. Including CLI installation scripts wastes valuable context window tokens on one-time setup tasks that belong in a human-readable README.md.

Merging Reference Docs into a Monolithic File: Non-Compliant

The guidelines strictly mandate a Progressive Disclosure Design Principle:

"Keep SKILL.md body to the essentials and under 500 lines to minimize context bloat... Avoid duplication: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill."

The architectural ideal is that SKILL.md serves as a lean routing document. If a user asks a specific question, the agent reads SKILL.md and then dynamically decides to load references/commands.md or references/targets.md as needed. Merging them forces the agent to load the entire payload into context on every trigger.

3. Empirical Analysis of Ecosystem Practices

While the official guidelines advocate for Progressive Disclosure, an analysis of 46 popular agent CLI skills (including those found via skills.sh and local installations) reveals a stark contrast between theory and practice:

The Monolithic SKILL.md vs. References Directory

• Practice heavily favors the Monolithic approach. Out of 46 skills analyzed, 36 skills (78%) do not use a references/ directory. They consolidate all information into a single SKILL.md file.
• Only 10 skills (e.g., playwright-cli, agent-browser, file-tasks) utilize the progressive disclosure pattern with separate reference files.
• Example: The runpodctl skill (cited in PR #24) is a single, monolithic 400+ line markdown file containing every command, parameter, and output shape.

Why the deviation? Agent reasoning engines are highly capable, but file-system navigation via tool calls can introduce latency and brittleness. When an agent has to read SKILL.md, realize it needs more info, call a read_file tool on a reference file, and wait for the response, it introduces points of failure. The monolithic file guarantees the agent has 100% of the context instantly.

Presence of Installation Instructions

• Out of 46 skills, 16 included some form of "install" instructions explicitly within the SKILL.md.
• However, most of these instructions are for project-level dependencies (e.g., npm install @playwright/test), not global host-machine installations (like curl ... | bash).
• Including global host-machine installation instructions is extremely rare and generally frowned upon because agents running in sandboxed or read-only environments will fail if they attempt to execute them autonomously.

4. Conclusion and Recommendations

Verdict: Pragmatically Reasonable, but Architecturally "Incorrect."

1. Merging the Reference Files: While violating the official "Progressive Disclosure" rule, merging the files is practically reasonable. Nearly 80% of the ecosystem ignores this rule in favor of monolithic SKILL.md files (provided they stay under ~500 lines). It drastically improves agent reliability by removing the need for sequential file-reading tool calls.
2. Adding CLI Installation Instructions: This remains an anti-pattern. While it helps "first-time agent use," it bloats the prompt with one-time setup instructions. The ecosystem specifically separates the installation of the skill/CLI from the execution of the skill.

Final Recommendation: Retain the merged monolithic reference structure for improved agent reliability, as this aligns with the dominant ecosystem practice. However, consider moving the CLI installation guide out of the SKILL.md and into a standard human-readable README.md, adhering to the principle that SKILL.md should purely be an operational manual for the agent.

5. References

1. Skill Creator Guide: Official guidelines defining SKILL.md structure, the Progressive Disclosure Design Principle, and exclusion criteria (e.g., installation guides).
2. GitHub PR #24: stablyai/agent-slack #24: fix[skill]: consolidate into single self-contained SKILL.md
3. Vercel skills.sh: Open standard documentation emphasizing the separation of agent skills from environment setup.
4. Local Agent Skill Ecosystem Analysis: Programmatic analysis of 46 installed agent skills (e.g., ~/.agents/skills/), evaluating line counts, references/ directories, and installation instructions.
5. Runpodctl Skill Source: runpod/skills/runpodctl/SKILL.md