Building Developer Platforms & Tooling

Platform engineering creates self-service capabilities that reduce cognitive load and accelerate delivery. This skill covers the full spectrum: from designing golden paths and service catalogs to building MCP servers and plugin systems, document generation, reproducible environments, and setup orchestration. Sourced from 107 assets across 13 repositories.

When Invoked Without Clear Intent

MANDATORY: You MUST call the AskUserQuestion tool — do NOT render these options as text:

AskUserQuestion( header: "Platform", question: "What platform engineering topic do you need help with?", options: [ { label: "Scaffolding & Templates", description: "Project scaffolding, golden paths, template libraries" }, { label: "MCP Server Dev", description: "Build Model Context Protocol servers for LLM-to-service integration" }, { label: "Plugin Systems", description: "Plugin architecture, lifecycle management, Claude Code plugins" }, { label: "Developer Experience", description: "DX assessment, internal tooling, CLI/SDK design" } ] )

If the user selects "Other", present: Document Generation (PDF/DOCX/PPTX/XLSX), Reproducible Environments (Nix/devenv), File Organization, Service Catalogs.

Core Capabilities

1. Service Catalog & Golden Paths

Design and implement service catalogs that encode organizational best practices into discoverable, self-service templates.

Key patterns from Provectus assets:

• Template libraries structured by domain (see proagent/core/templates/skill-template.md, proagent/core/templates/command-template.md)
• Reusable skill and command patterns (see skills/skill-creator/SKILL.md for the meta-skill pattern)
• Progressive disclosure: metadata for discovery, instructions for understanding, details for implementation

Golden path design principles:

• Encode best practices as defaults, not documentation
• Make the right thing the easy thing
• Support escape hatches for advanced users
• Version templates independently from consuming projects
• Include validation hooks to catch drift from the golden path

2. Project Scaffolding & Templates

Create scaffolding systems that generate production-ready project structures.

Template architecture:

• Prompt templates: reusable instruction patterns for common tasks
• Code templates: standard patterns for API endpoints, models, tests, migrations
• Workflow templates: stage-based sequences (plan, implement, validate, deploy)
• Review templates: checklists for consistent quality assessment

Language-specific scaffolding commands:

• Python projects: agents/plugins/python-development/commands/python-scaffold.md with packaging skill at agents/plugins/python-development/skills/python-packaging/SKILL.md
• TypeScript projects: agents/plugins/javascript-typescript/commands/typescript-scaffold.md

Scaffolding workflow:

1. Identify repetition across teams and projects
2. Extract invariants (structure, quality criteria, required sections)
3. Parameterize variables (names, configurations, domain-specific values)
4. Add guidance with examples of good fill-ins and common mistakes
5. Iterate based on usage feedback and adoption metrics

3. MCP Server Development

Build Model Context Protocol servers that enable LLM-to-service integration (see skills/mcp-builder/SKILL.md).

Recommended stack:

• TypeScript with MCP SDK for broad compatibility
• Streamable HTTP transport for remote servers, stdio for local
• Zod schemas for input validation, structured output schemas

Implementation phases:

1. Deep research: study the target API, plan tool coverage
2. Implementation: project structure, core infrastructure, tool registration
3. Review and test: code quality, MCP Inspector verification
4. Evaluation: create 10 complex, realistic test questions

Tool design principles:

• Balance comprehensive API coverage with workflow convenience tools
• Use consistent naming prefixes (e.g., github_create_issue, github_list_repos)
• Return focused, relevant data with pagination support
• Provide actionable error messages that guide toward solutions

4. Plugin System Architecture

Design and implement plugin systems for extensibility.

Plugin anatomy:

