docs: update README quickstart and skills install#7
Conversation
Summary of ChangesHello @venikman, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly updates the project's primary documentation, the Highlights
🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console. Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
|
Note Other AI code review bot(s) detectedCodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review. 📝 WalkthroughWalkthroughREADME.md rewritten to replace a CLI-first quickstart with an artifact- and workflow-focused guide, adding explicit artifact paths, runnable skill demos (Mint a Name, Record a DRR, Log Work), expanded installation/setup and validation guidance, and reorganized downstream sections and safety gates. Changes
Sequence Diagram(s)(omitted — changes are documentation-focused and do not introduce a new multi-component control flow) Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. 🧹 Recent nitpick comments
📜 Recent review detailsConfiguration used: defaults Review profile: CHILL Plan: Pro 📒 Files selected for processing (1)
🧰 Additional context used🪛 LanguageToolREADME.md[style] ~3-~3: Try using a descriptive adverb here. (ON_PURPOSE_DELIBERATELY) 🪛 markdownlint-cli2 (0.18.1)README.md53-53: Fenced code blocks should have a language specified (MD040, fenced-code-language) 77-77: Fenced code blocks should have a language specified (MD040, fenced-code-language) 100-100: Fenced code blocks should have a language specified (MD040, fenced-code-language) 🔇 Additional comments (1)
✏️ Tip: You can disable this entire section by setting Comment |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request significantly improves the README by adding a detailed quickstart guide, examples for using skills, and instructions for integrating with Claude and Codex. The new documentation is much more comprehensive and helpful for new users. I've identified a couple of minor inconsistencies and ambiguities in the new documentation that could be clarified.
| cp -R .codex/skills/<skill> "$CODEX_SKILLS_DIR/" | ||
| cp -R .codex/skills/<skill> ~/.claude/skills/ |
There was a problem hiding this comment.
The <skill> placeholder is ambiguous. It's unclear what a user should substitute here. Is it the skill ID (e.g., design/mint-name) or a flattened name? This is especially confusing since skill IDs can contain slashes, which would be interpreted as path separators.
For clarity, please consider:
- Explaining what
<skill>represents (e.g., the directory name of the skill package). - Providing a concrete example of a skill name.
- Adding instructions for installing all skills at the user level, similar to the repo-local example that uses
*, for users who might want to do so.
| Mint a Name Card via Codex skill (`.codex/skills`): | ||
|
|
||
| ```text | ||
| Use $design-mint-name to mint a Name Card: |
There was a problem hiding this comment.
The skill name $design-mint-name seems inconsistent with the other Codex prompt examples, which use a slash as a separator (e.g., $design/record-drr, $telemetry/log-work). Based on the skill IDs in skill.json files, it should likely be $design/mint-name to maintain consistency.
| Use $design-mint-name to mint a Name Card: | |
| Use $design/mint-name to mint a Name Card: |
|
Codex Review: Didn't find any major issues. Bravo. ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
There was a problem hiding this comment.
Pull request overview
This PR restores and expands the README with comprehensive documentation for FPF Foundry's skill-based workflow system. It provides practical quickstart instructions, detailed skill usage examples, and installation guides for both Codex and Claude AI assistants.
Changes:
- Added skills overview section explaining the practical outputs (Name Cards, DRRs, U.Work records)
- Added bunx quickstart with JSON mode examples for machine-readable output
- Documented skill installation for
.claudeand.codexdirectories withCODEX_HOMEenvironment variable support
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| --spec "A.15.1" \ | ||
| --role "Archivist" \ |
There was a problem hiding this comment.
The parameter names used in this example are inconsistent with the canonical names used elsewhere in the documentation. The log-work script accepts --spec as an alias for --method and --role as an alias for --role-assignment for backward compatibility, but for consistency with other examples and the primary interface, consider using --method instead of --spec and --role-assignment instead of --role.
| --spec "A.15.1" \ | |
| --role "Archivist" \ | |
| --method "A.15.1" \ | |
| --role-assignment "Archivist" \ |
README.md
Outdated
|
|
||
| SkillSpec (machine-readable): design/skills/**/skill.json | ||
|
|
||
| Skill doc (human-facing, optional but expected for non-none): design/skills/**/SKILL.md (frontmatter is used by tooling) |
There was a problem hiding this comment.
The phrase "optional but expected for non-none" is unclear and awkward. Consider revising to something clearer like "optional but recommended for most skills" or "optional except for basic/stub skills" to better convey the expectation.
| Skill doc (human-facing, optional but expected for non-none): design/skills/**/SKILL.md (frontmatter is used by tooling) | |
| Skill doc (human-facing, optional but recommended for most skills): design/skills/**/SKILL.md (frontmatter is used by tooling) |
| runtime/contexts/Tooling/design/names/fpf-foundry.md | ||
|
|
||
| runtime/contexts/Tooling/telemetry/work/work-<timestamp>.md (via telemetry/log-work) | ||
|
|
There was a problem hiding this comment.
The output file paths should be consistently formatted. Consider using code formatting (backticks) or consistent indentation for all output file paths to match the structured format used elsewhere in the examples (e.g., lines 77-79 show a structured format, while these lines show bare paths).
| runtime/contexts/Tooling/design/names/fpf-foundry.md | |
| runtime/contexts/Tooling/telemetry/work/work-<timestamp>.md (via telemetry/log-work) | |
| - `runtime/contexts/Tooling/design/names/fpf-foundry.md` | |
| - `runtime/contexts/Tooling/telemetry/work/work-<timestamp>.md` (via telemetry/log-work) |
|
Addressed review nits:
|
Summary
Testing
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.