# Manage Repository Document IDs

Teams lose trust in documentation when IDs drift, references break, or metadata changes without review. Shirushi gives Claude, Codex, and Claude Code workflows for validating, assigning, and tracking immutable document IDs.

## Install

```bash
npx skillstore add caphtech/shirushi
```

## Metadata

- - Slug: caphtech-shirushi
- - Version: 1.0.0
- - Author: CAPHTECH
- - GitHub username: CAPHTECH
- - License: MIT
- - Repository: https://github.com/CAPHTECH/shirushi/tree/main/skills/shirushi
- - Ref: main
- - Supported tools: Claude, Codex, Claude Code
- - Risk level: medium
- - Risk factors: external\_commands
- - Quality score: 73
- - Public page: https://skillstore.pages.dev/skills/caphtech-shirushi
- - Manifest: https://skillstore.pages.dev/api/skills/caphtech-shirushi/manifest

## Capabilities

- Validate doc\_id values and index integrity with shirushi lint.
- List repository documents and metadata with shirushi scan.
- Look up a document by immutable doc\_id with shirushi show.
- Assign document IDs to new Markdown or YAML files.
- Recalculate content hashes and check doc\_id references.

## Use Cases

- Validate documentation before merge: Run doc\_id and reference checks before a pull request is merged.
- Assign IDs to new specifications: Add stable document IDs to new Markdown files using the repository format.
- Trace references during code review: Find the document behind an @see docid reference and review related metadata.

## Prompt Templates

### Check document IDs

```
Use the Shirushi skill to validate document IDs in this repository. Run the safest lint command first and summarize any issues.
```

### Find one document

```
Use Shirushi to find document API-SPEC-2025-0001-G. Report the document path, title, type, and any reference warnings.
```

### Prepare new documents

```
Use Shirushi to assign doc_ids to new files under docs/. Show the commands you plan to run, then review the resulting Git diff.
```

### Audit a pull request

```
Use Shirushi to lint this branch against origin/main with reference checks. Group findings by broken IDs, changed hashes, and missing references.
```

## Limitations

- Requires the shirushi CLI to be installed and available in the repository environment.
- Only covers repositories that use the documented Shirushi configuration and frontmatter format.
- Mutating commands can change files and should be reviewed with Git diffs.
- Does not provide the Shirushi implementation or CI configuration by itself.

## Best Practices

- Run lint before committing documentation changes.
- Review Git diffs after assign or rehash commands.
- Keep .shirushi.yml aligned with repository document types.

## Anti Patterns

- Do not run mutating commands without checking the working tree first.
- Do not treat check digits as cryptographic integrity protection.
- Do not manually rewrite immutable doc\_ids after publication.

## Security Audit

- - Safe to publish: true
- - Audited at: 2026-06-28T20:21:27.33\+00:00
- - Summary: Static analysis flagged many backtick examples as Ruby or shell execution, but the file is Markdown documentation for a CLI workflow. No malicious intent, network access, credential handling, or prompt injection was found. Risk remains medium because the skill directs agents to run external commands that can inspect and modify repository files.

## Stats

- - Views: 192
- - Downloads: 4
- - Favorites: 0
- - Popularity score: 0