Create installable agent skill for gh-devlake (Playwright CLI pattern)

[ewega]

Problem

Coding agents (Copilot CLI agent, Claude, etc.) have no structured way to discover and use gh-devlake commands. Users must manually explain the CLI's capabilities in every agent session. The Playwright CLI solved this with an installable skill definition ΓÇö a structured document that teaches agents the CLI's command surface, typical workflows, and expected output formats.

Proposed Solution

Ship a skills/gh-devlake/SKILL.md (with optional references/ docs) and an install --skills command that copies the skill into the agent's skill directory.

Architecture (following Playwright CLI pattern)

skills/
  gh-devlake/
    SKILL.md              # Top-level command reference + quick start
    references/
      deployment.md       # deploy local, deploy azure, cleanup
      configuration.md    # connections, scopes, projects, blueprints
      querying.md         # query commands (from #61), status
      troubleshooting.md  # diagnose, common errors

SKILL.md structure

Following microsoft/playwright-cli/skills/playwright-cli/SKILL.md:

---
name: gh-devlake
description: Deploy, configure, and query Apache DevLake from the terminal. Manages GitHub, GitLab, and Copilot data sources with DORA metrics.
---

# DevLake Management with gh-devlake

## Quick start
gh devlake deploy local
gh devlake configure full
gh devlake status --json

## Commands

### Deployment
gh devlake deploy local         # Docker Compose on this machine
gh devlake deploy azure         # Azure Container Apps
gh devlake cleanup              # tear down resources

### Configuration
gh devlake configure connection list --json
gh devlake configure connection add --plugin github --token $TOKEN --org my-org
gh devlake configure scope add --plugin github --connection-id 1 --repos org/repo1
gh devlake configure project add --project-name my-team

### Operations
gh devlake status --json        # deployment health + connections
gh devlake query dora --project my-team --json
gh devlake insights "question"  # AI-powered Q&A

## Output modes
(document --json flag from #60)

## Specific tasks
(link to reference docs)

Install command

gh devlake install --skills

Implementation:

• Detects agent type from environment (check for .copilot/, .claude/, .github/copilot-instructions.md)
• Copies skills/gh-devlake/ into the appropriate skill directory
• For Copilot: .github/skills/gh-devlake/ or .copilot/skills/gh-devlake/
• For Claude: .claude/skills/gh-devlake/
• Prints confirmation with path

Reference implementation: microsoft/playwright-cli install --skills ΓÇö installs skill files that agents auto-discover.

Skills-less operation (fallback)

Agents can also bootstrap from --help:

gh devlake --help
gh devlake configure --help
gh devlake query --help

This is the Playwright CLI's "skills-less operation" pattern.

Update script

Following microsoft/playwright-cli/scripts/update.js, create a script that regenerates the SKILL.md from the current CLI's --help output and registered commands. This keeps the skill in sync with the implementation.

Acceptance Criteria

• skills/gh-devlake/SKILL.md exists with command reference, quick start, and examples
• skills/gh-devlake/references/ has at least deployment.md, configuration.md
• gh devlake install --skills copies the skill into the agent's directory
• Skill content covers deployment, configuration, querying, and operations
• --help output is sufficient for skills-less operation
• go build ./... and go test ./... pass
• README updated with skill installation instructions

Target Version

v0.4.3 ΓÇö Agent-friendly CLI foundation within the active v0.4.x line.

Dependencies

• Add --json output flag to read commands #60 ΓÇö --json output flag (skill docs reference JSON output mode)

References

• Playwright CLI skill architecture: microsoft/playwright-cli/skills/playwright-cli/SKILL.md ΓÇö the skill file format, command reference structure, and examples section
• Playwright CLI install --skills: README.md#installing-skills ΓÇö how agents discover and consume the skill
• Playwright CLI skills-less operation: README.md#skills-less-operation ΓÇö fallback when skills aren't installed
• Playwright CLI update script: scripts/update.js ΓÇö keeps skill content in sync with CLI changes
• Playwright CLI session management: skills/playwright-cli/references/session-management.md ΓÇö pattern for reference docs alongside the main SKILL.md
• gh-devlake AGENTS.md ΓÇö existing architecture documentation to draw from for skill content
• .github/skills/ ΓÇö existing skill definitions in the repo (cli-architecture, plugin-registry, etc.)