Skip to content
Skills Library
DevOps & cloud · Analysis

documentation

/documentation

Use this skill to survey and catalog an Itential platform — when someone wants to know what's on their platform, document global assets (workflows, templates, LCM models, golden config, OM automations) that are NOT inside a named project, group them into logical use cases, and produce a master catalog or README. Trigger it for phrases like "document everything on the platform", "what use cases do we have?", "catalog all our global workflows", "I inherited this platform and have no idea what's there", "group our automations by use case", or "produce a platform README". The output is a structure

Licence
GPL-3.0
Last repository change
15.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
8
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 15.10.2026, without references to retired models or APIs.

Licence

GPL-3.0, otwarta.

What it does and when to use it

Use this skill to survey and catalog an Itential platform — when someone wants to know what's on their platform, document global assets (workflows, templates, LCM models, golden config, OM automations) that are NOT inside a named project, group them into logical use cases, and produce a master catalog or README. Trigger it for phrases like "document everything on the platform", "what use cases do we have?", "catalog all our global workflows", "I inherited this platform and have no idea what's there", "group our automations by use case", or "produce a platform README". The output is a structure

Triggers from the description

document everything on the platformwhat use cases do we have?catalog all our global workflowsI inherited this platform and have no idea whatgroup our automations by use caseproduce a platform README
Original author description

Use this skill to survey and catalog an Itential platform — when someone wants to know what's on their platform, document global assets (workflows, templates, LCM models, golden config, OM automations) that are NOT inside a named project, group them into logical use cases, and produce a master catalog or README. Trigger it for phrases like "document everything on the platform", "what use cases do we have?", "catalog all our global workflows", "I inherited this platform and have no idea what's there", "group our automations by use case", or "produce a platform README". The output is a structure

How it works

  1. Customization
  2. CRITICAL: Output Requirements
  3. What This Does
  4. Flow
  5. Step 0: Determine Scope
  6. Step 1: Collect and Classify Assets
  7. Step 2: Discover Relationships and Group
  8. Step 3: Present Groupings to Engineer
  9. Step 4: Write Per-Use-Case Reports
  10. Step 5: Write Master README
Original SKILL.md headings · 423 lines, 2,966 words
SKILL.md preview
---
name: documentation
description: Use this skill to survey and catalog an Itential platform — when someone wants to know what's on their platform, document global assets (workflows, templates, LCM models, golden config, OM automations) that are NOT inside a named project, group them into logical use cases, and produce a master catalog or README. Trigger it for phrases like "document everything on the platform", "what use cases do we have?", "catalog all our global workflows", "I inherited this platform and have no idea what's there", "group our automations by use case", or "produce a platform README". The output is a structured catalog — customer-spec.md + solution-design.md per use case + master README. NOT for documenting a specific named project — use /project-to-spec for that. NOT for building new automation.
---

# Documentation

**Purpose:** Read Itential assets → discover relationships → group into use cases → produce documentation
**Output:** `customer-spec.md` (inferred HLD per use case) + `solution-design.md` (as-built LLD per use case) + `README.md` (master index, only when multiple use cases)
**Feeds into:** Can be handed to `/spec-agent` for refinement or `/solution-arch-agent` for redesign

## Customization

Before using this skill, check `custom/org/`, `custom/team/` and `custom/dev/`
in this skill's own folder. Read every `.md` file found — any folder may be
empty or absent. Apply them on top of everything below; where a file overrides a
specific rule here, follow the override. More specific wins: dev > team > org >
this document. No customization may weaken this skill's safety
rules or put credentials in committed files.