plugin-name/
  .claude-plugin/plugin.json   # Manifest: name, version, agents, skills, commands, hooks, mcp
  agents/*.md                   # Agent definitions with YAML frontmatter
  skills/*/SKILL.md             # Skill definitions with progressive disclosure
  commands/*.md                 # Slash commands with argument handling ($1, $ARGUMENTS)
  hooks/hooks.json              # Lifecycle event handlers (PreToolUse, PostToolUse, Stop)
  .mcp.json                     # MCP server configurations

Plugin lifecycle:

1. Discovery: scan directories for .claude-plugin/plugin.json manifests
2. Loading: parse manifest, resolve paths, load all resource types
3. Namespacing: all resources use plugin-name:resource-name format
4. Access: typed accessors for agents, skills, commands, hooks, MCP configs

5. Developer Experience (DX) Optimization

Evaluate and improve developer workflows, toolchains, and self-service capabilities.

DX assessment dimensions:

• Onboarding time: minutes from clone to first meaningful contribution
• Inner loop speed: edit-build-test-debug cycle time
• Cognitive load: number of tools, contexts, and decisions per task
• Self-service coverage: percentage of common tasks achievable without filing tickets
• Documentation quality: accuracy, discoverability, freshness

Improvement strategies:

• Automate repetitive setup with scripts (see root-setup/setup-agentic-coding.sh)
• Provide CLI wrappers for complex operations
• Create development containers with pre-configured environments
• Build integration connectors for Slack, GitHub, GitLab, Google Drive
• Implement maturity models to track DX improvements (see proagent/core/skills/tac/maturity-model.md)

6. Internal CLI & SDK Design

Build internal command-line tools and SDKs that wrap platform capabilities.

CLI design patterns:

• Rich formatting for terminal output
• Pydantic-based configuration with environment variable loading
• Command registries with argument substitution
• Plugin discovery and auto-loading

SDK design principles:

• Type-safe interfaces with comprehensive validation
• Progressive complexity: simple defaults, advanced overrides
• Consistent error handling with actionable messages
• Auto-discovery of extensions and plugins

7. Document Generation

Generate professional documents from templates and data using the awesome-claude-skills document generation patterns.

Supported formats:

• PDF: Reports, proposals, technical specifications (see awesome-claude-skills/document-skills/pdf/SKILL.md)
• DOCX: Word documents for RFCs, design docs, SOWs (see awesome-claude-skills/document-skills/docx/SKILL.md)
• PPTX: Presentations for architecture reviews, sprint demos, stakeholder updates (see awesome-claude-skills/document-skills/pptx/SKILL.md)
• XLSX: Spreadsheets for capacity planning, cost analysis, inventory tracking (see awesome-claude-skills/document-skills/xlsx/SKILL.md)

Usage patterns:

• Generate platform documentation artifacts from structured data
• Create template-driven reports for DX assessments and tooling audits
• Produce stakeholder-ready presentations from technical analysis

8. Reproducible Environments & Setup Orchestration

Build reproducible development environments and automate installation workflows.

Nix/devenv patterns (from ralph-orchestrator and gastown):

• Declarative environment definitions with Nix flakes
• Per-project development shells with all dependencies pinned
• Cross-platform reproducibility (macOS and Linux)

Setup orchestration (from awos src/core/setup-orchestrator.js):

• Multi-step installation workflows with dependency resolution
• Idempotent setup scripts that can be re-run safely
• Environment validation and health checks post-setup

Plugin management systems:

• casdk-harness src/harness/plugin_manager.py: Python-based plugin lifecycle (discovery, loading, initialization, teardown)
• gastown internal/cmd/plugin.go: Go-based plugin management CLI commands
• agents docs/plugins.md: Plugin system documentation and marketplace usage patterns

9. File Organization & README Generation

File organization (from awesome-claude-skills/file-organizer/SKILL.md):

• Automated project structure organization following convention-based layouts
• Cross-directory file sorting and categorization

README generation (from awesome-claude-code/scripts/readme/generate_readme.py):

• Multi-style README generation from project analysis
• Automated documentation extraction from code and config files

Workflow: Building a New Platform Component

1. Understand the need: interview stakeholders, gather concrete usage examples
2. Survey existing assets: search for similar patterns in the catalog (107 platform assets across 13 repos)
3. Design the component: choose the right abstraction (template, skill, command, MCP server, plugin)
4. Implement: follow the appropriate pattern from this skill
5. Validate: run template validation, DX feedback checks, and user testing
6. Ship and iterate: publish to the service catalog, track adoption, refine based on feedback

Composio App Automations

This plugin integrates with Composio-powered SaaS automation skills via the Rube MCP server. These skills connect to real external services for end-to-end workflow automation.

Available Automations

Skill	Service	Key Capabilities
slack-automation	Slack	Send messages, manage channels, create workflows, user management, file sharing
notion-automation	Notion	Create/update pages and databases, manage blocks, search content, template management
confluence-automation	Confluence	Create/update pages, manage spaces, search content, attach files, label management
google-drive-automation	Google Drive	Create/manage files and folders, sharing permissions, search, export/import formats

Usage Pattern

All Composio automations follow a three-step workflow:

1. Discover tools: Use RUBE_SEARCH_TOOLS with a use case description to find available tools and their schemas
2. Connect service: Use RUBE_MANAGE_CONNECTIONS to activate the toolkit connection (handles OAuth automatically)
3. Execute actions: Use RUBE_MULTI_EXECUTE_TOOL with the discovered tool slug and schema-compliant arguments

Configuration

Add the Rube MCP server to your .mcp.json:

"rube": {
  "url": "https://rube.app/mcp"
}

Visual Diagramming with Excalidraw

Use the Excalidraw MCP server to generate interactive diagrams directly in the conversation. Describe what you need in natural language and Excalidraw renders it as an interactive canvas with hand-drawn style.

When to Use

• Platform topology and service catalog maps
• Golden path and developer workflow diagrams
• Internal tooling architecture and scaffolding template relationships
• Developer portal and DX optimization flows

Workflow

1. Describe the diagram you need — be specific about components, relationships, and layout
2. Review the rendered interactive diagram in the chat
3. Request refinements by describing what to change (add/remove/rearrange elements)
4. Use fullscreen mode for detailed editing when needed

Tips for Effective Diagrams

• Name specific components and their connections (e.g., "API Gateway connects to Auth Service and User Service")
• Specify layout direction when it matters (e.g., "left-to-right flow" or "top-down hierarchy")
• Request specific diagram types (architecture diagram, flowchart, sequence diagram, ER diagram)
• Iterate — start with the overall structure, then refine details