New: 97,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Update Platform Docs

by openshift-eng in openshift-eng/ai-helpers

Update existing platform documentation with automatic gap detection in openshift/enhancements

Apache-2.0Auto-check passedAgent Workflows

Install Update Platform Docs

skills CLI
$ npx skills add openshift-eng/ai-helpers --skill update-platform-docs -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install openshift-eng/ai-helpers update-platform-docs --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/openshift-eng/ai-helpers.git skills-src && mkdir -p .claude/skills && cp -r skills-src/plugins/agentic-docs/skills/update-platform-docs .claude/skills/update-platform-docs && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
update-platform-docs
GitHub stars
120
Token cost
~2.9k tokens
SKILL.md length
1,050 words
Files
8 (incl. scripts)
Skills in repo
118
Repo updated
First seen
Licence
Apache-2.0

At a glance

Update existing platform documentation with automatic gap detection in openshift/enhancements

  • Works in 4 steps: Discovery & Gap Detection → Perform Updates → Validation & Verification → …
  • Agent Workflows work in your project
  • SKILL.md covers Execution Workflow, Update Scenarios, File Naming Conventions and Update Guidelines, plus 7 more sections
  • Runs Shell scripts from its folder

What it does

Update Platform Docs is an agent skill from openshift-eng/ai-helpers. Update existing platform documentation with automatic gap detection in openshift/enhancements

Its SKILL.md is about 2.9k tokens, which your agent loads only when the skill is triggered. The skill folder holds 9 other files, including scripts (for example `scripts/discover.sh`, `scripts/gap-detection.sh` and `scripts/validate.sh`).

It sits in Agent Workflows. The repository describes itself as: Developer productivity tools for Claude Code & other AI assistants. The licence is Apache-2.0.

When your agent uses it

  • Agent Workflows work in your project

Example prompts

  • “/update-platform-docs”

Requirements

  • A Bash shell

Workflow steps

4 steps, taken from the step headings in SKILL.md.

  1. Discovery & Gap Detection
  2. Perform Updates
  3. Validation & Verification
  4. Report

What it can do on your machine

Read from SKILL.md and the folder at commit a627176. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Ships 3 files in scripts/ (Shell), which the agent can run.

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Update Platform Docs loads about 2.9k tokens when it runs. Until then it costs about 29 tokens; SKILL.md has 1,050 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~29
When it runs · the whole SKILL.md, loaded when a task matches
~2.9k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from openshift-eng/ai-helpers at commit a627176, republished under its Apache-2.0 licence (© openshift-eng). 1,050 words, ~2,856 tokens.