**Bundled files:** paths in this skill that start with `assets/` or `scripts/` are
relative to this skill's own folder. When you read one, or pass one to a shell
command (which runs from the user's working folder), use this skill's folder +
that relative path — e.g. `<this skill's folder>/assets/helpers/create/create-workflow.json`.
---

## CRITICAL: Output Requirements

**The ONLY deliverables are markdown files.** Do NOT produce JSON index files, JSON catalogs, or any intermediate artifacts. All analysis happens in-memory.

```
{reports-directory}/
  README.md                          ← master index of all use cases ONLY when more than one use case
  {use-case-slug}/
    customer-spec.md                 ← inferred HLD (business purpose, scope, requirements)
    solution-design.md               ← as-built LLD (components, flows, adapters, data model)
  {use-case-slug}/
    customer-spec.md
    solution-design.md
  ...
```

**Never write JSON files as output.** No `workflow-index.json`, no `asset-index.json`, no `use-case-groups.json`. The user wants documentation, not data dumps.

---

## What This Does

Surveys **global** Itential assets — workflows, JSON forms, transformations, templates, command templates, analytic templates, Operations Manager automations, golden configuration trees and compliance plans, and LCM resource models that live outside named projects. Accepts `all`, `platform`, a directory path, or a list of specific global asset names. Discovers how they relate to each other, groups them into logical use cases, and produces documentation for each group plus a master index when there are multiple use cases.

> **For a named project:** Use `/project-to-spec` instead — it reads a single project's components and produces customer-spec.md + solution-design.md tailored to that project.

---

## Flow

```
User invokes /documentation ['all' | 'platform' | directory | specific global asset names]
      |
      ├── Step 0: Determine Scope
      |     ├── Project named? → redirect to /project-to-spec
      |     ├── Specific global assets named? → resolve + discover relationships → ask grouping preference
      |     └── 'all' / platform / directory? → full collection + grouping flow
      |
      ├── Step 1: Collect + classify global assets (in-memory)
      ├── Step 2: Discover relationships + group into use cases (in-memory)
      ├── Step 3: Present proposed groupings to engineer for approval
      ├── Step 4: Write per-use-case reports (customer-spec.md + solution-design.md)
      ├── Step 5: Write master README.md (ONLY when more than one use case)
      └── Step 6: Present summary to engineer for review
```

---

## Step 0: Determine Scope

Before collecting assets, determine what the user wants to document.

### Pattern 1 — Project named

If the user names a specific project, **redirect them to `/project-to-spec`** — that skill is purpose-built for single-project documentation and produces a more thorough analysis.

> "It looks like you want to document a specific project — use `/project-to-spec` for that. It reads the project's components directly and produces a more thorough customer-spec.md and solution-design.md for it."

### Pattern 2 — Specific global asset(s) named

If the user provides one or more asset names or IDs:

1. Resolve each asset via the platform API or local files
2. Traverse the relationship graph starting from each named asset (childJob links, OM→workflow, LCM→workflow, golden config→command template, etc.)
3. Present the discovered asset cluster to the engineer:
   - List all assets found (named + discovered via relationships)
   - Show how they connect

4. Ask the engineer:
   > "I found these assets and their relationships. How should I document them?"
   > - **(Default) Group into use cases** — analyze and cluster into logical groups, then produce HLD+LLD per group
   > - **Document as a single unit** — treat the entire cluster as one use case, produce one HLD+LLD
   > - **Document each asset independently** — produce separate minimal documentation per asset without cross-linking

Proceed based on the engineer's answer.

### Pattern 3 — All globals / platform / directory

If the user says `all`, `platform`, or provides a directory path, run the full collection and grouping flow (Steps 1–6) without asking about grouping preference.

---

## Step 1: Collect and Classify Assets

Ask the engineer for the asset source if not specified. Two modes:

### Mode A — Local Directory

Scan for asset JSON files organized by type:

```
directory/
  workflows/                          *.json
  json_forms/                         *.json
  transformations/                    *.json or *.jst.json
  templates/                          *.json
  command_templates/                  *.json
  operations_manager_automations/     *.json
  golden_config/                      *.json
  lcm/                                *.json
```

If the directory is flat (all JSON at root), classify by JSON structure signatures below.

If a `projects/` subfolder exists, scan it too. Project manifest files (containing `name` + `components[]`) identify which assets belong to a project — use that grouping when building the relationship graph. Strip `@projectId:` prefixes from any workflow names found inside.

### Mode B — Platform API

Authenticate using `.auth.json` (see `assets/AGENTS.md` auth reuse pattern). Fetch global assets (ensure you fetch pagination if there are a lot of assets):

```
GET /automation-studio/workflows?exclude-project-members=true&limit=500
GET /automation-studio/templates?limit=500
GET /automation-studio/json-forms?limit=500
GET /operations-manager/automations
GET /mop/templates
GET /golden-config/trees
GET /golden-config/plans
GET /lifecycle-manager/model
GET /automation-studio/projects?limit=500
```

> **Visibility caveat:** see `assets/AGENTS.md`'s "Project Visibility" section. Global assets (this skill's focus) aren't ACL-restricted, so the global catalog isn't undercounted by RBAC — but `GET /automation-studio/projects?limit=500` is per-project-ACL-filtered. Since this skill targets globals, projects are out of scope by default; if the engineer names a specific project they expect, route to `/project-to-spec` instead.

