Setup and use guide · Apptio Skills Registry

Put source-linked Apptio product knowledge where people already work: inside Claude Code or Kiro for guided execution, or inside a Copilot Notebook for focused retrieval and analysis.

The registry turns large IBM documentation sets into compact task routers and focused references. An administrator can move faster without losing production guardrails, while an analyst can begin with a familiar symptom and follow an evidence-based troubleshooting path without needing to understand every backend detail first.

ONE SOURCE, THREE DELIVERY PATHS Use Claude Code or Kiro when the AI should help perform the work. Use a Copilot Notebook when people need a shared, searchable knowledge space.

Choose a setup

I want to…	Start here	What it provides
Investigate or plan product work with Claude Code	Claude Code plugin	Automatic routing to the relevant skill and references
Use the same skills in a Kiro workspace	Kiro workspace skills	Automatic discovery from `.kiro/skills/` and interactive skill commands
Give analysts a focused product research workspace	Copilot Notebook	Retrieval grounded in a selected set of uploadable Word files
Review what the registry covers before installing anything	Browse the skills	A product-by-product map of the 36 current skills
Build the same pattern for another IBM product	Extend the registry	A repeatable documentation survey and skill-authoring workflow

Why this is more useful than a folder of documentation

Task-ready context

A compact router selects only the references needed for the job, keeping answers focused instead of loading an entire product manual.

Traceable answers

Detailed references retain their official IBM source URLs, so teams can verify guidance and distinguish documentation from assumptions.

A lower technical barrier

Analysts can describe missing data, an unexpected result, or a failed process in plain language and receive guided checks that explain what each step proves.

Production-aware assistance

Permissions, tenant differences, read-only diagnosis, write boundaries, version gates, and escalation points stay part of the workflow.

Set up the Claude Code plugin

The repository includes a validated .claude-plugin/plugin.json manifest that exposes the Targetprocess, TBM Studio, and Planning registries together. Local loading is the simplest setup for this repository today and is also the official plugin-development workflow documented by Claude Code.

1. Clone the registry

git clone https://github.com/SantiaGoMode/apptio-skills-registry.git
cd apptio-skills-registry

2. Validate the package

claude plugin validate . --strict

This checks the manifest and plugin structure before it is loaded.

3. Start Claude Code with the plugin

claude --plugin-dir /absolute/path/to/apptio-skills-registry

Tip: use an absolute path if you launch Claude Code from different project folders. During an active session, run /reload-plugins after changing a skill.

4. Confirm a skill is available

/apptio-skills-registry:tp-rest-api-v2

Help me build a read-only query for open features and explain the paging strategy.

Skills are namespaced by the plugin name. Product prefixes make the route explicit: tp- for Targetprocess, tbm- for TBM Studio, and plan- for Planning.

Plugin loading and reload behavior: Claude Code plugin documentation.

Set up the Kiro workspace skills

The repository includes a portable .kiro/skills/ package containing all 36 skill routers and their focused references. Kiro's default agent discovers workspace skills automatically when it starts from the repository.

1. Clone the registry and start Kiro from its root

git clone https://github.com/SantiaGoMode/apptio-skills-registry.git
cd apptio-skills-registry
kiro-cli chat

2. Confirm all workspace skills are discovered

/context show

