feat: migrate skills review desk to astro
This commit is contained in:
Marcos Paulo
@@ -0,0 +1,68 @@
|
||||
# Attachments
|
||||
|
||||
Attachments live on a page and are referenced by filename. They survive page
|
||||
moves and template changes, but they do not survive page deletion.
|
||||
|
||||
## Upload via mcp-atlassian
|
||||
|
||||
```python
|
||||
mcp__atlassian.confluence_upload_attachment(
|
||||
pageId=…,
|
||||
filePath="path/to/file.png",
|
||||
comment="optional version note",
|
||||
)
|
||||
```
|
||||
|
||||
Returns a metadata object including the download URL. Use that URL inside the
|
||||
page body, not a local file path.
|
||||
|
||||
## Reference in the body
|
||||
|
||||
By attachment filename:
|
||||
|
||||
```xml
|
||||
<ac:link>
|
||||
<ri:attachment ri:filename="diagram.png" />
|
||||
<ac:plain-text-link-body><![CDATA[diagram]]></ac:plain-text-link-body>
|
||||
</ac:link>
|
||||
```
|
||||
|
||||
As an inline image:
|
||||
|
||||
```xml
|
||||
<ac:image ac:width="600">
|
||||
<ri:attachment ri:filename="diagram.png" />
|
||||
</ac:image>
|
||||
```
|
||||
|
||||
Always set `ac:alt` for accessibility:
|
||||
|
||||
```xml
|
||||
<ac:image ac:width="600">
|
||||
<ri:attachment ri:filename="diagram.png" />
|
||||
<ac:alt>Sequence diagram of the order → inventory → shipment flow.</ac:alt>
|
||||
</ac:image>
|
||||
```
|
||||
|
||||
## What NOT to do
|
||||
|
||||
- Don't paste base64 PNG into the body. The page editor can't replace it
|
||||
without re-rendering the whole page; it bloats the storage body; the page
|
||||
cannot be reviewed by lint.
|
||||
- Don't link to a public CDN. BASS pages are private; CDN URLs leak and break
|
||||
on access-controlled spaces.
|
||||
- Don't re-upload the same file under a new name. Confluence deduplicates by
|
||||
hash within a page, but the editor doesn't surface duplicates well.
|
||||
|
||||
## Versioning
|
||||
|
||||
Attach with a version suffix (`diagram-v2.png`) when updating. Confluence
|
||||
keeps the old version in the attachments list and the page body continues to
|
||||
reference the filename; change the filename in the body to point at the new
|
||||
version.
|
||||
|
||||
## Cleanup
|
||||
|
||||
Pages with stale attachments show up in the space's attachment report. When
|
||||
removing a diagram, also remove the attachment (do not leave orphaned files
|
||||
on the page).
|
||||
@@ -0,0 +1,112 @@
|
||||
# Confluence Storage Macros
|
||||
|
||||
Confluence Cloud storage format accepts a fixed set of macros. Anything not in
|
||||
this catalog either renders as plain text or fails silently. Before adding a
|
||||
new macro to a draft, check the name here.
|
||||
|
||||
## Inline
|
||||
|
||||
| Macro | When |
|
||||
|-------|------|
|
||||
| `{code}` | Fenced code with optional language |
|
||||
| `{plantuml}` | Diagrams — see `diagram-plantuml` skill |
|
||||
| `{info}` | Info panel |
|
||||
| `{note}` | Note panel |
|
||||
| `{warning}` | Warning panel |
|
||||
| `{tip}` | Tip panel |
|
||||
| `{excerpt}` | Reusable fragment; also `excerpt-include` |
|
||||
| `{anchor}` | Inline anchor for `{pageref}` |
|
||||
| `{pageref}` | Cross-page reference by anchor |
|
||||
| `{children}` | Lists child pages |
|
||||
| `{include}` | Includes another page (full or excerpt) |
|
||||
| `{table-of-content}` | Outline from heading hierarchy |
|
||||
| `{expand}` | Collapsible section |
|
||||
| `{status}` | Coloured status pill |
|
||||
| `{cheese}` | Image gallery — prefer `image` element instead |
|
||||
| `{noformat}` | Plain monospace, no language hint |
|
||||
|
||||
## Panels
|
||||
|
||||
Panels take rich-text bodies. PlantUML inside a panel does not render — put
|
||||
diagrams at body root.
|
||||
|
||||
```xml
|
||||
<ac:structured-macro ac:name="info">
|
||||
<ac:rich-text-body>
|
||||
<p>Body goes here.</p>
|
||||
</ac:rich-text-body>
|
||||
</ac:structured-macro>
|
||||
```
|
||||
|
||||
Available panel macros: `info`, `note`, `warning`, `tip`, `success`,
|
||||
`error`, `panel` (generic).
|
||||
|
||||
## Code block
|
||||
|
||||
```xml
|
||||
<ac:structured-macro ac:name="code">
|
||||
<ac:parameter ac:name="language">python</ac:parameter>
|
||||
<ac:parameter ac:name="title">example.py</ac:parameter>
|
||||
<ac:parameter ac:name="linenumbers">true</ac:parameter>
|
||||
<ac:plain-text-body><![CDATA[def hello():
|
||||
pass]]></ac:plain-text-body>
|
||||
</ac:structured-macro>
|
||||
```
|
||||
|
||||
`language` accepts the short names from Confluence's language list (`python`,
|
||||
`java`, `javascript`, `typescript`, `go`, `bash`, `sql`, `json`, `yaml`,
|
||||
`xml`, `markdown`). Anything outside the list falls back to plain monospace.
|
||||
|
||||
## Tables
|
||||
|
||||
Standard XHTML tables. Confluence does not need the `<ac:structured-macro
|
||||
ac:name="table">` wrapper for plain tables.
|
||||
|
||||
```xml
|
||||
<table>
|
||||
<tbody>
|
||||
<tr>
|
||||
<th>Column A</th>
|
||||
<th>Column B</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>cell</td>
|
||||
<td>cell</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
```
|
||||
|
||||
For sortable or filterable tables, use the `table-plus` macro — but only
|
||||
when the table is genuinely worth the overhead.
|
||||
|
||||
## Links
|
||||
|
||||
- External: `<a href="https://…">label</a>`
|
||||
- Page by title: `<ac:link><ri:page ri:content-title="Hub"/></ac:link>`
|
||||
- Page by id: `<ac:link><ri:page ri:content-id="12345"/></ac:link>`
|
||||
- Attachment: `<ac:link><ri:attachment ri:filename="diagram.png"/></ac:link>`
|
||||
- User mention: `<ac:link><ri:user ri:username="marcos"/></ac:link>`
|
||||
|
||||
## Attachments
|
||||
|
||||
Attachments go through `mcp__atlassian.confluence_upload_attachment` /
|
||||
`confluence_create_page_from_file` (with the file path) — never as base64 in
|
||||
the body. See `attachments.md`.
|
||||
|
||||
## What is NOT a macro
|
||||
|
||||
| Construct | Status |
|
||||
|-----------|--------|
|
||||
| Wiki markup (`{code}…{code}`) | Renders only on pages whose renderer is set to wiki; do not assume |
|
||||
| Markdown fences | Not interpreted; render as text |
|
||||
| HTML5 `<details>` | Rendered as plain HTML; works but no styling |
|
||||
| Inline SVG | Works but is not editable through the page editor; prefer PlantUML |
|
||||
| `<script>` / `<iframe>` | Stripped by Confluence; do not bother |
|
||||
|
||||
## Naming conventions
|
||||
|
||||
- Macro names are lowercase.
|
||||
- Parameter names are lowercase with words separated by `-`, not `_`
|
||||
(`linenumbers`, not `line_numbers`).
|
||||
- Parameter values that include spaces must be quoted.
|
||||
@@ -0,0 +1,52 @@
|
||||
# Secrets and PII
|
||||
|
||||
A draft that contains any of the patterns below is **BLOCKED** by the
|
||||
`page-reviewer` skill. Scrub before posting; the reviewer's verdict is not
|
||||
overridden by "this is a test fixture" or "this is obvious from context".
|
||||
|
||||
## Hard blocks
|
||||
|
||||
| Pattern | Example | Action |
|
||||
|---------|---------|--------|
|
||||
| AWS access key id | `AKIA[0-9A-Z]{16}` | Replace with `<AWS_KEY>` |
|
||||
| AWS secret access key | `[A-Za-z0-9/+=]{40}` in env files | Replace with `<AWS_SECRET>` |
|
||||
| Bearer / personal token | `ghp_…`, `glpat-…`, `dapi…` | Replace with `<TOKEN>` |
|
||||
| Confluence / Jira token | `ATATT…` (Cloud), long base64 | Replace with `<CONFLUENCE_TOKEN>` |
|
||||
| Slack token | `xoxb-…`, `xoxp-…` | Replace with `<SLACK_TOKEN>` |
|
||||
| OpenAI key | `sk-…` (40+ chars after) | Replace with `<OPENAI_KEY>` |
|
||||
| Service-account password | any string in `*.password=…`, `secret: …` | Replace |
|
||||
| PEM private key | `-----BEGIN … PRIVATE KEY-----` | Replace |
|
||||
| Cookie value | `connect.sid=…`, `JSESSIONID=…` | Replace |
|
||||
|
||||
## Soft blocks (review)
|
||||
|
||||
| Pattern | Why | Action |
|
||||
|---------|-----|--------|
|
||||
| Customer email | PII | Mask: `j***@example.com` or remove |
|
||||
| Customer hostname / IP | PII + internal info | Replace with `<HOST>` / `<IP>` |
|
||||
| Runbook hostname (`*.k8s.sdntest.netcracker.com`) | Internal surface | Use the public URL or `<INTERNAL_HOST>` |
|
||||
| Phone number | PII | Mask or remove |
|
||||
| Bank / payment info | PII | Remove |
|
||||
|
||||
## Why this is in the skill
|
||||
|
||||
BASS Confluence is private to Netcracker, but watchers, exported PDFs, and
|
||||
incident write-ups leak. Pages are also exported to training data when teams
|
||||
mirror content into LLMs. "It's on a private space" is not enough.
|
||||
|
||||
## If you need a realistic-looking fixture
|
||||
|
||||
Generate one with the project's placeholder vocabulary:
|
||||
|
||||
- emails: `user1@example.com`, `user2@example.com`
|
||||
- IPs: `10.0.0.1`, `192.0.2.1`
|
||||
- tokens: `<TOKEN>`, `<SECRET>`
|
||||
- hostnames: `host-a.internal`, `host-b.internal`
|
||||
|
||||
Do not use the customer's name, the production hostname, or a real-looking
|
||||
token "because it doesn't matter".
|
||||
|
||||
## What the reviewer checks
|
||||
|
||||
The `page-reviewer` skill runs a grep pass against this list. A single hit
|
||||
returns **BLOCK**; the author fixes the draft and re-runs.
|
||||
@@ -0,0 +1,25 @@
|
||||
# BASS Space Keys
|
||||
|
||||
The BASS / AVP space keys used by `mcp__atlassian.confluence_*` calls.
|
||||
|
||||
| Space key | Name | Use it for |
|
||||
|-----------|------|------------|
|
||||
| `AVP` | NDO space | NDO product docs, hub pages, runbooks |
|
||||
| `BASS` | Netcracker Confluence | Internal team / governance / how-to / Cursor / MCP pages |
|
||||
| `NDO` | (legacy) | Old NDO content; new writes go to `AVP` |
|
||||
| `GF` | GFiber space | GFiber product content; the gfiber-logging skill targets here |
|
||||
| `NCM` | NCM space | NCM product content |
|
||||
| `~seby0316` | Personal space | Sebastián; the Cursor MCPs page lives here |
|
||||
|
||||
When in doubt, search for a similar page and use the same one. The mirror
|
||||
index at `~/Netcracker/Projects/NDO/knowledge/confluence/_index.md` lists the
|
||||
spaces already in use locally.
|
||||
|
||||
## Picking a space
|
||||
|
||||
- **Top-level product page** → the product space (`AVP` for NDO).
|
||||
- **Internal how-to / governance / Cursor / MCP** → `BASS`.
|
||||
- **Customer-facing release notes** → check with the page owner; the
|
||||
default is `doc.netcracker.com` not BASS.
|
||||
- **Personal scratch** → do not post to BASS / AVP; keep in
|
||||
`~/Netcracker/Projects/NDO/knowledge/confluence/drafts/`.
|
||||
Reference in New Issue
Block a user