### Classification Signatures

| Asset Type | Identifying Fields |
|---|---|
| **Workflow** | `tasks` (object), `transitions` |
| **JSON Form** | `schema`, `struct`, `uiSchema` |
| **Transformation** | `incoming`, `outgoing`, `steps` |
| **Template** | `type` (textfsm/jinja2), `template` field |
| **Command Template** | `commands[]` with `rules[]` |
| **Analytic Template** | `commands[]` with `analytics[]` or `baseline` fields |
| **OM Automation** | `triggers[]`, `componentName` |
| **Golden Config Tree** | `nodes[]`, `rootNode`, `treeType` |
| **Golden Config Compliance Plan** | `planType`, `configSpec`, `devices[]` |
| **LCM Resource Model** | `resourceType`, `actions[]`, `schema` |

**Build the asset index in-memory only.** For each asset, note: name, file path/ID, type, and key metadata.

---

## Step 2: Discover Relationships and Group

### Relationship Discovery

Build a relationship graph in-memory connecting all assets:

1. **Workflow → Workflow (childJob links):** For each workflow task where `name === "childJob"` AND `app === "WorkFlowEngine"`, extract child workflow name from `variables.incoming.workflow`. Strip `@projectId:` prefixes.

2. **Workflow → JSON Form:** Tasks where `app === "JsonForms"` or name contains `RenderJsonSchema`/`JsonForm`.

3. **Workflow → Template:** Tasks where `app === "TemplateBuilder"` (renderJinjaTemplate, applyTemplate, applyTextFSMTemplate).

4. **Workflow → Transformation:** Tasks where `name === "transformation"`.

5. **Workflow → Command Template:** Tasks referencing MOP operations (runCommandTemplate).

6. **OM Automation → Workflow:** `componentName` field names the target workflow. Trigger types reveal entry mode: schedule, endpoint (webhook/API), manual (with optional formId).

7. **LCM Resource Model → Workflow:** Each LCM action has an `actionWorkflow` field naming an IAP workflow → link.

8. **Golden Config Compliance Plan → Command Template:** Plans reference MOP command templates for configuration checks → link.

9. **Workflow → Golden Config:** Workflows calling golden-config API tasks via adapter → link.

10. **Adapter patterns:** Collect tasks where `location === "Adapter"` — extract `app` (type name) and operation name.

11. **Naming prefix clustering:** Split on ` - ` (space-dash-space). Assets sharing a prefix are candidates for the same use case.

### Grouping Rules (apply in order)

1. **OM Automations as Entry Points:** Each OM automation's `componentName` → root workflow → traverse childJob graph → collect all reachable workflows + referenced forms/templates/transformations/command templates = one cluster.

2. **LCM Resource Models as Entry Points:** Each LCM model → action workflows → traverse childJob graph → collect all reachable assets = one cluster. If a workflow cluster already contains these workflows, merge the LCM model into that cluster.

3. **Golden Config Clusters:** Golden config trees + their compliance plans + referenced command templates → one cluster. If workflows reference these golden config assets, merge into the same cluster.