Under .kiro/skills/*/SKILL.md, Kiro should list 36 matched skill files: 11 Targetprocess, 12 TBM Studio, and 13 Planning.

3. Invoke a skill or describe the task

/tp-rest-api-v2

Help me build a read-only query for open features and explain the paging strategy.

Use interactive chat for skill commands. Start kiro-cli chat and enter /<skill-name>. Kiro's headless --no-interactive mode treats slash commands differently; use a plain-language prompt there instead.

Discovery, activation, workspace paths, and slash commands: Kiro Agent Skills documentation.

Use the agent skills

Claude Code and Kiro can invoke a specific skill, but most work can begin with a plain-language request. The skill descriptions help either agent select the right router.

CLAUDE CODE DIRECT ROUTE

Use the plugin namespace

/apptio-skills-registry:tp-automation-rules

Diagnose why this rule stopped creating comments.

KIRO DIRECT ROUTE

Use the workspace skill name

/tp-automation-rules

Diagnose why this rule stopped creating comments.

For automatic routing in either agent, describe the outcome directly: Review this Targetprocess entity-view JSON and explain why the lookup is empty. Start read-only.

Give the agent the evidence it needs

Name the product and environment when the distinction matters.
Include the symptom, expected result, and the last known working behavior.
Paste sanitized errors, configuration, formulas, or API responses.
State whether you want analysis only or are authorizing a change.
Ask it to identify assumptions and show which checks are read-only.

Set up a Copilot Notebook

Copilot Notebooks work with flat reference collections. The included builder turns each Markdown router and reference into a styled .docx, rewrites internal links to the flattened filenames, and keeps source provenance in the generated documents.

1. Choose the product knowledge you need

python3 tools/build_notebook_docs.py --list
python3 tools/build_notebook_docs.py tp
python3 tools/build_notebook_docs.py tbm
python3 tools/build_notebook_docs.py planning
python3 tools/build_notebook_docs.py all

The generated files appear under each registry:

tp_skills/copilot_notebook_docs/
tbm_skills/copilot_notebook_docs/
planning_skills/copilot_notebook_docs/

2. Create and ground the notebook

Open the Microsoft 365 Copilot app and select Notebooks.
Create or open a notebook for one product, team, or operational problem.
Under References, select the plus button, then choose Upload or drag and drop files.
Add the generated .docx files that match the notebook's scope.
Give the notebook a short instruction such as: “Answer from these references, identify the product area used, retain source links, and flag tenant-specific assumptions.”

Scope the pack deliberately. Microsoft currently documents grounding of up to the first 300 references for Microsoft 365 Copilot users and up to 50 for Copilot Chat users. The full registry produces 203 documents, so a product- or task-focused selection is usually easier to navigate and may be required by your license.

Current upload flow, permissions, formats, and reference limits: Microsoft Support: Add references to a Copilot Notebook.

3. Ask grounded questions

Which references apply to a Targetprocess REST API v2 relation query, and what should I verify before changing it? I am an analyst seeing missing report data. Give me a read-only diagnostic sequence and explain what each check proves.

Compare the documented roles of API v1 and API v2. Cite the relevant source links and identify any tenant-specific assumptions.

Turn the guidance for this task into an administrator-ready checklist with an escalation point.

Keep the knowledge current

The product registry Markdown is canonical. Generated Word files are intentionally ignored by Git, while .kiro/skills/ is a committed portable delivery copy. Refresh both downstream forms whenever their canonical source changes.

Pull the latest repository changes.
Refresh the affected .kiro/skills/<skill-name>/ copy and confirm it matches the canonical router and references.
Run the builder again for the affected registry.
Remove or replace the older notebook references so similarly named versions do not compete during retrieval.
Run a known-answer prompt and confirm that the response uses the updated reference.

git pull --rebase
python3 tools/build_notebook_docs.py tp

Practical use cases

Who	Useful starting points	Value
Targetprocess administrators	API queries, automation rules, entity views, imports, integrations, formulas, governance	Faster diagnosis and safer change planning in active environments
Analysts	Missing data, unexpected calculations, failed jobs, inconsistent reports	A guided path from visible symptom to evidence-backed escalation
TBM model and reporting teams	Data Studio, model allocations, formulas, reports, build and deploy	Layer-first troubleshooting that narrows where a defect originates
Planning teams	Plan lifecycle, line items, labor, forecasts, approvals, integrations	Shared understanding across planners, administrators, and reviewers
Governance and enablement leads	Permissions, production boundaries, source verification, reusable prompts	A consistent operating pattern across teams and products
Skill authors	New IBM product documentation registries	Reuse the architecture without rebuilding the knowledge pipeline

Starter prompt patterns

Troubleshoot without immediately changing anything

I am seeing [symptom] in [product/environment].
Expected: [expected result]
Observed: [actual result]

Start with read-only checks. Explain what each check proves, identify assumptions,
and tell me when this should move to an administrator or engineer.

Prepare an administrator-ready change plan

Using the relevant registry guidance, prepare a change plan for [outcome].
Include prerequisites, permissions, tenant-specific checks, rollback, validation,
and the exact point where explicit write authorization is required.

Review a configuration or response

Review the sanitized [JSON / formula / API response] below.
Route to the appropriate skill, identify the most likely failure layer,
and separate documented behavior from inference.

Use it safely in production

The registry improves judgment; it does not replace environment verification.

Prefer read-only inspection before proposing or performing a change.
Verify tenant metadata, product version, feature enablement, permissions, and limits live.
Treat publish, import, promotion, permission, and mutation operations as production actions.
Use least-privilege credentials and never paste secrets into prompts or notebook references.
Retain source links and clearly mark any recommendation that is inferred rather than documented.

Troubleshooting the setup

Symptom	Check
The plugin does not load	Use the repository's absolute path and run `claude plugin validate . --strict` from its root.
A skill command is not found	Use the current namespace: `/apptio-skills-registry:<skill-name>`. Reload after local changes.
Kiro does not list the workspace skills	Start `kiro-cli chat` from the repository root, run `/context show`, and confirm that `.kiro/skills/*/SKILL.md` matches 36 files.
A Kiro skill slash command is rejected	Use the command inside interactive `kiro-cli chat`. In headless mode, submit the task as a plain-language prompt instead of a slash command.
Copilot answers from older guidance	Rebuild the `.docx` set, remove the old notebook references, upload the new files, and retry a known-answer prompt.
Notebook answers are too broad	Reduce the reference set to one product or task family and name that scope in the prompt.
A source link looks valid but opens a not-found page	Run `python3 tools/check_sources.py`; IBM documentation redirects can return HTTP 200 while landing on an error page.
Guidance conflicts with the tenant	Treat the documentation as a pattern, verify live version and tenant behavior, and record the difference before proceeding.

Extend the registry

The packaged authoring command surveys another IBM documentation tree, decomposes it into focused tasks, creates source-linked skills and references, validates coverage, generates its Copilot Notebook pack, and wires the portable copies into Claude Code and Kiro.

/apptio-skills-registry:new-skill-registry \
  <ibm-docs-root-url> <short-name> [skill-prefix]

Use the existing registries as the format contract and review the generated decomposition before treating it as production-ready knowledge.