How the Shipping-Artifacts Skill Documents AI-Built Applications for Review

The shipping-artifacts skill generates a structured markdown artifact that captures application overview, version history, architecture, and security audit results, writing it to a review-ready document in the project's docs folder.

The shipping-artifacts skill is part of the pm-ai-shipping collection in the phuryn/pm-skills repository. It standardizes documentation for AI-generated applications by prompting the LLM to gather essential metadata and assembling the results into a consistent markdown format. This ensures reviewers receive a complete picture of what the application does, how it was built, and what checks have been run.

Invocation Through the document-app Command

The skill is triggered via the document-app command defined in pm-ai-shipping/commands/document-app.md. When executed, this CLI wrapper initiates the prompt flow and handles file output operations.

To generate an artifact from the terminal, run:

pm-ai-shipping document-app \
  --app-name "SmartTicket" \
  --output docs/smartticket-artifact.md

The command launches the shipping-artifacts skill, gathers the required details from the LLM, and writes a ready-to-review markdown file to the specified path.

Artifact Structure and Content Sections

The markdown document generated by the shipping-artifacts skill follows a standardized layout defined in pm-ai-shipping/skills/shipping-artifacts/SKILL.md. This structure ensures consistency across all AI-built applications in the repository.

Application Overview and Target Users

The skill prompts the LLM for a concise description of the application's purpose and its intended user base. This section provides reviewers with immediate context about the business logic and functionality without requiring them to parse source code.

Version Tracking and Changelog

The artifact includes the current version number and a short list of recent changes. This historical tracking allows reviewers to quickly identify what has changed since the last review and assess the scope of the current iteration.

Architecture and External Dependencies

The skill documents key components including architecture diagrams, data sources, and any external services integrated into the application. This transparency helps reviewers evaluate system dependencies and potential points of failure.

Security and Compliance Integration

Critical audit results from sibling skills are incorporated into the documentation. The skill references outputs from security-audit-static and performance-audit-static, including their findings in the Audit Results section of the final document.

Output Generation and File Handling

Once the LLM provides all required information, the skill assembles the content into a markdown file with sections for Summary, Version, Architecture, Audit Results, and Next Steps.

By default, the document is written to the project's docs/ folder. The CLI prints a direct link to the created file upon completion, enabling reviewers to open the artifact immediately from the terminal output.

Integration with Review Pipelines

Because the generated artifact includes standardized audit results and a changelog, downstream review tools can automatically ingest the markdown. Code-review bots and PR templates can parse the document to surface information in pull request descriptions or review checklists.

For example, you can reference the artifact in a PR template:

## AI-Built Application Review

**Artifact:** [SmartTicket Artifact](docs/smartticket-artifact.md)

- Architecture verified
- Security audit passed
- Performance benchmarks reviewed

This creates a single source of truth that links the technical implementation to its documented review criteria.

Summary

• The shipping-artifacts skill in phuryn/pm-skills generates structured markdown documentation for AI-built applications through the document-app command.
• The artifact includes application overview, version history, architecture details, and integration with security-audit-static and performance-audit-static results.
• Output is written to the docs/ folder by default, with CLI output providing a direct link to the review-ready file.
• The standardized format enables automated ingestion by PR templates and code-review bots, streamlining the review pipeline.

Frequently Asked Questions

What file format does the shipping-artifacts skill generate?

The skill generates a markdown document that follows the layout defined in pm-ai-shipping/skills/shipping-artifacts/SKILL.md. This format includes sections for Summary, Version, Architecture, Audit Results, and Next Steps, making it readable both in raw form and rendered in GitHub or other markdown viewers.

How does the shipping-artifacts skill integrate with security audits?

The skill references outputs from sibling skills security-audit-static and performance-audit-static when assembling the documentation. These audit results are included in the Audit Results section of the generated artifact, ensuring reviewers have immediate access to security and performance validation data.

Where does the shipping-artifacts skill save the generated documentation?

By default, the skill writes the markdown file to the project's docs/ folder. However, users can specify a custom output path using the --output flag in the document-app command, allowing flexibility for different project structures.

Can I customize the output path for the generated artifact?

Yes. When invoking the document-app command, provide the --output parameter followed by your desired file path. For example, pm-ai-shipping document-app --app-name "MyApp" --output reviews/myapp-v2.md writes the artifact to a custom location while maintaining the same standardized content structure.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}