4. **Expand by Naming Prefix:** Add ungrouped assets sharing the same naming prefix as assets already in a cluster.

5. **Ungrouped Workflow Trees:** Any root workflow (no parent) with children → new cluster.

6. **Shared Utilities:** Workflows appearing in 3+ clusters → "Shared Utilities" group. Also include: generic TextFSM templates, utility transformations (math, array ops), common utilities (MongoDB CRUD, credential retrieval, notifications).

7. **Test / Standalone:** Workflows with developer name prefixes, `[TEST]`/`test-`/`dummy` patterns, Jira ticket patterns, or <5 tasks with no children and no triggers → "Standalone / Test Workflows" (catalog only, no full HLD/LLD).

8. **Remaining Ungrouped:** Group by functional similarity or list as individual entries in master README.

### Analyze the Components

Work through the components to reconstruct intent and structure.

#### Identify the orchestrator

Find the parent workflow — usually the one that:
- Has no `childJob` references pointing to it from other workflows
- References other workflows via `childJob` tasks
- Has the most complex transition graph

For LCM clusters, the resource model itself is the anchor — its action workflows are the orchestrators.
For golden config clusters, the compliance plan anchors the cluster.

#### Map the data flow

For the orchestrator and each child:
1. What are the **inputs**? (inputSchema properties)
2. What adapters are called? (location: "Adapter" tasks)
3. What utility tasks are used? (merge, query, evaluation, childJob, makeData)
4. What are the **outputs**? (outputSchema properties, `$var.job.x` assignments)
5. What external systems are touched? (adapter names → infer ServiceNow, Route53, etc.)

#### Infer the phases

Each major section of the orchestrator maps to a phase:
- A `childJob` to a child workflow = one phase
- An `evaluation` branch = a decision point
- An adapter call cluster = an integration phase
- A `ViewData` = an approval gate
- Error handling branches = rollback/recovery phases
- An LCM action = a lifecycle phase
- A compliance plan check = a validation phase

#### Reconstruct acceptance criteria

From the workflow structure, infer what "done" looks like:
- What does the final outgoing variable represent?
- What adapters were called? → "ServiceNow ticket created and updated"
- What verifications exist? → `evaluation` tasks checking status
- What is the `outputSchema`? → these are the observable outcomes

---

## Step 3: Present Groupings to Engineer

**Stop and present the proposed groupings before writing any reports.** Ask:

1. "Here are the use case groups I identified — does this look right?"
2. "These assets are ungrouped — should any be added to an existing group?" — default no
3. "These appear to be test/dev workflows — should I catalog or skip them?" — default skip

Show each group with: name, category (Core/Specialized/Shared/Reference), approximate asset count, and 1-line description.

**Wait for engineer approval before proceeding to Step 4.**

---

## Step 4: Write Per-Use-Case Reports

For each approved use case group, create a directory (or write directly to reports root if only one use case) with two markdown files.

### Produce `customer-spec.md`

Write professional, narrative documentation — not mechanical spec sheets. The HLD should read like a business-facing document with rich prose, detailed tables, and domain-specific context.

→ See template in `assets/helpers/documentation-output-templates.md` — **"customer-spec.md Template"**

**For test/standalone use cases**, use a simplified catalog format — asset table with Purpose and Adapters columns only. No full HLD needed.

### Produce `solution-design.md`

Write the as-built LLD — this is factual, not inferred. Each component should have at least a sentence description, so an engineer could understand the full system without reading the source JSON.

→ See template in `assets/helpers/documentation-output-templates.md` — **"solution-design.md Template"**

#### Generating Section D: Execution Flow

The guidance and example are in the Section D placeholder in `assets/helpers/documentation-output-templates.md`.

Do not add a sequence diagram to the HLD (`customer-spec.md`). Section 2 of the HLD is a narrative paragraph only.

---

## Step 5: Write Master README

**Only write this step when there are 2 or more use cases.**

Create `README.md` at the root of the reports directory.

→ See template in `assets/helpers/documentation-output-templates.md` — **"README.md Template"**