Download SKILL.mdSave it as .claude/skills/update-platform-docs/SKILL.md (or your agent's skills folder). This skill also uses 7 other files; get the full folder from GitHub.
name
update-platform-docs
description
Update existing platform documentation with automatic gap detection in openshift/enhancements

Platform Documentation Updater

Incrementally update existing AI-optimized platform documentation in openshift/enhancements/ai-docs/ without regenerating everything.

Features:

  • Automatic gap detection - Scans ai-docs/ and reports missing files
  • Targeted updates - Add specific content without full regeneration
  • Smart navigation - Auto-updates index files and AGENTS.md
  • Validation - Ensures quality and conventions

Use when:

  • Discovering what's missing from documentation
  • Adding new content to existing documentation
  • Adding new sections (e.g., workflows/exec-plans/)
  • Updating AGENTS.md with new links
  • Adding new domain concepts, patterns, or ADRs
  • Fixing or enhancing existing files

Don't use when:

  • You want to completely regenerate all docs from scratch

Execution Workflow

Phase 1: Discovery & Gap Detection
  • Resolve this skill directory from the location of the loaded SKILL.md. Resolve all scripts/ and templates/ paths relative to it. Do not search a plugin cache or assume the repository is the current directory.
  • Preflight every script and template required by the selected update before changing the repository. Stop and identify any missing resource.
  • Determine repo path: REPO_PATH="${provided_path:-$PWD}"
  • Run the resolved scripts/discover.sh with "$REPO_PATH"
  • Verify ai-docs/ exists (ai-docs/ should already exist in openshift/enhancements)
  • Run the resolved scripts/gap-detection.sh with "$REPO_PATH"
  • Show gap detection results to user
  • Ask user: Fill detected gaps OR specify custom addition?
Phase 2: Perform Updates

Based on user request, perform ONE OR MORE of:

Add New Platform Pattern
  • Create new file in platform/operator-patterns/
  • Update platform/operator-patterns/index.md
  • Update AGENTS.md navigation if needed
  • Use templates/operator-pattern-template.md for structure
Add New Domain Concept
  • Create new file in domain/kubernetes/ or domain/openshift/
  • Update corresponding domain/*/index.md
  • Update AGENTS.md navigation if needed
  • Use templates/domain-concept-template.md for structure
Add New Practice
  • Create new file in practices/*/
  • Update corresponding practices/*/index.md
  • Update AGENTS.md navigation if needed
  • Use templates/practice-template.md for structure
Add New ADR
  • Create new file in decisions/adr-NNNN-*.md
  • Update decisions/index.md
  • Update AGENTS.md navigation if needed
  • Use templates/adr-template.md for structure
Add New Workflow Section
  • Create new directory in workflows/ (e.g., exec-plans/)
  • Create files in new section
  • Update workflows/index.md
  • Update AGENTS.md navigation if needed
Update AGENTS.md
  • Read current AGENTS.md
  • Add new navigation links
  • Verify line count stays 100-200 lines
  • Maintain compressed table format
Update Existing Files
  • Read current file
  • Make targeted updates (add section, update content)
  • Preserve existing structure
  • Maintain file length targets
Phase 3: Validation & Verification
  • Run the resolved scripts/validate.sh with "$REPO_PATH"
  • Verify new files follow conventions, AGENTS.md 100-200 lines, internal links work
  • Anti-hallucination: Pattern claims verified in sample repos, API fields link to github.com/openshift/api or k8s/apimachinery, cross-check terminology with openshift-docs
  • All technical claims have references (type definitions, implementations, or enhancements)
Phase 4: Report
  • List files created
  • List files updated
  • Show validation status
  • Suggest git commit command

Update Scenarios

Scenario 1: Add New Operator Pattern

User request: "Add RBAC patterns to operator patterns"

Actions:

  1. Create platform/operator-patterns/rbac.md using pattern template
  2. Add entry to platform/operator-patterns/index.md
  3. Add link to AGENTS.md under "Standard Operator Patterns"
  4. Validate
Scenario 2: Add New Workflow Section

User request: "Add exec-plans guidance to workflows"

Actions:

  1. Create workflows/exec-plans/ directory
  2. Create workflows/exec-plans/README.md from template
  3. Create workflows/exec-plans/template.md from template
  4. Update workflows/index.md with new section
  5. Add link to AGENTS.md under "Workflows"
  6. Validate
Scenario 3: Update AGENTS.md

User request: "Add link to new ADR in AGENTS.md"

Actions:

  1. Read current AGENTS.md
  2. Find "Cross-Repo Architectural Decisions" section
  3. Add new ADR link in table format
  4. Verify line count ≤200
  5. Validate

User request: "Add security practices section with STRIDE and secrets handling"

Actions:

  1. Create practices/security/threat-modeling.md
  2. Create practices/security/secrets.md
  3. Update practices/security/index.md
  4. Add links to AGENTS.md under "Engineering Practices"
  5. Validate

File Naming Conventions

MUST follow these conventions:

  1. Index files: Use index.md NOT README.md (exception: exec-plans/README.md)
  2. ADR naming: Use adr-NNNN- prefix (4 digits with leading zeros)
  3. Short file names: Match production conventions
  4. Separate distinct concepts: Don't combine multiple topics

Update Guidelines

Show full SKILL.md (434 more words)Show less
Adding Content
  • Use appropriate template from templates/
  • Follow existing file structure and style
  • Maintain reference/terse style (tables, checklists)
  • Keep files within length targets (100-400 lines)

Verification Requirements: API/CRD claims link to github.com/openshift/api or kubernetes/apimachinery; pattern claims link to implementations; version/convention claims verified in actual repos (3+ samples); architectural claims link to enhancements/ADRs

Updating AGENTS.md
  • Always read current content first
  • Add new links in appropriate sections
  • Use table format for consistency
  • Keep compressed (navigation, not prose)
  • Verify line count ≤200 after update
Updating Index Files
  • Add one-line description per new file
  • Maintain alphabetical or logical order
  • Use consistent format: - [filename.md](filename.md) - Brief description
Preserving Structure
  • Don't reorganize existing content unless explicitly requested
  • Match existing conventions and patterns
  • Maintain consistency with existing files

Validation

After updates, verify:

✅ New files use correct naming conventions ✅ Index files updated with new entries ✅ AGENTS.md updated if needed (and 100-200 lines) ✅ Internal links work ✅ Files follow reference style (tables, checklists) ✅ No duplication of dev-guide/guidelines content

Gap Detection Mode

Automatic workflow:

  1. Scan existing ai-docs/ structure
  2. Compare against expected files checklist
  3. Report what's missing (by category)
  4. Ask user which gaps to fill

Gap categories scanned:

  • Platform Patterns (controller-runtime, status-conditions, webhooks, etc.)
  • Domain Concepts - Kubernetes (pod, service, crds)
  • Domain Concepts - OpenShift (clusteroperator, clusterversion)
  • Practices (testing, security, reliability, development)
  • Workflows (enhancement-process, implementing-features, exec-plans)
  • Decisions (adr-template, index)
  • References (repo-index, glossary, api-reference)
  • Core Files (DESIGN_PHILOSOPHY, KNOWLEDGE_GRAPH)
  • Navigation (AGENTS.md)

User chooses:

  • Fill all detected gaps
  • Fill specific gaps (select from list)
  • Skip gaps, specify custom addition

Examples

Example 1: Gap Detection Workflow
bash
/update-platform-docs

# Automatic gap detection runs:
🔍 Scanning ai-docs/ for gaps...

## Platform Patterns
Missing:
  - platform/operator-patterns/webhooks.md
  - platform/operator-patterns/finalizers.md

## Workflows
Missing:
  - workflows/exec-plans/README.md
  - workflows/exec-plans/template.md

📊 Summary: 4 missing files detected

# User selects:
"Fill all gaps" OR "Fill exec-plans only" OR "Custom: add observability practices"

# Actions: Creates missing files, updates indexes, validates
Example 2: Add Exec-Plans Workflow
bash
/update-platform-docs

# User: "Add exec-plans guidance to workflows"

# Actions:
mkdir -p ai-docs/workflows/exec-plans
# Create README.md from template
# Create template.md from template
# Update workflows/index.md
# Update AGENTS.md
# Update create-structure.sh
# Validate
Example 2: Add New Platform Pattern
bash
/update-platform-docs

# User: "Add webhooks pattern to operator patterns"

# Actions:
# Create platform/operator-patterns/webhooks.md from template
# Update platform/operator-patterns/index.md
# Update AGENTS.md (add link to webhooks)
# Validate
Example 3: Update Existing File
bash
/update-platform-docs

# User: "Add conversion webhooks section to webhooks.md"

# Actions:
# Read platform/operator-patterns/webhooks.md
# Add new section with conversion webhook guidance
# Validate (check line count, style)

Arguments

bash
/update-platform-docs [--path <repository-path>]

Arguments:

  • --path <repository-path>: Path to enhancements repository (default: current directory)
  • No args: Update documentation in current directory

Prerequisites

Before running:

  1. ✅ ai-docs/ already exists in openshift/enhancements
  2. ✅ You're in openshift/enhancements repository
  3. ✅ You know what you want to add/update

Success Output

text
✅ Platform Documentation Updated

Repository: /path/to/enhancements

Changes:
  ✅ Created: ai-docs/workflows/exec-plans/README.md
  ✅ Created: ai-docs/workflows/exec-plans/template.md
  ✅ Updated: ai-docs/workflows/index.md
  ✅ Updated: AGENTS.md (added exec-plans link)

Validation:
  ✅ File naming conventions correct
  ✅ Index files updated
  ✅ AGENTS.md: 192 lines (target: ≤200)
  ✅ Internal links valid
  ✅ Reference style maintained

Next Steps:
  1. Review changes
  2. Run: git add ai-docs/ AGENTS.md
  3. Run: git commit -m "Add exec-plans workflow guidance"

Common Mistakes to Avoid

❌ Mistake 1: Making AGENTS.md Too Long

Wrong: Adding verbose descriptions to AGENTS.md Right: Keep compressed, table-based navigation only

❌ Mistake 2: Not Updating Index Files

Wrong: Creating new file without updating parent index.md Right: Always update corresponding index.md

❌ Mistake 3: Inconsistent Naming

Wrong: Creating README.md (except in exec-plans/) or adr-1-topic.md Right: Use index.md (or exec-plans/README.md as exception) and adr-0001-topic.md

❌ Mistake 4: Duplicating Content

Wrong: Copying content from dev-guide/guidelines Right: Link to authoritative source or reformat for AI agents

❌ Mistake 5: Documenting Without Verification

Wrong: Patterns from memory, API fields without checking github.com/openshift/api, unverified conventions Right: Verify in actual code, link to type definitions (k8s/apimachinery, openshift/api), check multiple repos for patterns

See Also

  • Platform Documentation (openshift/enhancements/ai-docs/) - Existing platform docs
  • /component-docs - Create component documentation

© openshift-eng, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 7 other files (scripts) in plugins/agentic-docs/skills/update-platform-docs of openshift-eng/ai-helpers.

  • SKILL.md
  • scripts/discover.sh
  • scripts/gap-detection.sh
  • scripts/validate.sh
  • templates/adr-template.md
  • templates/domain-concept-template.md
  • templates/operator-pattern-template.md
  • templates/practice-template.md

Open the folder on GitHubat commit a627176

Compare with similar skills

Update Platform Docs next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Update Platform Docs compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Update Platform Docs this skillopenshift-eng/ai-helpers120—~2.9kAutomated safety check: PassApache-2.0
MCP Server Builderanthropics/skills180k62 repos~2.3kAutomated safety check: PassApache-2.0
Hook Development for Claude Code Pluginsanthropics/claude-plugins-official37k11 repos~4.1kAutomated safety check: NotesApache-2.0
Using Superpowersfarm-fe/farm5.6k34 repos~1.4kAutomated safety check: PassMIT
Executing Plans Inlineobra/superpowers296k2 repos~5.1kAutomated safety check: PassMIT
Claude Code Agent Developmentanthropics/claude-plugins-official37k8 repos~2.8kAutomated safety check: PassApache-2.0

Similar skills

  • MCP Server Builder

    anthropics/skills

    Official

    Guides the design and implementation of Model Context Protocol servers in TypeScript or Python, from tool naming and error messages to evaluation.

    180k GitHub starsUsed in 62 repos~2.3k tokens
    Agent WorkflowsAuto-check passed

  • Hook Development for Claude Code Plugins

    anthropics/claude-plugins-official

    Official

    Explains how to write Claude Code plugin hooks, both prompt-based checks and bash commands, for events such as PreToolUse, Stop and SessionStart.

    37k GitHub starsUsed in 11 repos~4.1k tokens
    Agent WorkflowsAuto-check: notes

  • Using Superpowers

    farm-fe/farm

    A skill your agent uses when starting any conversation - establishes how to find and use skills, requiring Skill tool invocation before ANY response including clarifying questions

    5.6k GitHub starsUsed in 34 repos~1.4k tokens
    Agent WorkflowsAuto-check passed

  • Executing Plans Inline

    obra/superpowers

    Has the agent carry out an implementation plan itself, task by task in the current session, keeping a ledger, proving each step with a test and ending with one whole-branch review.

    296k GitHub starsUsed in 2 repos~5.1k tokens
    Agent WorkflowsAuto-check passed

  • Claude Code Agent Development

    anthropics/claude-plugins-official

    Official

    Explains how to write agents for Claude Code plugins: the markdown file with YAML frontmatter, trigger descriptions, model and color settings, and system prompt design.

    37k GitHub starsUsed in 8 repos~2.8k tokens
    Agent WorkflowsAuto-check passed

  • Skill Creator

    Azure/azqr

    Official

    Create new skills, modify and improve existing skills, and measure skill performance.

    794 GitHub starsUsed in 89 repos~8.2k tokens
    Agent WorkflowsAuto-check passed

More from openshift-eng/ai-helpers

All 118 skills in this repo

  • Investigate CI Reliability

    openshift-eng/ai-helpers

    Find and independently validate actionable reliability defects across OpenShift release jobs and presubmits, then export portable issue handoffs.

    120 GitHub stars~1.9k tokensUpdated yesterday
    Auto-check passed

  • Address Review PR

    openshift-eng/ai-helpers

    Fetch and address all PR review comments — categorize by priority, make code changes, post replies, and push.

    120 GitHub stars~2.9k tokensUpdated yesterday
    Auto-check passed

  • Categorize Activity Types

    openshift-eng/ai-helpers

    Categorize Jira issues into Red Hat Sankey Activity Type categories using MCP Jira tools.

    120 GitHub stars~2.4k tokensUpdated yesterday
    Auto-check passed

  • Has Review Work

    openshift-eng/ai-helpers

    Decide whether a GitHub PR has unanswered authorized review comments or new required CI failures worth a follow-up agent.

    120 GitHub stars~1.9k tokensUpdated yesterday
    Auto-check passed

  • Must Gather Analyzer

    openshift-eng/ai-helpers

    Analyze OpenShift must-gather diagnostic data including cluster operators, pods, nodes, and network components.

    120 GitHub stars~2.3k tokensUpdated yesterday
    Auto-check passed

  • Payload Autodl JSON

    openshift-eng/ai-helpers

    Schema for the autodl JSON data file produced by payload-analysis for database ingestion — you must use this skill whenever generating the autodl JSON file

    120 GitHub stars~2.6k tokensUpdated yesterday
    Auto-check passed

Categories

Questions about Update Platform Docs

What does Update Platform Docs do?

Update existing platform documentation with automatic gap detection in openshift/enhancements. Update Platform Docs is an agent skill from openshift-eng/ai-helpers.

When should I use Update Platform Docs?

Update Platform Docs fits situations like: agent Workflows work in your project.

How do I install Update Platform Docs in Claude Code?

Run `npx skills add openshift-eng/ai-helpers --skill update-platform-docs -a claude-code`. Or copy the skill folder (plugins/agentic-docs/skills/update-platform-docs in openshift-eng/ai-helpers) into .claude/skills/update-platform-docs in your project. Claude Code loads it when a task matches its description.

How do I install Update Platform Docs in Codex?

Run `npx skills add openshift-eng/ai-helpers --skill update-platform-docs -a codex`. Or copy the skill folder (plugins/agentic-docs/skills/update-platform-docs in openshift-eng/ai-helpers) into .agents/skills/update-platform-docs in your project. Codex loads it when a task matches its description.

Can I use Update Platform Docs in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add openshift-eng/ai-helpers --skill update-platform-docs -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/update-platform-docs, .gemini/skills/update-platform-docs, .github/skills/update-platform-docs and .opencode/skills/update-platform-docs in your project.

What does Update Platform Docs need to run?

Going by SKILL.md and its folder, Update Platform Docs needs a shell for the scripts in its folder. Our summary lists: A Bash shell.

Does Update Platform Docs access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Update Platform Docs safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does Update Platform Docs use?

Update Platform Docs is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Update Platform Docs use?

About 2.9k tokens (SKILL.md is roughly 11k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Update Platform Docs?

Skills that share tags, products or a category with Update Platform Docs: MCP Server Builder (anthropics/skills, 180k stars), Hook Development for Claude Code Plugins (anthropics/claude-plugins-official, 37k stars), Using Superpowers (farm-fe/farm, 5.6k stars) and Executing Plans Inline (obra/superpowers, 296k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Update Platform Docs?

openshift-eng (a GitHub organization) maintains it in openshift-eng/ai-helpers, which has 120 GitHub stars. The repository holds 118 skills in this directory. The repository was last updated on October 6, 2026.

Source: openshift-eng/ai-helpers on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.