---

## Step 6: Present to Engineer

Show a summary:

1. **Asset inventory** — total files analyzed per type
2. **Use case groups** — count and names
3. **Reports produced** — list of directories/files with customer-spec.md + solution-design.md
4. **Excluded assets** — what was skipped
5. **Gaps** — "I don't see rollback logic or notifications."

Ask the engineer to review the reports. Next steps:
- **Accept** — use the reports as-is
- **Refine** — hand specific use case specs to `/spec-agent`
- **Redesign** — hand to `/solution-arch-agent`
- **Organize into projects** — proceed to Step 7

---

## Step 7: Organize Global Assets into Projects (Optional)

After the engineer accepts the use case groupings and reviews the reports, ask:

> "Would you like me to create a project for each use case and move the assets in? Moving assets into a project renames them with an `@projectId:` prefix — anything currently referencing those assets by name will need updating. Shared utility assets will stay global. Should I proceed?"

If no, stop here. The documentation stands as-is.

If yes, for each approved use case group (skip "Shared Utilities"):

**1. Create the project:**
```
POST /automation-studio/projects
{"name": "{use-case-name}", "description": "{one-line from customer-spec.md}", "thumbnail": "", "backgroundColor": "#FFFFFF"}
```
Save `data._id` as `projectId`.

**2. Add components:**
```
POST /automation-studio/projects/{projectId}/components/add
{
  "components": [
    {"type": "workflow", "reference": "{workflow-id}", "folder": "/"},
    {"type": "template", "reference": "{template-id}", "folder": "/"},
    {"type": "mopCommandTemplate", "reference": "{mop-name}", "folder": "/"}
  ],
  "mode": "move"
}
```

Component type values: see `assets/AGENTS.md` Rule 13.

**3. Build a reference impact report before moving anything:**

Before executing any moves, scan all global workflows, OM automations, and LCM models to find references that will break. For each asset being moved, find:

- **Workflows** with a `childJob` task where `variables.incoming.workflow` matches the asset's current name
- **OM automations** where `componentName` matches the asset's current name
- **LCM models** where any `actions[].actionWorkflow` matches the asset's current name

Produce a table:

| Asset being moved | Referenced by | Field | New name after move |
|------------------|--------------|-------|-------------------|
| `VLAN_Provision_Parent` | `Monthly_Audit` (workflow) | childJob.workflow | `@abc123: VLAN_Provision_Parent` |
| `DNS_Create` | `DNS Automation` (OM automation) | componentName | `@abc123: DNS_Create` |

Show this to the engineer **before** proceeding:
> "Moving these assets will break the following references. I won't fix them automatically — you'll need to update these manually after the move. Here's what needs changing:"

**4. Execute the moves** (after engineer confirms they've noted the impact):

For each group, run the `POST .../components/add` calls as above.

**5. After all groups are processed, show a final summary:**

| Use Case | Project ID | Assets Moved | Broken References to Fix |
|----------|------------|-------------|--------------------------|
| {name} | {id} | {count} | {count} — see impact report above |

Flag anything that couldn't be moved (already in a project, API error) for manual follow-up.

**Warnings to keep in mind:**
- Shared Utilities stay global — do not move them
- Assets already in a project cannot be moved again — skip and report
- Cross-project references (workflow in one project referencing a workflow in another) must use the full `@{otherProjectId}: {name}` format

---

## What to Watch For

- **Orphaned workflows:** No childJob parent AND no OM trigger. May be standalone utilities, abandoned, or externally invoked. Check adapter usage to infer purpose.
- **`@projectId:` prefixed names:** Strip prefix (everything through colon+space) before matching.
- **Empty componentName:** Fall back to trigger names, `actionId`, or automation name.
- **Duplicate/backup workflows:** Names with "Backup", date suffixes, version numbers → note as backups, don't give own group.
- **Cross-use-case shared workflows:** Document fully in primary group, add cross-references in others.
- **Transformation `.jst.json` naming:** Match on internal `name` field, not filename.
- **Template `data` field:** Often a JSON string, not parsed object — parse before analyzing.
- **Large TextFSM libraries:** Group under Shared Utilities, not individual use cases.
- **Command template rules:** Each rule encodes a compliance check — valuable for HLD requirements.
- **LCM `actionWorkflow` may be missing:** If a LCM action has no linked workflow, note the gap — the action is defined but not implemented.
- **Golden config trees without compliance plans:** Document the structure but note there is no automated compliance enforcement.
- **Workflow descriptions and task summaries are the best source of business intent** — use them heavily.
- **Non-hex task IDs:** Task IDs like `apush` or `myTask` are a known bug pattern (`$var` references silently fail on these).
- **Static values as indicators:** Hard-coded strings in merge tasks or newVariable tasks often reveal business rules (e.g., `"value": "production"` → production-only path).
- **Missing error transitions:** Note any adapter tasks without error transitions — this is a quality gap in the existing implementation.

---

## Gotchas

- **Global assets are not access-restricted; projects are** (see `assets/AGENTS.md` Project Visibility). If the engineer names a specific project they expect, route to `/project-to-spec` rather than declaring it absent.
- **NEVER produce JSON files as output.** Only markdown reports.
- **childJob `workflow` is the primary relationship link.** Don't trace `$var` references across workflows.
- **Naming prefix is a heuristic, not a rule.** Prioritize childJob graph over naming when they conflict.
- **OM automations can have multiple triggers.** Document all of them.
- **Not every asset connects.** Don't force them into groups — catalog in Shared Utilities or Reference.
- **When unsure about golden config or LCM relationships**, ask the engineer rather than guessing.
- **Master README is only for multiple use cases.** Single use case → write files directly in reports directory, no subdirectory, no README.
Files in this package (8)
  • SKILL.md 22 KB
  • agents/openai.yaml 1 KB
  • assets/AGENTS.md 57 KB
  • assets/helpers/documentation-output-templates.md 16 KB
  • assets/helpers/create/create-workflow.json 1 KB
  • custom/dev/.gitkeep 1 KB
  • custom/org/.gitkeep 1 KB
  • custom/team/.gitkeep 1 KB

Versions

RepositoryScoreLicence
This page · itential/builder-skills100GPL-3.0
software-combined/SC_AI100Apache-2.0
DaveSkender/Stock.Indicators100Apache-2.0
mcouthon/agents100MIT
YLfjuk/deltafold100MIT
comet-ml/opik100Apache-2.0
runwield/runwield100MIT
anthropics/knowledge-work-plugins100Apache-2.0
luocfprime/labtasker100Apache-2.0

Database snapshot: 13.11.2026 · package version 75dfe06f0f20 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100itential-lcm
    Manage resource models, instances, actions, and lifecycle execution in Itential Lifecycle Manager. Use when defining reusable service models, running actions against resource instances, or tracking action execution history.
  • 100itential-automation
    Itential Automation Platform (IAP) — network automation orchestration, device configuration management, compliance enforcement, workflow execution, golden config, lifecycle management, and gateway services via 65+ MCP tools. Use when the change should go through IAP's governed…
  • 95itential-golden-config
    Build golden config trees, config specs, compliance plans, run compliance checks, grade reports, and remediate violations. Use when the user needs to define configuration standards or check device compliance.
  • 100pyats-config-mgmt
    Direct, pyATS-based network change management - pre-change baselines, configuration deployment, post-change verification, rollback procedures, and compliance validation. Use when pushing config to a device, planning a network change, rolling back a configuration, or running…
  • 90devops-internal-developer-platform
    Deep dive into IDP design: golden path architecture, platform APIs, Backstage plugin development, software templates, tech docs, service catalog design, platform adoption, and developer experience measurement. Covers: Scaffolder custom actions, catalog entity modeling, Backstage…
  • 95readme
    When the user wants to create or update a README.md file for a project. Also use when the user says 'write readme,' 'create readme,' 'document this project,' 'project documentation,' or asks for he...

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.